+ The has_mouse function returns TRUE if the mouse driver has been
+ successfully initialized, and FALSE otherwise.
+
+ Mouse events are ignored when input is in cooked mode, and 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-loop
+ termination.
+
+
To make mouse events visible, use the mousemask function. This sets
the mouse events to be reported. By default, no mouse events are
@@ -99,53 +109,52 @@
o If oldmask is non-NULL, this function fills the indicated location
with the previous value of the current screen's mouse event mask.
- As a side effect, setting a zero mousemask may turn off the mouse
+ As a side effect, setting a zero mouse mask may turn off the mouse
pointer; setting a nonzero mask may turn it on. Whether this happens
is device-dependent.
-
@@ -174,33 +183,37 @@
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.
+ If the parameter is a pad, wenclose uses the most recent screen
+ coordinates used for this pad in prefresh(3x) or pnoutrefresh(3x).
+
- 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
- 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 ripoffline and slk_init(3x) calls, for example).
-
- o If the parameter to_screen is TRUE, the pointers pY,pX must
- reference 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
+ or vice versa. The resulting stdscr-relative coordinates are not
+ always identical to screen coordinates due to the mechanism to reserve
+ lines on top or bottom of the screen for other purposes (see the
+ ripoffline(3x) and slk_init(3x) calls, for example).
+
+ o If the parameter to_screen is TRUE, the pointers pY,pX must
+ reference the coordinates of a location inside the window win.
+ They are converted to stdscr-relative coordinates and returned
+ through the pointers. If the conversion was successful, the
function returns TRUE.
- o If one of the parameters was NULL or the location is not inside the
+ 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-
- relative coordinates. They are converted to stdscr-relative
- coordinates if the window win encloses this point. In this case
+ o If to_screen is FALSE, the pointers pY,pX must reference
+ stdscr-relative coordinates. They are converted to window-relative
+ coordinates 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
- replaced by the converted coordinates if the transformation was
- successful.
+ If one of the parameters is NULL or the point is not inside the
+ window, FALSE is returned.
+
+ The referenced coordinates are only replaced by the converted
+ coordinates if the transformation was successful.
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
- resolution. This function returns the previous interval value. Use
- mouseinterval(-1) to obtain the interval without altering it. The
- default is one sixth of a second.
+ resolved as a click. An application might interpret button press and
+ release events separated by more than the mouse interval as a "long
+ press", or, with motion, as a "drag".
+ Calling mouseinterval(0) disables click resolution. When ncurses
+ detects a mouse event, it awaits further input activity up to this
+ interval, and then checks for a subsequent mouse event which can be
+ combined with the first event. If the timeout expires without input
+ activity (which would happen with a zero interval), then no click
+ resolution will occur.
-
- The has_mouse function returns TRUE if the mouse driver has been
- successfully initialized, and FALSE otherwise.
+ This function returns the previous interval value. Use
+ mouseinterval(-1) to obtain the interval without altering it.
- 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-
- loop termination.
+ The mouse interval is set to one sixth of a second when the
+ corresponding screen is initialized, e.g., in initscr(3x) or
+ setupterm(3x).
@@ -247,27 +263,16 @@
mousemask returns the mask of reportable events.
- mouseinterval returns the previous interval value, unless the terminal
- was not initialized. In that case, it returns the maximum interval
+ mouseinterval returns the previous interval value, unless the terminal
+ was not initialized. In that case, it returns the maximum interval
value (166).
- The feature macro NCURSES_MOUSE_VERSION is provided so the preprocessor
- can be used to test whether these features are present. If the
- interface is changed, the value of NCURSES_MOUSE_VERSION will be
- incremented. These values for NCURSES_MOUSE_VERSION may be specified
- when configuring ncurses:
-
- 1 has definitions for reserved events. The mask uses 28 bits.
-
- 2 adds definitions for button 5, removes the definitions for
- reserved events. The mask uses 29 bits.
-
The order of the MEVENT structure members is not guaranteed.
Additional fields may be added to the structure in the future.
- Under ncurses, these calls are implemented using either xterm's built-
+ Under ncurses, these calls are implemented using either xterm's built-
in mouse-tracking API or platform-specific drivers including
o Alessandro Rubini's gpm server
@@ -279,14 +284,14 @@
If you are using an unsupported configuration, mouse events will not be
visible to ncurses (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
- mode 1000 of xterm:
+ mode 1000 of xterm:
\E[?1000%?%p1%{1}%=%th%el%;
- The mouse driver also recognizes a newer xterm private mode 1006, e.g.,
+ The mouse driver also recognizes a newer xterm private mode 1006, e.g.,
\E[?1006;1000%?%p1%{1}%=%th%el%;
@@ -295,20 +300,36 @@
or with 3D-mice/trackballs/power gloves.
The ALL_MOUSE_EVENTS class does not include REPORT_MOUSE_POSITION.
- They are distinct. For example, in xterm, wheel/scrolling mice send
+ 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.
+
+ These functions were designed for ncurses(3x), and are not found in
+ SVr4 curses, 4.4BSD curses, or any other previous curses
+ implementation. (SVr4 curses did have a getmouse function, which took
+ no argument and returned a different type.)
+
+
- These calls were designed for ncurses, and are not found in SVr4
- curses, 4.4BSD curses, or any other previous version of curses.
+ Applications employing the ncurses mouse extension should condition its
+ use on the visibility of the NCURSES_MOUSE_VERSION preprocessor macro.
+ When the interface changes, the macro's value increments. Multiple
+ versions are available when ncurses is configured; see section
+ "ALTERNATE CONFIGURATIONS" of ncurses(3x). The following values may be
+ specified.
+
+ 1 has definitions for reserved events. The mask uses 28 bits.
+
+ 2 adds definitions for button 5, removes the definitions for
+ reserved events. The mask uses 29 bits.
SVr4 curses had support for the mouse in a variant of xterm(1). It is
- mentioned in a few places, but with no supporting documentation:
+ mentioned in a few places, with little supporting documentation.
- o the "libcurses" manual page lists functions for this feature which
- are prototyped in curses.h:
+ o Its "libcurses" manual page lists functions for this feature
+ prototyped in curses.h.
extern int mouse_set(long int);
extern int mouse_on(long int);
@@ -318,61 +339,62 @@
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 Its "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
- key_mouse kmous Km 0631, Mouse event has occurred
- mouse_info minfo Mi Mouse status information
- req_mouse_pos reqmp RQ Request mouse position report
+ buttonsbtnsBT Number of buttons on the mouse
+ get_mousegetmGm Curses should get button events
+ key_mousekmousKm 0631, Mouse event has occurred
+ mouse_infominfoMi Mouse status information
+ req_mouse_posreqmpRQ 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
capability.
- Those features required a terminal which had been modified to work
- with curses. They were not part of the X Consortium's xterm.
+ Those features required a terminal program that had been modified
+ to work with SVr4 curses. They were not part of the X Consortium's
+ xterm.
- When developing the xterm mouse support for ncurses in September 1995,
- Eric Raymond was uninterested in using the same interface due to its
+ When developing the xterm mouse support for ncurses in September 1995,
+ Eric Raymond was uninterested in using the same interface due to its
lack of documentation. Later, in 1998, Mark Hesseling provided support
- in PDCurses 2.3 using the SVr4 interface. PDCurses, however, does not
- use video terminals, making it unnecessary to be concerned about
+ in PDCurses 2.3 using the SVr4 interface. PDCurses, however, does not
+ use video terminals, making it unnecessary to be concerned about
compatibility with the escape sequences.
- Mouse events from xterm are not ignored in cooked mode if they have
- been enabled by mousemask. Instead, the xterm mouse report sequence
+ Mouse events from xterm are not ignored in cooked mode if they have
+ been enabled by mousemask. Instead, the xterm mouse report sequence
appears in the string read.
- Mouse event reports from xterm are not detected correctly in a window
- with keypad application mode disabled, since they are interpreted as a
- variety of function key. Set the the terminal's terminfo capability
- kmous to "\E[M" (the beginning of the response from xterm for mouse
- clicks). Other values of kmous are permitted under the same
- assumption, that is, the report begins with that sequence.
+ An ncurses window must enable keypad(3x) to correctly receive mouse
+ event reports from xterm since they are encoded like function keys.
+ Set the terminal's terminfo capability kmous to "\E[M" (the beginning
+ of the response from xterm for mouse clicks). Other values of kmous
+ are permitted under the same assumption, that is, the report begins
+ with that sequence.
Because there are no standard response sequences that serve to identify
- terminals supporting the xterm mouse protocol, ncurses assumes that if
+ terminals supporting the xterm mouse protocol, ncurses assumes that if
kmous is defined in the terminal description, or if the terminal type's
- primary name or aliases contain the string "xterm", then the terminal
+ primary name or aliases contain the string "xterm", then the terminal
may send mouse events. The kmous capability is checked first, allowing
- use of newer xterm mouse protocols such as its private mode 1006.
+ use of newer xterm mouse protocols, such as its private mode 1006.