diff options
Diffstat (limited to 'lib/libcurses/curs_mouse.3tbl')
| -rw-r--r-- | lib/libcurses/curs_mouse.3tbl | 231 |
1 files changed, 162 insertions, 69 deletions
diff --git a/lib/libcurses/curs_mouse.3tbl b/lib/libcurses/curs_mouse.3tbl index 8c06b5aca66..802fd0c8560 100644 --- a/lib/libcurses/curs_mouse.3tbl +++ b/lib/libcurses/curs_mouse.3tbl @@ -1,8 +1,8 @@ '\" t -.\" $OpenBSD: curs_mouse.3tbl,v 1.9 2000/07/10 03:06:08 millert Exp $ +.\" $OpenBSD: curs_mouse.3tbl,v 1.10 2010/01/12 23:21:59 nicm Exp $ .\" .\"*************************************************************************** -.\" Copyright (c) 1998,1999,2000 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2005,2006 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 * @@ -29,19 +29,23 @@ .\" authorization. * .\"*************************************************************************** .\" -.'" $From: curs_mouse.3x,v 1.15 2000/07/08 12:50:08 tom Exp $ +.\" $Id: curs_mouse.3tbl,v 1.10 2010/01/12 23:21:59 nicm Exp $ .TH curs_mouse 3 "" +.na +.hy 0 .SH NAME \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 - +\fB#include <curses.h> +.PP \fBtypedef unsigned long mmask_t; - +.PP typedef struct { short id; \fI/* ID to distinguish multiple devices */\fB @@ -57,7 +61,7 @@ MEVENT;\fR .br \fBmmask_t mousemask(mmask_t newmask, mmask_t *oldmask);\fR .br -\fBbool wenclose(WINDOW *win, int y, int x);\fR +\fBbool wenclose(const WINDOW *win, int y, int x);\fR .br \fBbool mouse_trafo(int* pY, int* pX, bool to_screen);\fR .br @@ -69,22 +73,26 @@ MEVENT;\fR .br .SH DESCRIPTION These functions provide an interface to mouse events from -\fBcurses\fR(3). Mouse events are represented by \fBKEY_MOUSE\fR +\fBncurses\fR(3). +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. +.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. +.PP +Here are the mouse event type masks which may be defined: +.PP .TS l l _ _ @@ -95,122 +103,207 @@ 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 +\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 +.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 +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. +.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 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 +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 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. +.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, \fBungetmouse\fR and \fBmouseinterval\fR +\fBgetmouse\fR and \fBungetmouse\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 +upon successful completion. +.RS +.TP 5 +\fBgetmouse\fP +returns an error. +If no mouse driver was initialized, or +if the mask parameter is zero, +.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, and are not found in SVr4 +These calls were designed for \fBncurses\fR(3), 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). +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. - -Under \fBncurses\fR, 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 and there is no gpm daemon -running on your machine, mouse events will not be visible to -\fBcurses\fR(3) (and the \fBwmousemask\fR function will always +.PP +Under \fBncurses\fR(3), 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(3) (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: +.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 \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, 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). - +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 $DISPLAY environment variable is set, and \fBkmous\fR is defined in +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(3). +\fBcurses\fR(3), +\fBcurs_kernel\fR(3), +\fBcurs_slk\fR(3). .\"# .\"# The following sets edit modes for GNU EMACS .\"# Local Variables: |