ncurses 6.0 - patch 20160514
[ncurses.git] / man / curs_mouse.3x
index ad7d601d5c0d84d5027bc6be6ccd367eedc71dc8..b7cf4c6ca2399fae8b21bec9785c5948d0fab2b7 100644 (file)
 '\" t
+.\"***************************************************************************
+.\" Copyright (c) 1998-2014,2015 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.42 2015/07/21 09:27:39 tom Exp $
+.de bP
+.IP \(bu 4
+..
 .TH curs_mouse 3X ""
+.na
+.hy 0
 .SH NAME
-\fBgetmouse\fR, \fBungetmouse\fR, 
-\fBmousemask\fR - mouse interface through curses
+\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
-.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
+.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
-\fBint getmouse(MEVENT *event);\fR
+\fBbool wenclose(const WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
 .br
-\fBint ungetmouse(MEVENT *event);\fR
+\fBbool mouse_trafo(int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB, bool \fP\fIto_screen\fP\fB);\fR
 .br
-\fBmmask_t mousemask(mmask_t newmask, mmask_t *oldmask);\fR
+\fBbool wmouse_trafo(const WINDOW* \fP\fIwin\fP\fB, int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB,\fR
 .br
-\fBbool wenclose(WINDOW *win, int y, int x)\fR
+       \fBbool \fP\fIto_screen\fP\fB);\fR
 .br
-\fBint mouseinterval(int erval)\fR
+\fBint mouseinterval(int \fP\fIerval\fP\fB);\fR
 .br
 .SH DESCRIPTION
 These functions provide an interface to mouse events from
-\fBncurses\fR(3x).  Mouse events are represented by \fBKEY_MOUSE\fR
+\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.
+.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,
+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.
-
-Here are the mouse event type masks:
-
+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_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_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_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_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
-
-Once a class of mouse events have been made visible in a window,
+.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
+\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
+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
+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 TRUE
-if it is and FALSE otherwise.  It is useful for determining what subset of
+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 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 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.
-
+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
-All routines return the integer \fBERR\fR upon failure or \fBOK\fR
-upon successful completion.
+\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(3x), and are not found in SVr4
+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 (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
+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.
-
-The order of the \fBMEVENT\fR structure members is not guaranteed.  
+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.
-
-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 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
+.PP
+Under \fBncurses\fR(3X), 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(3X) (and the \fBmousemask\fR function will always
 return \fB0\fR).
-
-The z member in the event structure is not presently used.  It is intended
+.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 \fBwmousemask\fR.  Instead, the xterm mouse
+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.
+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).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fBcurses\fR(3X),
+\fBcurs_kernel\fR(3X),
+\fBcurs_slk\fR(3X),
+\fBcurs_variables\fR(3X).