NAME¶

has_mouse, getmouse, ungetmouse, mousemask, wenclose, mouse_trafo, wmouse_trafo, mouseinterval - get mouse events in curses

SYNOPSIS¶

#include <ncursesw/curses.h>

typedef unsigned long mmask_t;

typedef struct {
    short id;         /* ID to distinguish multiple devices */
    int x, y, z;      /* event coordinates */
    mmask_t bstate;   /* button state bits */
} MEVENT;

bool has_mouse(void);

mmask_t mousemask(mmask_t newmask, mmask_t *oldmask);

int getmouse(MEVENT *event);
int ungetmouse(MEVENT *event);

bool wenclose(const WINDOW *win, int y, int x);

bool mouse_trafo(int* pY, int* pX, bool to_screen);
bool wmouse_trafo(const WINDOW* win,
int* pY, int* pX, bool to_screen);

int mouseinterval(int erval);

DESCRIPTION¶

These functions provide an interface to mouse events from ncurses(3NCURSES). Mouse events are represented by KEY_MOUSE pseudo-key values in the wgetch(3NCURSES) input stream.

RETURN VALUE¶

has_mouse, wenclose, mouse_trafo, and wmouse_trafo return TRUE or FALSE as noted above.

getmouse and ungetmouse return ERR upon failure and OK upon success.

getmouse fails if:

• no mouse driver was initialized,
• the mask of reportable events is zero,
• a mouse event was detected that does not match the mask,
• or if no more events remain in the queue.

ungetmouse returns ERR if the event queue is full.

mousemask returns the mask of reportable events.

mouseinterval returns the previous interval value, unless the terminal was not initialized. In that case, it returns the maximum interval value (166).

NOTES¶

The order of the MEVENT structure members is not guaranteed. Additional fields may be added to the structure in the future.

Under ncurses, these calls are implemented using either xterm's built-in mouse-tracking API or platform-specific drivers including

If you are using an unsupported configuration, mouse events will not be visible to ncurses (and the mousemask function will always return 0).

If the terminfo entry contains a XM string, this is used in the xterm mouse driver to control the way the terminal is initialized for mouse operation. The default, if XM is not found, corresponds to private mode 1000 of xterm:

The mouse driver also recognizes a newer xterm private mode 1006, e.g.,

The z member in the event structure is not presently used. It is intended for use with touch screens (which may be pressure-sensitive) or with 3D-mice/trackballs/power gloves.

The ALL_MOUSE_EVENTS class does not include REPORT_MOUSE_POSITION. They are distinct. For example, in xterm, wheel/scrolling mice send position reports as a sequence of presses of buttons 4 or 5 without matching button-releases.

EXTENSIONS¶

These functions were designed for ncurses(3NCURSES), and are not found in SVr4 curses, 4.4BSD curses, or any other previous curses implementation. (SVr4 curses did have a getmouse function, which took no argument and returned a different type.)

PORTABILITY¶

Applications employing the ncurses mouse extension should condition its use on the visibility of the NCURSES_MOUSE_VERSION preprocessor macro. When the interface changes, the macro's value increments. Multiple versions are available when ncurses is configured; see section “ALTERNATE CONFIGURATIONS” of ncurses(3NCURSES). The following values may be specified.

SVr4 curses had support for the mouse in a variant of xterm(1). It is mentioned in a few places, with little supporting documentation.

•

Its “libcurses” manual page lists functions for this feature prototyped in curses.h.

extern int mouse_set(long int);
extern int mouse_on(long int);
extern int mouse_off(long int);
extern int request_mouse_pos(void);
extern int map_button(unsigned long);
extern void wmouse_position(WINDOW *, int *, int *);
extern unsigned long getmouse(void), getbmap(void);

•

Its “terminfo” manual page lists capabilities for the feature.

•

The interface made assumptions (as does ncurses) about the escape sequences sent to and received from the terminal.

For instance, the SVr4 curses library used the get_mouse capability to tell the terminal which mouse button events it should send, passing the mouse-button bit mask to the terminal. Also, it could ask the terminal where the mouse was using the req_mouse_pos capability.

Those features required a terminal program that had been modified to work with SVr4 curses. They were not part of the X Consortium's xterm.

When developing the xterm mouse support for ncurses in September 1995, Eric Raymond was uninterested in using the same interface due to its lack of documentation. Later, in 1998, Mark Hesseling provided support in PDCurses 2.3 using the SVr4 interface. PDCurses, however, does not use video terminals, making it unnecessary to be concerned about compatibility with the escape sequences.

BUGS¶

Mouse events from xterm are not ignored in cooked mode if they have been enabled by mousemask. Instead, the xterm mouse report sequence appears in the string read.

An ncurses window must enable keypad(3NCURSES) to correctly receive mouse event reports from xterm since they are encoded like function keys. Set the terminal's terminfo capability kmous to “\E[M” (the beginning of the response from xterm for mouse clicks). Other values of kmous are permitted under the same assumption, that is, the report begins with that sequence.

Because there are no standard response sequences that serve to identify terminals supporting the xterm mouse protocol, ncurses assumes that if kmous is defined in the terminal description, or if the terminal type's primary name or aliases contain the string “xterm”, then the terminal may send mouse events. The kmous capability is checked first, allowing use of newer xterm mouse protocols, such as its private mode 1006.

SEE ALSO¶

ncurses(3NCURSES), inopts(3NCURSES), kernel(3NCURSES), pad(3NCURSES), slk(3NCURSES), curses_variables(3NCURSES)