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.

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.