diff options
Diffstat (limited to 'lib/libcurses/curs_mouse.3')
| -rw-r--r-- | lib/libcurses/curs_mouse.3 | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/lib/libcurses/curs_mouse.3 b/lib/libcurses/curs_mouse.3 new file mode 100644 index 00000000000..4781f99bed8 --- /dev/null +++ b/lib/libcurses/curs_mouse.3 @@ -0,0 +1,151 @@ +'\" t +.TH curs_mouse 3X "" +.SH NAME +\fBgetmouse\fR, \fBungetmouse\fR, +\fBmousemask\fR - mouse interface through curses +.SH SYNOPSIS +.nf +\fB#include <curses.h>\fR + +\fBtypedef unsigned long mmask_t; + +typedef struct +{ + short id; \fI/* ID to distinguish multiple devices */\fB + int x, y, z; \fI/* event coordinates */\fB + mmask_t bstate; \fI/* button state bits */\fB +} +MEVENT;\fR +.fi +.br +\fBint getmouse(MEVENT *event);\fR +.br +\fBint ungetmouse(MEVENT *event);\fR +.br +\fBmmask_t mousemask(mmask_t newmask, mmask_t *oldmask);\fR +.br +\fBbool wenclose(WINDOW *win, int y, int x)\fR +.br +\fBint mouseinterval(int erval)\fR +.br +.SH DESCRIPTION +These functions provide an interface to mouse events from +\fBcurses\fR(3x). Mouse events are represented by \fBKEY_MOUSE\fR +pseudo-key values in the \fBwgetch\fR input stream. + +To make mouse events visible, use the \fBmousemask\fR function. 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. If oldmask is non-NULL, +this function fills the indicated location with the previous value of the given +window's mouse event mask. + +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. + +Here are the mouse event type masks: + +.TS +l l +_ _ +l l. +\fIName\fR \fIDescription\fR +BUTTON1_PRESSED mouse button 1 down +BUTTON1_RELEASED mouse button 1 up +BUTTON1_CLICKED mouse button 1 clicked +BUTTON1_DOUBLE_CLICKED mouse button 1 double clicked +BUTTON1_TRIPLE_CLICKED mouse button 1 triple clicked +BUTTON2_PRESSED mouse button 2 down +BUTTON2_RELEASED mouse button 2 up +BUTTON2_CLICKED mouse button 2 clicked +BUTTON2_DOUBLE_CLICKED mouse button 2 double clicked +BUTTON2_TRIPLE_CLICKED mouse button 2 triple clicked +BUTTON3_PRESSED mouse button 3 down +BUTTON3_RELEASED mouse button 3 up +BUTTON3_CLICKED mouse button 3 clicked +BUTTON3_DOUBLE_CLICKED mouse button 3 double clicked +BUTTON3_TRIPLE_CLICKED mouse button 3 triple clicked +BUTTON4_PRESSED mouse button 4 down +BUTTON4_RELEASED mouse button 4 up +BUTTON4_CLICKED mouse button 4 clicked +BUTTON4_DOUBLE_CLICKED mouse button 4 double clicked +BUTTON4_TRIPLE_CLICKED mouse button 4 triple clicked +BUTTON_SHIFT shift was down during button state change +BUTTON_CTRL control was down during button state change +BUTTON_ALT alt was down during button state change +ALL_MOUSE_EVENTS report all button state changes +REPORT_MOUSE_POSITION report mouse movement +.TE + +Once a class of mouse events have been made visible in a window, +calling the \fBwgetch\fR function on that window may return +\fBKEY_MOUSE\fR as an indicator that a mouse event has been queued. +To read the event data and pop the event off the queue, call +\fBgetmouse\fR. This function will return \fBOK\fR if a mouse event +is actually visible in the given window, \fBERR\fR otherwise. +When \fBgetmouse\fR returns \fBOK\fR, the data deposited as y and +x in the event structure coordinates will be screen-relative character-cell +coordinates. The returned state mask will have exactly one bit set to +indicate the event type. + +The \fBungetmouse\fR function behaves analogously to \fBungetch\fR. It pushes +a \fBKEY_MOUSE\fR event onto the input queue, and associates with that event +the given state data and screen-relative character-cell coordinates. + +The \fBwenclose\fR function tests whether a given pair of screen-relative +character-cell coordinates is enclosed by a given window, returning TRUE +if it is and FALSE otherwise. It is useful for determining what subset of +the screen windows enclose the location of a mouse event. + +The \fBmouseinterval\fR function sets the maximum time (in thousands of a +second) that can elapse between press and release events in order for them to +be recognized as a click. This function returns the previous interval value. +The default is one fifth of a second. + +Note that mouse events will be ignored when input is in cooked mode, and will +cause an error beep when cooked mode is being simulated in a window by a +function such as \fBgetstr\fR that expects a linefeed for input-loop +termination. + +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure or \fBOK\fR +upon successful completion. +.SH PORTABILITY +These calls were designed for \fBcurses\fR(3x), and are not found in SVr4 +curses, 4.4BSD curses, or any other previous version of curses. + +The feature macro \fBNCURSES_MOUSE_VERSION\fR is provided so the preprocessor +can be used to test whether these features are present (its value is 1). NOTE: +THIS INTERFACE IS EXPERIMENTAL AND IS SUBJECT TO CHANGE WITHOUT NOTICE! If the +interface is changed, the value of \fBNCURSES_MOUSE_VERSION\fR will be +incremented. + +The order of the \fBMEVENT\fR structure members is not guaranteed. +Additional fields may be added to the structure in the future. + +Under \fBcurses\fR(3x), these calls are implemented using either +xterm's built-in mouse-tracking API or Alessandro Rubini's gpm server. +If you are using something other than xterm there is no gpm daemon +running on your machine, mouse events will not be visible to +\fBcurses\fR(3x) (and the \fBwmousemask\fR function will always +return \fB0\fR). + +The z member in the event structure is not presently used. It is intended +for use with touchscreens (which may be pressure-sensitive) or with +3D-mice/trackballs/power gloves. +.SH BUGS +Mouse events under xterm will not in fact be ignored during cooked mode, +if they have been enabled by \fBwmousemask\fR. Instead, the xterm mouse +report sequence will appear in the string read. + +Mouse events under xterm will not be detected correctly in a window with +its keypad bit off. +.SH SEE ALSO +\fBcurses\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: |