diff options
Diffstat (limited to 'contrib/ncurses/man/curs_mouse.3x')
| -rw-r--r-- | contrib/ncurses/man/curs_mouse.3x | 310 |
1 files changed, 0 insertions, 310 deletions
diff --git a/contrib/ncurses/man/curs_mouse.3x b/contrib/ncurses/man/curs_mouse.3x deleted file mode 100644 index 23f9f9c6d7d0..000000000000 --- a/contrib/ncurses/man/curs_mouse.3x +++ /dev/null @@ -1,310 +0,0 @@ -'\" t -.\"*************************************************************************** -.\" Copyright (c) 1998-2005,2006 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: curs_mouse.3x,v 1.30 2006/12/30 23:43:34 tom Exp $ -.TH curs_mouse 3X "" -.na -.hy 0 -.SH NAME -\fBgetmouse\fR, \fBungetmouse\fR, -\fBmousemask\fR, \fBwenclose\fR, -\fBmouse_trafo\fR, \fBwmouse_trafo\fR, -\fBmouseinterval\fR - mouse interface through curses -.ad -.hy -.SH SYNOPSIS -.nf -\fB#include <curses.h> -.PP -\fBtypedef unsigned long mmask_t; -.PP -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. -.PP -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. -.PP -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. -.PP -Here are the mouse event type masks which may be defined: -.PP -.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 -_ -BUTTON5_PRESSED mouse button 5 down -BUTTON5_RELEASED mouse button 5 up -BUTTON5_CLICKED mouse button 5 clicked -BUTTON5_DOUBLE_CLICKED mouse button 5 double clicked -BUTTON5_TRIPLE_CLICKED mouse button 5 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 -.PP -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. -.PP -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. -.PP -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. -.PP -The \fBwmouse_trafo\fR function transforms a given pair of coordinates -from stdscr-relative coordinates -to coordinates relative to the given window 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 the \fBripoffline()\fP and \fBslk_init\fR calls, for example). -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 window-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 window-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. -.PP -The \fBmouse_trafo\fR function performs the same translation -as \fBwmouse_trafo\fR, -using stdscr for \fBwin\fR. -.PP -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(0)\fR to disable click resolution. -This function returns the previous interval value. -Use \fBmouseinterval(-1)\fR to obtain the interval without altering it. -The default is one sixth of a second. -.PP -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 and \fBungetmouse\fR -return the integer \fBERR\fR upon failure or \fBOK\fR -upon successful completion. -.RS -.TP 5 -\fBgetmouse\fP -returns an error. -If no mouse driver was initialized, or -if the mask parameter is zero, -.TP 5 -\fBungetmouse\fP -returns an error if the FIFO is full. -.RE -.PP -\fBmousemask\fR -returns the mask of reportable events. -.PP -\fBmouseinterval\fR -returns the previous interval value, unless -the terminal was not initialized. -In that case, it returns the maximum interval value (166). -.PP -\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. -.PP -The feature macro \fBNCURSES_MOUSE_VERSION\fR is provided so the preprocessor -can be used to test whether these features are present. -If the interface is changed, the value of \fBNCURSES_MOUSE_VERSION\fR will be -incremented. -These values for \fBNCURSES_MOUSE_VERSION\fR may be -specified when configuring ncurses: -.RS -.TP 3 -1 -has definitions for reserved events. -The mask uses 28 bits. -.TP 3 -2 -adds definitions for button 5, -removes the definitions for reserved events. -The mask uses 29 bits. -.RE -.PP -The order of the \fBMEVENT\fR structure members is not guaranteed. -Additional fields may be added to the structure in the future. -.PP -Under \fBncurses\fR(3X), these calls are implemented using either -xterm's built-in mouse-tracking API or -platform-specific drivers including -.RS -Alessandro Rubini's gpm server. -.br -FreeBSD sysmouse -.br -OS/2 EMX -.RE -If you are using an unsupported configuration, -mouse events will not be visible to -\fBncurses\fR(3X) (and the \fBmousemask\fR function will always -return \fB0\fR). -.PP -If the terminfo entry contains a \fBXM\fR string, -this is used in the xterm mouse driver to control the -way the terminal is initialized for mouse operation. -The default, if \fBXM\fR is not found, -corresponds to private mode 1000 of xterm: -.RS -\\E[?1000%?%p1%{1}%=%th%el%; -.RE -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 \fBmousemask\fR. -Instead, the xterm mouse -report sequence will appear in the string read. -.PP -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 should have \fBkmous\fR set to "\\E[M" -(the beginning of the response from xterm for mouse clicks). -Other values for \fBkmous\fR are permitted, -but under the same assumption, -i.e., it is the beginning of the response. -.PP -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), -\fBcurs_kernel\fR(3X), -\fBcurs_slk\fR(3X). -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: |