314 lines
12 KiB
Plaintext
314 lines
12 KiB
Plaintext
'\" t
|
|
.\"***************************************************************************
|
|
.\" Copyright (c) 1998-2010,2013 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.39 2013/06/22 18:09:42 tom Exp $
|
|
.TH curs_mouse 3X ""
|
|
.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 <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 *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.
|
|
The corresponding data in the queue is marked invalid.
|
|
A subsequent call to \fBgetmouse\fP will retrieve the next older
|
|
item from the queue.
|
|
.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
|
|
The \fBhas_mouse\fP function returns TRUE 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
|
|
.TP 5
|
|
\fBgetmouse\fP
|
|
returns an error.
|
|
If no mouse driver was initialized, or
|
|
if the mask parameter is zero,
|
|
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
|
|
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),
|
|
\fBcurs_variables\fR(3X).
|