.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_mouse.3x,v 1.78 2023/09/23 23:08:40 tom Exp $
-.TH curs_mouse 3X 2023-09-23 "ncurses 6.4" "Library calls"
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
-.ie n .ds CW R
-.el \{
-.ie \n(.g .ds CW CR
-.el .ds CW CW
+.\" $Id: curs_mouse.3x,v 1.82 2023/12/16 21:08:16 tom Exp $
+.TH curs_mouse 3X 2023-12-16 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
.\}
-.de NS
-.ie n .sp
-.el .sp .5
-.ie n .in +4
-.el .in +2
-.nf
-.ft \*(CW
-..
-.de NE
-.fi
-.ft R
-.ie n .in -4
-.el .in -2
-..
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
get mouse events in \fIcurses\fR
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fP
+\fB#include <curses.h>
.PP
-\fBtypedef unsigned long mmask_t;\fP
+\fBtypedef unsigned long mmask_t;
.PP
-\fBtypedef struct {\fP
-\fB short id; \fI/* ID to distinguish multiple devices */\fR
-\fB int x, y, z; \fI/* event coordinates */\fR
-\fB mmask_t bstate; \fI/* button state bits */\fR
-\fB} MEVENT;\fP
+\fBtypedef struct {
+\fB 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;
.PP
-\fBbool has_mouse(void);\fP
+\fBbool has_mouse(void);
.PP
-\fBint getmouse(MEVENT *\fIevent\fB);\fR
-\fBint ungetmouse(MEVENT *\fIevent\fB);\fR
+\fBint getmouse(MEVENT *\fIevent\fP);
+\fBint ungetmouse(MEVENT *\fIevent\fP);
.PP
-\fBmmask_t mousemask(mmask_t \fInewmask\fB, mmask_t *\fIoldmask\fB);\fR
+\fBmmask_t mousemask(mmask_t \fInewmask\fP, mmask_t *\fIoldmask\fP);
.PP
-\fBbool wenclose(const WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR
+\fBbool wenclose(const WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
.PP
-\fBbool mouse_trafo(int* \fIpY\fB, int* \fIpX\fB, bool \fIto_screen\fB);\fR
-\fBbool wmouse_trafo(const WINDOW* \fIwin\fB,\fR
+\fBbool mouse_trafo(int* \fIpY\fP, int* \fIpX\fP, bool \fIto_screen\fP);
+\fBbool wmouse_trafo(const WINDOW* \fIwin\fP,
\fBint* \fIpY\fB, int* \fIpX\fB, bool \fIto_screen\fB);\fR
.PP
\fBint mouseinterval(int \fIerval\fB);\fR
the screen windows enclose the location of a mouse event.
.SS wmouse_trafo
The \fB\%wmouse_trafo\fP function transforms a given pair of coordinates
-from stdscr-relative coordinates
+from \fB\%stdscr\fP-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
+The resulting \fB\%stdscr\fP-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 \fB\%ripoffline\fP and \fB\%slk_init\fP(3X) calls, for example).
.bP
If the parameter \fIto_screen\fP is \fBTRUE\fP, the pointers
If \fIto_screen\fP is
\fBFALSE\fP, the pointers \fIpY, pX\fP must reference window-relative
coordinates.
-They are converted to stdscr-relative coordinates if the
+They are converted to \fB\%stdscr\fP-relative coordinates if the
window \fIwin\fP encloses this point.
In this case the function returns \fBTRUE\fP.
.bP
.SS mouse_trafo
The \fB\%mouse_trafo\fP function performs the same translation
as \fB\%wmouse_trafo\fP,
-using stdscr for \fIwin\fP.
+using \fB\%stdscr\fP for \fIwin\fP.
.SS mouseinterval
The \fB\%mouseinterval\fP function sets the maximum time (in thousands of a
second) that can elapse between press and release events for them to
Use \fB\%mouseinterval(\-1)\fP to obtain the interval without altering it.
The default is one sixth of a second.
.SS has_mouse
-The \fB\%has_mouse\fP function returns \fBTRUE\fP if the mouse driver has been
-successfully initialized.
+The \fB\%has_mouse\fP function returns \fBTRUE\fP if the mouse driver
+has been successfully initialized,
+and \fBFALSE\fP otherwise.
.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 \fB\%getstr\fP that expects a linefeed for input-loop
termination.
.SH RETURN VALUE
+\fB\%has_mouse\fP,
+\fB\%wenclose\fP,
+\fB\%mouse_trafo\fP,
+and
+\fB\%wmouse_trafo\fP
+return \fBTRUE\fP or \fBFALSE\fP as noted above.
+.PP
\fB\%getmouse\fP and \fB\%ungetmouse\fP
-return the integer \fBERR\fP upon failure or \fBOK\fP
-upon successful completion:
-.RS 3
-.TP 5
-\fB\%getmouse\fP
-returns an error.
+return \fBERR\fP upon failure and \fBOK\fP upon success.
+.PP
+\fB\%getmouse\fP fails if:
.bP
-If no mouse driver was initialized, or
-if the mask parameter is zero,
+no mouse driver was initialized,
.bP
-It returns an error if a mouse event was detected which did not match the
-current \fImousemask\fP.
+the mask of reportable events is zero,
.bP
-It also returns an error if no more events remain in the queue.
-.TP 5
-\fB\%ungetmouse\fP
-returns an error if the FIFO is full.
-.RE
+a mouse event was detected that does not match the mask,
+.bP
+or if no more events remain in the queue.
+.PP
+\fB\%ungetmouse\fP returns an error if the event queue is full.
.PP
\fB\%mousemask\fP
returns the mask of reportable events.
returns the previous interval value, unless
the terminal was not initialized.
In that case, it returns the maximum interval value (166).
-.PP
-\fB\%wenclose\fP and \fB\%wmouse_trafo\fP
-are boolean functions returning \fBTRUE\fP or \fBFALSE\fP depending
-on their test result.
-.SH PORTABILITY
-These calls were designed for \fIncurses\fP, and are not found in SVr4
-\fIcurses\fP, 4.4BSD \fIcurses\fP, or any other previous version of \fIcurses\fP.
-.PP
-SVr4 \fIcurses\fP had support for the mouse in a variant of \fBxterm\fP(1).
-It is mentioned in a few places, but with no supporting documentation:
-.bP
-the \*(``libcurses\*('' manual page lists functions for this feature
-which are prototyped in \fBcurses.h\fP:
-.NS
-extern int mouse_set(long int);
-extern int mouse_on(long int);
-extern int mouse_off(long int);
-extern int request_mouse_pos(void);
-extern int map_button(unsigned long);
-extern void wmouse_position(WINDOW *, int *, int *);
-extern unsigned long getmouse(void), getbmap(void);
-.NE
-.bP
-the \*(``terminfo\*('' manual page lists capabilities for the feature
-.NS
-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
-.NE
-.bP
-the interface made assumptions (as does \fIncurses\fP) about the escape sequences
-sent to and received from the terminal.
-.IP
-For instance
-the SVr4 \fIcurses\fP library used the \fB\%get_mouse\fP 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 \fB\%req_mouse_pos\fP capability.
-.IP
-Those features required a terminal which had been modified to work with \fIcurses\fP.
-They were not part of the X Consortium's xterm.
-.PP
-When developing the xterm mouse support for \fIncurses\fP 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 compatibility with the
-escape sequences.
-.PP
+.SH NOTES
The feature macro \fB\%NCURSES_MOUSE_VERSION\fP is provided so the preprocessor
can be used to test whether these features are present.
If the interface is changed, the value of \fB\%NCURSES_MOUSE_VERSION\fP will be
incremented.
These values for \fB\%NCURSES_MOUSE_VERSION\fP may be
-specified when configuring \fIncurses\fP:
+specified when configuring \fI\%ncurses\fP:
.RS 3
.TP 3
1
The order of the \fB\%MEVENT\fP structure members is not guaranteed.
Additional fields may be added to the structure in the future.
.PP
-Under \fIncurses\fP, these calls are implemented using either
+Under \fI\%ncurses\fP, these calls are implemented using either
xterm's built-in mouse-tracking API or
platform-specific drivers including
.RS 3
.PP
If you are using an unsupported configuration,
mouse events will not be visible to
-\fIncurses\fP (and the \fB\%mousemask\fP function will always
+\fI\%ncurses\fP (and the \fB\%mousemask\fP function will always
return \fB0\fP).
.PP
If the terminfo entry contains a \fBXM\fP string,
corresponds to private mode 1000 of xterm:
.PP
.RS 3
-\\E[?1000%?%p1%{1}%=%th%el%;
+\eE[?1000%?%p1%{1}%=%th%el%;
.RE
.PP
The mouse driver also recognizes a newer xterm private mode 1006, e.g.,
.PP
.RS 3
-\\E[?1006;1000%?%p1%{1}%=%th%el%;
+\eE[?1006;1000%?%p1%{1}%=%th%el%;
.RE
.PP
The \fIz\fP member in the event structure is not presently used.
for use with touch screens (which may be pressure-sensitive) or with
3D-mice/trackballs/power gloves.
.PP
-The \fB\%ALL_MOUSE_EVENTS\fP class does not include \fB\%REPORT_MOUSE_POSITION\fP.
+The \fB\%ALL_MOUSE_EVENTS\fP class does not
+include \fB\%REPORT_MOUSE_POSITION\fP.
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.
+.SH PORTABILITY
+These calls were designed for \fI\%ncurses\fP,
+and are not found in SVr4 \fIcurses\fP,
+4.4BSD \fIcurses\fP, or any other previous version of \fIcurses\fP.
+.PP
+SVr4 \fIcurses\fP had support for the mouse in a variant of \fBxterm\fP(1).
+It is mentioned in a few places, but with no supporting documentation:
+.bP
+the \*(``libcurses\*('' manual page lists functions for this feature
+which are prototyped in \fBcurses.h\fP:
+.PP
+.RS 8
+.EX
+extern int mouse_set(long int);
+extern int mouse_on(long int);
+extern int mouse_off(long int);
+extern int request_mouse_pos(void);
+extern int map_button(unsigned long);
+extern void wmouse_position(WINDOW *, int *, int *);
+extern unsigned long getmouse(void), getbmap(void);
+.EE
+.RE
+.bP
+the \*(``terminfo\*('' manual page lists capabilities for the feature
+.PP
+.RS 8
+.EX
+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
+.EE
+.RE
+.bP
+the interface made assumptions (as does \fI\%ncurses\fP)
+about the escape sequences
+sent to and received from the terminal.
+.IP
+For instance
+the SVr4 \fIcurses\fP library used the \fB\%get_mouse\fP 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 \fB\%req_mouse_pos\fP capability.
+.IP
+Those features required a terminal which had been modified
+to work with \fIcurses\fP.
+They were not part of the X Consortium's xterm.
+.PP
+When developing the xterm mouse support for \fI\%ncurses\fP 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 compatibility with the
+escape sequences.
.SH BUGS
-Mouse events under xterm will not in fact be ignored during cooked mode,
-if they have been enabled by \fB\%mousemask\fP.
-Instead, the xterm mouse
-report sequence will appear in the string read.
+Mouse events from \fI\%xterm\fP are \fInot\fP ignored in cooked mode if
+they have been enabled by \fB\%mousemask\fP.
+Instead,
+the \fI\%xterm\fP mouse report sequence appears 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 should have \fB\%kmous\fP set to \*(``\\E[M\*(''
-(the beginning of the response from xterm for mouse clicks).
-Other values for \fB\%kmous\fP are permitted,
-but under the same assumption,
-i.e., it is the beginning of the response.
+Mouse event reports from \fI\%xterm\fP 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 \fI\%terminfo\fP capability \fB\%kmous\fP to
+\*(``\eE[M\*(''
+(the beginning of the response from \fI\%xterm\fP for mouse clicks).
+Other values of \fB\%kmous\fP are permitted under the same assumption,
+that is,
+the report begins with that sequence.
.PP
-Because there are no standard terminal responses that would serve to identify
-terminals which support the xterm mouse protocol, \fIncurses\fP assumes that
-if \fB\%kmous\fP is defined in the terminal description,
-or if the terminal description's primary name or aliases
-contain the string \*(``xterm\*('',
+Because there are no standard response sequences that serve to identify
+terminals supporting the \fI\%xterm\fP mouse protocol,
+\fI\%ncurses\fP assumes that if \fB\%kmous\fP is defined in the terminal
+description,
+or if the terminal type's primary name or aliases contain the string
+\%\*(``xterm\*('',
then the terminal may send mouse events.
The \fB\%kmous\fP capability is checked first,
-allowing the use of newer xterm mouse protocols
-such as xterm's private mode 1006.
+allowing use of newer \fI\%xterm\fP mouse protocols such as its private
+mode 1006.
.SH SEE ALSO
\fB\%curses\fP(3X),
\fB\%curs_inopts\fP(3X),
projects / ncurses.git / blobdiff