Next: , Previous: , Up: The basic curses library   [Contents][Index]

5.2.27 Mouse handling

These functions provide an interface to mouse events. Mouse events are represented by KEY_MOUSE pseudo-key values in the wgetch input stream.

To make mouse events visible, use the mousemask function.

Procedure: has-mouse?

Returns #t if the mouse driver has been successfully installed.

This procedure is only present if the underlying version of ncurses supports it.

Procedure: mousemask mask

This will set the mouse events to be reported. By default, no mouse events are reported. The function will return a mask to indicate which of the specified mouse events can be reported; on complete failure it returns 0.

As a side effect, setting a zero mousemask may turn off the mouse pointer; setting a nonzero mask may turn it on. Whether this happens is device-dependent.

See Table 5.5 for the mouse event types mask that may be defined.

BUTTON1_PRESSEDmouse button 1 down
BUTTON1_RELEASEDmouse button 1 up
BUTTON1_CLICKEDmouse button 1 clicked
BUTTON1_DOUBLE_CLICKEDmouse button 1 double clicked
BUTTON1_TRIPLE_CLICKEDmouse button 1 triple clicked
BUTTON2_PRESSEDmouse button 2 down
BUTTON2_RELEASEDmouse button 2 up
BUTTON2_CLICKEDmouse button 2 clicked
BUTTON2_DOUBLE_CLICKEDmouse button 2 double clicked
BUTTON2_TRIPLE_CLICKEDmouse button 2 triple clicked
BUTTON3_PRESSEDmouse button 3 down
BUTTON3_RELEASEDmouse button 3 up
BUTTON3_CLICKEDmouse button 3 clicked
BUTTON3_DOUBLE_CLICKEDmouse button 3 double clicked
BUTTON3_TRIPLE_CLICKEDmouse button 3 triple clicked
BUTTON4_PRESSEDmouse button 4 down
BUTTON4_RELEASEDmouse button 4 up
BUTTON4_CLICKEDmouse button 4 clicked
BUTTON4_DOUBLE_CLICKEDmouse button 4 double clicked
BUTTON4_TRIPLE_CLICKEDmouse button 4 triple clicked
BUTTON5_PRESSEDmouse button 5 down
BUTTON5_RELEASEDmouse button 5 up
BUTTON5_CLICKEDmouse button 5 clicked
BUTTON5_DOUBLE_CLICKEDmouse button 5 double clicked
BUTTON5_TRIPLE_CLICKEDmouse button 5 triple clicked
BUTTON_SHIFTshift was down during button state change
BUTTON_CTRLcontrol was down during button state change
BUTTON_ALTalt was down during button state change
ALL_MOUSE_EVENTSreport all button state changes
REPORT_MOUSE_POSITIONreport mouse movement

Table 5.5: Mouse mask constants

Once a class of mouse events have been made visible in a window, calling the wgetch function on that window may return KEY_MOUSE as an indicator that a mouse event has been queued. To read the event data and pop the event off the queue, call getmouse.

Procedure: getmouse

This will return either a list of mouse information, or #f. If it does return a list, it will have the following form:

(id                             ; id to distinguish multiple devices
x y z                           ; event coordinates
bstate)                         ; button state bits

When getmouse returns a list, the data deposited as y and x in the list will be screen-relative character-cell coordinates. The returned state mask will have exactly one bit set to indicate the event type.

Procedure: ungetmouse mouse-event

The ungetmouse function behaves analogously to ungetch. It pushes a KEY_MOUSE event onto the input queue, and associates with that event the given state data and screen-relative character-cell coordinates in the mouse-event list, where mouse-event is a list of five elements as described above.

Procedure: mouse-trafo win y x to-screen

The mouse-trafo function transforms a given pair of coordinates y, x from stdscr-relative coordinates to coordinates relative to the given window win or vice versa. Please remember, that stdscr-relative coordinates are not always identical to window-relative coordinates due to the mechanism to reserve lines on top or bottom of the screen for other purposes (see slk-init, for example). If the parameter to-screen is #t, the procedure returns either a list of two elements (y, x) which is the location inside the window win, or #f if the location was not inside the window. If to-screen is #f, the return a list of two elements of where the window-relative location y, x would be in stdscr-relative coordinates.

The mouse-trafo procedure performs the same translation as wmouse-trafo, using stdscr for win.

Procedure: wenclose? win y x

The wenclose? function tests whether a given pair of screen-relative character-cell coordinates is enclosed by the given window win, returning #t if it is and #f otherwise. It is useful for determining what subset of the screen windows enclose the location of a mouse event.

Procedure: mouseinterval erval

The mouseinterval function sets the maximum time (in thousands of a second) that can elapse between press and release events for them to be recognized as a click. Use (mouseinterval 0) to disable click resolution. This function returns the previous interval value. Use (mouseinterval -1) to obtain the interval without altering it. The default is one sixth of a second.

Next: , Previous: , Up: The basic curses library   [Contents][Index]