diff options
Diffstat (limited to 'ncurses-5.3/man/curs_mouse.3x')
| -rw-r--r-- | ncurses-5.3/man/curs_mouse.3x | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/ncurses-5.3/man/curs_mouse.3x b/ncurses-5.3/man/curs_mouse.3x new file mode 100644 index 0000000..6be3118 --- /dev/null +++ b/ncurses-5.3/man/curs_mouse.3x @@ -0,0 +1,239 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2001,2002 Free Software Foundation, Inc. * +.\" * +.\" Permission is hereby granted, free of charge, to any person obtaining a * +.\" copy of this software and associated documentation files (the * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id$ +.TH curs_mouse 3X "" +.SH NAME +\fBgetmouse\fR, \fBungetmouse\fR, +\fBmousemask\fR, \fBwenclose\fR, +\fBmouse_trafo\fR, \fBwmouse_trafo\fR, +\fBmouseinterval\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(const WINDOW *win, int y, int x);\fR +.br +\fBbool mouse_trafo(int* pY, int* pX, bool to_screen);\fR +.br +\fBbool wmouse_trafo(const WINDOW* win, int* pY, int* pX,\fR +.br + \fBbool to_screen);\fR +.br +\fBint mouseinterval(int erval);\fR +.br +.SH DESCRIPTION +These functions provide an interface to mouse events from +\fBncurses\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 \fBwmouse_trafo\fR function transforms a given pair of coordinates from +stdscr-relative coordinates to screen-relative coordinates or vice versa. +Please remember, that stdscr-relative coordinates are not always identical +to screen-relative coordinates due to the mechanism to reserve lines on top +or bottom of the screen for other purposes (ripoff() call, see also slk_... +functions). +If the parameter \fBto_screen\fR is \fBTRUE\fR, the pointers +\fBpY, pX\fR must reference the coordinates of a location inside the window +\fBwin\fR. +They are converted to screen-relative coordinates and returned +through the pointers. +If the conversion was successful, the function returns \fBTRUE\fR. +If one of the parameters was NULL or the location is +not inside the window, \fBFALSE\fR is returned. +If \fBto_screen\fR is +\fBFALSE\fR, the pointers \fBpY, pX\fR must reference screen-relative +coordinates. +They are converted to stdscr-relative coordinates if the +window \fBwin\fR encloses this point. +In this case the function returns \fBTRUE\fR. +If one of the parameters is NULL or the point is not inside the +window, \fBFALSE\fR is returned. +Please notice, that the referenced coordinates +are only replaced by the converted coordinates if the transformation was +successful. + +The \fBmouseinterval\fR 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 \fBmouseinterval(-1)\fR to disable click resolution. +This function returns the previous interval value. +The default is one sixth 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 +\fBgetmouse\fR, \fBungetmouse\fR and \fBmouseinterval\fR +return the integer \fBERR\fR upon failure or \fBOK\fR +upon successful completion. +\fBmousemask\fR returns the +mask of reportable events. +\fBwenclose\fR and \fBwmouse_trafo\fR +are boolean functions returning \fBTRUE\fR or \fBFALSE\fR depending +on their test result. +.SH PORTABILITY +These calls were designed for \fBncurses\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). +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 \fBncurses\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 and there is no gpm daemon +running on your machine, mouse events will not be visible to +\fBncurses\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 touch screens (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, since they are interpreted as a variety of function key. +Your terminfo description must have \fBkmous\fR set to "\\E[M" (the beginning +of the response from xterm for mouse clicks). + +Because there are no standard terminal responses that would serve to identify +terminals which support the xterm mouse protocol, \fBncurses\fR assumes that +if your $TERM environment variable contains "xterm", +or \fBkmous\fR is defined in +the terminal description, then the terminal may send mouse events. +.SH SEE ALSO +\fBcurses\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: |