- These functions provide an interface to mouse events from ncurses(3x).
- Mouse events are represented by KEY_MOUSE pseudo-key values in the
- wgetch(3x) input stream.
+ These functions provide an interface to mouse events from ncurses(3X).
+ Mouse events are represented by KEY_MOUSE pseudo-key values in the
+ wgetch(3X) input stream.
- To make mouse events visible, use the mousemask function. This will
+ To make mouse events visible, use the mousemask 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
@@ -95,7 +101,7 @@
Once a class of mouse events has been made visible in a window, calling
- the wgetch function on that window may return KEY_MOUSE as an indicator
+ the wgetch function on that window may return KEY_MOUSE as an indicator
that a mouse event has been queued. To read the event data and pop the
- event off the queue, call getmouse. This function will return OK if a
- mouse event is actually visible in the given window, ERR otherwise.
- When getmouse returns OK, the data deposited as y and x in the event
+ event off the queue, call getmouse. This function will return OK if a
+ mouse event is actually visible in the given window, ERR otherwise.
+ When getmouse returns OK, the data deposited as y and x in the event
structure coordinates will be screen-relative character-cell coordi-
nates. The returned state mask will have exactly one bit set to indi-
cate the event type. The corresponding data in the queue is marked in-
- valid. A subsequent call to getmouse will retrieve the next older item
+ valid. A subsequent call to getmouse will retrieve the next older item
from the queue.
- The ungetmouse function behaves analogously to ungetch. It pushes a
- KEY_MOUSE event onto the input queue, and associates with that event
+ The ungetmouse function behaves analogously to ungetch. It pushes a
+ KEY_MOUSE event onto the input queue, and associates with that event
the given state data and screen-relative character-cell coordinates.
- The wenclose function tests whether a given pair of screen-relative
+ The wenclose 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
+ 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 wmouse_trafo function transforms a given pair of coordinates from
+ The wmouse_trafo 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 al-
ways identical to window-relative coordinates due to the mechanism to
reserve lines on top or bottom of the screen for other purposes (see
- the ripoffline and slk_init(3x) calls, for example).
+ the ripoffline and slk_init(3X) calls, for example).
- o If the parameter to_screen is TRUE, the pointers pY,pX must refer-
- ence the coordinates of a location inside the window win. They are
+ o If the parameter to_screen is TRUE, the pointers pY,pX must refer-
+ ence the coordinates of a location inside the window win. They are
converted to window-relative coordinates and returned through the
pointers. If the conversion was successful, the function returns
- TRUE.
+ TRUE.
- o If one of the parameters was NULL or the location is not inside the
- window, FALSE is returned.
+ o If one of the parameters was NULL or the location is not inside the
+ window, FALSE is returned.
- o If to_screen is FALSE, the pointers pY,pX must reference window-
+ o If to_screen is FALSE, the pointers pY,pX must reference window-
relative coordinates. They are converted to stdscr-relative coor-
- dinates if the window win encloses this point. In this case the
- function returns TRUE.
+ dinates if the window win encloses this point. In this case the
+ function returns TRUE.
- o If one of the parameters is NULL or the point is not inside the
- window, FALSE is returned. The referenced coordinates are only re-
+ o If one of the parameters is NULL or the point is not inside the
+ window, FALSE is returned. The referenced coordinates are only re-
placed by the converted coordinates if the transformation was suc-
cessful.
- The mouse_trafo function performs the same translation as wmouse_trafo,
- using stdscr for win.
+ The mouse_trafo function performs the same translation as wmouse_trafo,
+ using stdscr for win.
- The mouseinterval function sets the maximum time (in thousands of a
+ The mouseinterval 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 mouseinterval(0) to disable click resolu-
- tion. This function returns the previous interval value. Use mousein-
- terval(-1) to obtain the interval without altering it. The default is
+ recognized as a click. Use mouseinterval(0) to disable click resolu-
+ tion. This function returns the previous interval value. Use mousein-
+ terval(-1) to obtain the interval without altering it. The default is
one sixth of a second.
- The has_mouse function returns TRUE if the mouse driver has been suc-
+ The has_mouse function returns TRUE if the mouse driver has been suc-
cessfully initialized.
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 getstr that expects a linefeed for input-
+ window by a function such as getstr that expects a linefeed for input-
loop termination.
- getmouse and ungetmouse return the integer ERR upon failure or OK upon
+ getmouse and ungetmouse return the integer ERR upon failure or OK upon
successful completion:
- getmouse
+ getmouse
returns an error.
- o If no mouse driver was initialized, or if the mask parameter is
+ o If no mouse driver was initialized, or if the mask parameter is
zero,
- o It also returns an error if no more events remain in the queue.
+ o It also returns an error if no more events remain in the queue.
- ungetmouse
+ ungetmouse
returns an error if the FIFO is full.
- mousemask returns the mask of reportable events.
+ mousemask returns the mask of reportable events.
- mouseinterval returns the previous interval value, unless the terminal
+ mouseinterval returns the previous interval value, unless the terminal
was not initialized. In that case, it returns the maximum interval
value (166).
- wenclose and wmouse_trafo are boolean functions returning TRUE or FALSE
+ wenclose and wmouse_trafo are boolean functions returning TRUE or FALSE
depending on their test result.
- These calls were designed for ncurses(3x), and are not found in SVr4
+ These calls were designed for ncurses(3X), and are not found in SVr4
curses, 4.4BSD curses, or any other previous version of curses.
- SVr4 curses had support for the mouse in a variant of xterm. It is
+ SVr4 curses had support for the mouse in a variant of xterm. It is
mentioned in a few places, but with no supporting documentation:
- o the "libcurses" manual page lists functions for this feature which
- are prototyped in curses.h:
+ o the "libcurses" manual page lists functions for this feature which
+ are prototyped in curses.h:
extern int mouse_set(long int);
extern int mouse_on(long int);
@@ -258,7 +264,7 @@
extern void wmouse_position(WINDOW *, int *, int *);
extern unsigned long getmouse(void), getbmap(void);
- o the "terminfo" manual page lists capabilities for the feature
+ o the "terminfo" manual page lists capabilities for the feature
buttons btns BT Number of buttons on the mouse
get_mouse getm Gm Curses should get button events
@@ -266,13 +272,13 @@
mouse_info minfo Mi Mouse status information
req_mouse_pos reqmp RQ Request mouse position report
- o the interface made assumptions (as does ncurses) about the escape
+ o the interface made assumptions (as does ncurses) about the escape
sequences sent to and received from the terminal.
- For instance the SVr4 curses library used the get_mouse capability
+ For instance the SVr4 curses library used the get_mouse capability
to tell the terminal which mouse button events it should send,
passing the mouse-button bit-mask to the terminal. Also, it could
- ask the terminal where the mouse was using the req_mouse_pos capa-
+ ask the terminal where the mouse was using the req_mouse_pos capa-
bility.
Those features required a terminal which had been modified to work
@@ -285,10 +291,10 @@
use video terminals, making it unnecessary to be concerned about com-
patibility with the escape sequences.
- The feature macro NCURSES_MOUSE_VERSION is provided so the preprocessor
+ The feature macro NCURSES_MOUSE_VERSION is provided so the preprocessor
can be used to test whether these features are present. If the inter-
- face is changed, the value of NCURSES_MOUSE_VERSION will be increment-
- ed. These values for NCURSES_MOUSE_VERSION may be specified when con-
+ face is changed, the value of NCURSES_MOUSE_VERSION will be increment-
+ ed. These values for NCURSES_MOUSE_VERSION may be specified when con-
figuring ncurses:
1 has definitions for reserved events. The mask uses 28 bits.
@@ -296,25 +302,25 @@
2 adds definitions for button 5, removes the definitions for re-
served events. The mask uses 29 bits.
- The order of the MEVENT structure members is not guaranteed. Addition-
+ The order of the MEVENT structure members is not guaranteed. Addition-
al fields may be added to the structure in the future.
- Under ncurses(3x), these calls are implemented using either xterm's
+ Under ncurses(3X), these calls are implemented using either xterm's
built-in mouse-tracking API or platform-specific drivers including
- o Alessandro Rubini's gpm server
+ o Alessandro Rubini's gpm server
- o FreeBSD sysmouse
+ o FreeBSD sysmouse
- o OS/2 EMX
+ o OS/2 EMX
If you are using an unsupported configuration, mouse events will not be
- visible to ncurses(3x) (and the mousemask function will always return
- 0).
+ visible to ncurses(3X) (and the mousemask function will always return
+ 0).
- If the terminfo entry contains a XM string, this is used in the xterm
+ If the terminfo entry contains a XM string, this is used in the xterm
mouse driver to control the way the terminal is initialized for mouse
- operation. The default, if XM is not found, corresponds to private
+ operation. The default, if XM is not found, corresponds to private
mode 1000 of xterm:
\E[?1000%?%p1%{1}%=%th%el%;
@@ -323,11 +329,11 @@
\E[?1006;1000%?%p1%{1}%=%th%el%;
- The z member in the event structure is not presently used. It is in-
+ The z member in the event structure is not presently used. It is in-
tended for use with touch screens (which may be pressure-sensitive) or
with 3D-mice/trackballs/power gloves.
- The ALL_MOUSE_EVENTS class does not include REPORT_MOUSE_POSITION.
+ The ALL_MOUSE_EVENTS class does not include REPORT_MOUSE_POSITION.
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.
@@ -335,31 +341,31 @@
Mouse events under xterm will not in fact be ignored during cooked
- mode, if they have been enabled by mousemask. Instead, the xterm mouse
+ mode, if they have been enabled by mousemask. 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, since they are interpreted as a variety of
- function key. Your terminfo description should have kmous set to
+ function key. Your terminfo description should have kmous set to
"\E[M" (the beginning of the response from xterm for mouse clicks).
- Other values for kmous are permitted, but under the same assumption,
+ Other values for kmous are permitted, but under the same assumption,
i.e., it is the beginning of the response.
Because there are no standard terminal responses that would serve to
- identify terminals which support the xterm mouse protocol, ncurses as-
- sumes that if kmous is defined in the terminal description, or if the
+ identify terminals which support the xterm mouse protocol, ncurses as-
+ sumes that if kmous is defined in the terminal description, or if the
terminal description's primary name or aliases contain the string
- "xterm", then the terminal may send mouse events. The kmous capability
+ "xterm", then the terminal may send mouse events. The kmous capability
is checked first, allowing the use of newer xterm mouse protocols such
as xterm's private mode 1006.