diff options
Diffstat (limited to 'upstream/opensuse-leap-15-6/man3/mouse.3ncurses')
| -rw-r--r-- | upstream/opensuse-leap-15-6/man3/mouse.3ncurses | 404 |
1 files changed, 404 insertions, 0 deletions
diff --git a/upstream/opensuse-leap-15-6/man3/mouse.3ncurses b/upstream/opensuse-leap-15-6/man3/mouse.3ncurses new file mode 100644 index 00000000..7ef0e892 --- /dev/null +++ b/upstream/opensuse-leap-15-6/man3/mouse.3ncurses @@ -0,0 +1,404 @@ +'\" t +.\"*************************************************************************** +.\" Copyright (c) 1998-2015,2017 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.47 2017/11/18 23:52:45 tom Exp $ +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de NS +.ie n .sp +.el .sp .5 +.ie n .in +4 +.el .in +2 +.nf +.ft C \" Courier +.. +.de NE +.fi +.ft R +.in -4 +.. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.TH mouse 3NCURSES "" +.na +.hy 0 +.SH NAME +\fBhas_mouse\fR, +\fBgetmouse\fR, \fBungetmouse\fR, +\fBmousemask\fR, \fBwenclose\fR, +\fBmouse_trafo\fR, \fBwmouse_trafo\fR, +\fBmouseinterval\fR \- mouse interface through curses +.ad +.hy +.SH SYNOPSIS +\fB#include <ncursesw/curses.h>\fR +.PP +\fBtypedef unsigned long mmask_t;\fR +.PP +.nf +\fBtypedef struct {\fR +\fB short id; \fR\fI/* ID to distinguish multiple devices */\fR +\fB int x, y, z; \fR\fI/* event coordinates */\fR +\fB mmask_t bstate; \fR\fI/* button state bits */\fR +\fB} MEVENT;\fR +.fi +.PP +\fBbool has_mouse(void);\fR +.br +\fBint getmouse(MEVENT *\fP\fIevent\fP\fB);\fR +.br +\fBint ungetmouse(MEVENT *\fP\fIevent\fP\fB);\fR +.br +\fBmmask_t mousemask(mmask_t \fP\fInewmask\fP\fB, mmask_t *\fP\fIoldmask\fP\fB);\fR +.br +\fBbool wenclose(const WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR +.br +\fBbool mouse_trafo(int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB, bool \fP\fIto_screen\fP\fB);\fR +.br +\fBbool wmouse_trafo(const WINDOW* \fP\fIwin\fP\fB, int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB,\fR +.br + \fBbool \fP\fIto_screen\fP\fB);\fR +.br +\fBint mouseinterval(int \fP\fIerval\fP\fB);\fR +.br +.SH DESCRIPTION +These functions provide an interface to mouse events from +\fBncurses\fR(3NCURSES). +Mouse events are represented by \fBKEY_MOUSE\fR +pseudo-key values in the \fBwgetch\fR(3X) input stream. +.SS mousemask +.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. +.SS Mouse events +.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 +.SS getmouse +.PP +Once a class of mouse events has 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 corresponding data in the queue is marked invalid. +A subsequent call to \fBgetmouse\fP will retrieve the next older +item from the queue. +.SS ungetmouse +.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. +.SS wenclose +.PP +The \fBwenclose\fR function tests whether a given pair of screen-relative +character-cell coordinates is enclosed by a given window, returning \fBTRUE\fP +if it is and \fBFALSE\fP otherwise. +It is useful for determining what subset of +the screen windows enclose the location of a mouse event. +.SS wmouse_trafo +.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. +The resulting 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(3X) calls, for example). +.bP +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. +.bP +If one of the parameters was NULL or the location is +not inside the window, \fBFALSE\fR is returned. +.bP +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. +.bP +If one of the parameters is NULL or the point is not inside the +window, \fBFALSE\fR is returned. +The referenced coordinates +are only replaced by the converted coordinates if the transformation was +successful. +.SS mouse_trafo +.PP +The \fBmouse_trafo\fR function performs the same translation +as \fBwmouse_trafo\fR, +using stdscr for \fBwin\fR. +.SS mouseinterval +.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. +.SS has_mouse +.PP +The \fBhas_mouse\fP function returns \fBTRUE\fP if the mouse driver has been +successfully initialized. +.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 3 +.TP 5 +\fBgetmouse\fP +returns an error. +.bP +If no mouse driver was initialized, or +if the mask parameter is zero, +.bP +It also returns an error if no more events remain in the queue. +.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(3NCURSES), and are not found in SVr4 +curses, 4.4BSD curses, or any other previous version of curses. +.PP +SVr4 curses had support for the mouse in a variant of \fBxterm\fP. +It is mentioned in a few places, but with no supporting documentation: +.bP +the \*(``libcurses\*('' manual page lists functions for this feature +which are prototyped in \fBcurses.h\fP: +.NS +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); +.NE +.bP +the \*(``terminfo\*('' manual page lists capabilities for the feature +.NS +buttons btns BT Number of buttons on the mouse +get_mouse getm Gm Curses should get button events +key_mouse kmous Km 0631, Mouse event has occurred +mouse_info minfo Mi Mouse status information +req_mouse_pos reqmp RQ Request mouse position report +.NE +.bP +the interface made assumptions (as does ncurses) about the escape sequences +sent to and received from the terminal. +.IP +For instance +the SVr4 curses library used the \fBget_mouse\fP 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 \fBreq_mouse_pos\fP capability. +.IP +Those features required a terminal which had been modified to work with curses. +They were not part of the X Consortium's xterm. +.PP +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. +.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 3 +.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(3NCURSES), these calls are implemented using either +xterm's built-in mouse-tracking API or +platform-specific drivers including +.RS 3 +.bP +Alessandro Rubini's gpm server +.bP +FreeBSD sysmouse +.bP +OS/2 EMX +.RE +.PP +If you are using an unsupported configuration, +mouse events will not be visible to +\fBncurses\fR(3NCURSES) (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: +.PP +.RS 3 +\\E[?1000%?%p1%{1}%=%th%el%; +.RE +.PP +The \fIz\fP 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. +.PP +The \fBALL_MOUSE_EVENTS\fP class does not include \fBREPORT_MOUSE_POSITION\fP. +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. +.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 +\fBncurses\fR(3NCURSES), +\fBkernel\fR(3NCURSES), +\fBslk\fR(3NCURSES), +\fBcurses_variables\fR(3NCURSES). |