aboutsummaryrefslogtreecommitdiff
path: root/contrib/ncurses/man/curs_mouse.3x
diff options
context:
space:
mode:
authorPeter Wemm <peter@FreeBSD.org>1999-08-24 01:06:48 +0000
committerPeter Wemm <peter@FreeBSD.org>1999-08-24 01:06:48 +0000
commit0e3d540892016a47f6a68ec9ba2879d35ce5f7c2 (patch)
treead214c5b2c8142ad6dc6d2ce3a9c83e6317d7f77 /contrib/ncurses/man/curs_mouse.3x
downloadsrc-0e3d540892016a47f6a68ec9ba2879d35ce5f7c2.tar.gz
src-0e3d540892016a47f6a68ec9ba2879d35ce5f7c2.zip
Import unmodified (but trimmed) ncurses 5.0 prerelease 990821.vendor/ncurses/5.0-19990821
This contains the full eti (panel, form, menu) extensions. bmake glue to follow. Obtained from: ftp://ftp.clark.net/pub/dickey/ncurses
Notes
Notes: svn path=/vendor/ncurses/dist/; revision=50276 svn path=/vendor/ncurses/5.0-19990821/; revision=50278; tag=vendor/ncurses/5.0-19990821
Diffstat (limited to 'contrib/ncurses/man/curs_mouse.3x')
-rw-r--r--contrib/ncurses/man/curs_mouse.3x206
1 files changed, 206 insertions, 0 deletions
diff --git a/contrib/ncurses/man/curs_mouse.3x b/contrib/ncurses/man/curs_mouse.3x
new file mode 100644
index 000000000000..e995260473f9
--- /dev/null
+++ b/contrib/ncurses/man/curs_mouse.3x
@@ -0,0 +1,206 @@
+'\" t
+.\"***************************************************************************
+.\" Copyright (c) 1998 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.12 1999/01/09 22:53:22 tom Exp $
+.TH curs_mouse 3X ""
+.SH NAME
+\fBgetmouse\fR, \fBungetmouse\fR,
+\fBmousemask\fR, \fBwenclose\fR,
+\fBwmouse_trafo\fR, \fBmouseinterval\fR - mouse interface through curses
+.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
+.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(WINDOW *win, int y, int x);\fR
+.br
+\fBbool wmouse_trafo(const WINDOW* win, int* pY, int* pX, bool 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.
+
+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.
+
+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:
+
+.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
+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,
+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 \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.
+
+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.
+
+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.
+The default is one fifth of a second.
+
+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, \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
+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
+incremented.
+
+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
+return \fB0\fR).
+
+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 \fBwmousemask\fR. Instead, the xterm mouse
+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.
+.SH SEE ALSO
+\fBcurses\fR(3X).
+.\"#
+.\"# The following sets edit modes for GNU EMACS
+.\"# Local Variables:
+.\"# mode:nroff
+.\"# fill-column:79
+.\"# End: