'\" t
+.\"***************************************************************************
+.\" Copyright (c) 1998,1999,2000 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.15 2000/07/08 12:50:08 tom Exp $
.TH curs_mouse 3X ""
.SH NAME
-\fBgetmouse\fR, \fBungetmouse\fR,
-\fBmousemask\fR - mouse interface through curses
+\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
.br
\fBmmask_t mousemask(mmask_t newmask, mmask_t *oldmask);\fR
.br
-\fBbool wenclose(WINDOW *win, int y, int x)\fR
+\fBbool wenclose(WINDOW *win, int y, int x);\fR
.br
-\fBint mouseinterval(int erval)\fR
+\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
+\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
_ _
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
BUTTON_SHIFT shift was down during button state change
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 in order for them to
be recognized as a click. This function returns the previous interval value.
termination.
.SH RETURN VALUE
-All routines return the integer \fBERR\fR upon failure or \fBOK\fR
-upon successful completion.
+\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
+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). 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 (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.
+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
+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
+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
+\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
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.
+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 $DISPLAY environment variable is set, and \fBkmous\fR is defined in
+the terminal description, then the terminal may send mouse events.
.SH SEE ALSO
\fBcurses\fR(3X).
.\"#
projects / ncurses.git / blobdiff