-.\" $Id: curs_mouse.3x,v 1.71 2023/09/16 23:37:03 tom Exp $
-.TH curs_mouse 3X 2023-09-16 "ncurses 6.4" "Library calls"
+.\" $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"
\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 {\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
\fBbool wmouse_trafo(const WINDOW* \fIwin\fB,\fR
\fBint* \fIpY\fB, int* \fIpX\fB, bool \fIto_screen\fB);\fR
\fBbool wmouse_trafo(const WINDOW* \fIwin\fB,\fR
\fBint* \fIpY\fB, int* \fIpX\fB, bool \fIto_screen\fB);\fR
-\fBncurses\fP(3X).
-Mouse events are represented by \fBKEY_MOUSE\fP
-pseudo-key values in the \fBwgetch\fP(3X) input stream.
+\fB\%ncurses\fP(3X).
+Mouse events are represented by \fB\%KEY_MOUSE\fP
+pseudo-key values in the \fB\%wgetch\fP(3X) input stream.
This sets the mouse events to be reported.
By default, no mouse events are reported.
.bP
This sets the mouse events to be reported.
By default, no mouse events are reported.
.bP
this function fills the indicated location with the previous value of the
current screen's mouse event mask.
.PP
this function fills the indicated location with the previous value of the
current screen's mouse event mask.
.PP
BUTTON1_PRESSED mouse button 1 down
BUTTON1_RELEASED mouse button 1 up
BUTTON1_CLICKED mouse button 1 clicked
BUTTON1_PRESSED mouse button 1 down
BUTTON1_RELEASED mouse button 1 up
BUTTON1_CLICKED mouse button 1 clicked
-calling the \fBwgetch\fP function on that window may return
-\fBKEY_MOUSE\fP as an indicator that a mouse event has been queued.
+calling the \fB\%wgetch\fP function on that window may return
+\fB\%KEY_MOUSE\fP as an indicator that a mouse event has been queued.
This function will return \fBOK\fP if a mouse event
is actually visible in the given window, \fBERR\fP otherwise.
This function will return \fBOK\fP if a mouse event
is actually visible in the given window, \fBERR\fP otherwise.
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 corresponding data in the queue is marked invalid.
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 corresponding data in the queue is marked invalid.
character-cell coordinates is enclosed by a given window, returning \fBTRUE\fP
if it is and \fBFALSE\fP otherwise.
It is useful for determining what subset of
the screen windows enclose the location of a mouse event.
.SS wmouse_trafo
character-cell coordinates is enclosed by a given window, returning \fBTRUE\fP
if it is and \fBFALSE\fP otherwise.
It is useful for determining what subset of
the screen windows enclose the location of a mouse event.
.SS wmouse_trafo
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
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
.bP
If the parameter \fIto_screen\fP is \fBTRUE\fP, the pointers
\fIpY, pX\fP must reference the coordinates of a location
.bP
If the parameter \fIto_screen\fP is \fBTRUE\fP, the pointers
\fIpY, pX\fP must reference the coordinates of a location
window, \fBFALSE\fP is returned.
The referenced coordinates
are only replaced by the converted coordinates if the transformation was
successful.
.SS mouse_trafo
window, \fBFALSE\fP is returned.
The referenced coordinates
are only replaced by the converted coordinates if the transformation was
successful.
.SS mouse_trafo
successfully initialized.
.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
successfully initialized.
.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
returns the previous interval value, unless
the terminal was not initialized.
In that case, it returns the maximum interval value (166).
.PP
returns the previous interval value, unless
the terminal was not initialized.
In that case, it returns the maximum interval value (166).
.PP
-These calls were designed for \fBncurses\fP(3X), and are not found in SVr4
-curses, 4.4BSD curses, or any other previous version of curses.
+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.
It is mentioned in a few places, but with no supporting documentation:
.bP
the \*(``libcurses\*('' manual page lists functions for this feature
It is mentioned in a few places, but with no supporting documentation:
.bP
the \*(``libcurses\*('' manual page lists functions for this feature
terminal which mouse button events it should send,
passing the mouse-button bit-mask to the terminal.
Also, it could ask the terminal
terminal which mouse button events it should send,
passing the mouse-button bit-mask to the terminal.
Also, it could ask the terminal
Eric Raymond was uninterested in using the same interface due to its
lack of documentation.
Later, in 1998, Mark Hesseling provided support in
Eric Raymond was uninterested in using the same interface due to its
lack of documentation.
Later, in 1998, Mark Hesseling provided support in
.PP
If you are using an unsupported configuration,
mouse events will not be visible to
.PP
If you are using an unsupported configuration,
mouse events will not be visible to
for use with touch screens (which may be pressure-sensitive) or with
3D-mice/trackballs/power gloves.
.PP
for use with touch screens (which may be pressure-sensitive) or with
3D-mice/trackballs/power gloves.
.PP
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 BUGS
Mouse events under xterm will not in fact be ignored during cooked mode,
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 BUGS
Mouse events under xterm will not in fact be ignored during cooked mode,
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.
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.
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
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\fP assumes that
-if \fBkmous\fP is defined in the terminal description,
+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\*('',
then the terminal may send mouse events.
or if the terminal description's primary name or aliases
contain the string \*(``xterm\*('',
then the terminal may send mouse events.
-\fBcurses\fP(3X),
-\fBcurs_inopts\fP(3X),
-\fBcurs_kernel\fP(3X),
-\fBcurs_slk\fP(3X),
-\fBcurs_variables\fP(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_inopts\fP(3X),
+\fB\%curs_kernel\fP(3X),
+\fB\%curs_slk\fP(3X),
+\fB\%curs_variables\fP(3X)