.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_mouse.3x,v 1.89 2024/02/17 21:43:03 tom Exp $
-.TH curs_mouse 3X 2024-02-17 "ncurses 6.4" "Library calls"
+.\" $Id: curs_mouse.3x,v 1.98 2024/04/20 19:02:07 tom Exp $
+.TH curs_mouse 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.PP
\fBbool has_mouse(void);
.PP
+\fBmmask_t mousemask(mmask_t \fInewmask\fP, mmask_t *\fIoldmask\fP);
+.PP
\fBint getmouse(MEVENT *\fIevent\fP);
\fBint ungetmouse(MEVENT *\fIevent\fP);
.PP
-\fBmmask_t mousemask(mmask_t \fInewmask\fP, mmask_t *\fIoldmask\fP);
-.PP
\fBbool wenclose(const WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
.PP
\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
+.ti +18n \" "bool wmouse_trafo("
+\fBint* \fIpY\fB, int* \fIpX\fB, bool \fIto_screen\fB);
.PP
\fBint mouseinterval(int \fIerval\fB);\fR
.fi
\fB\%ncurses\fP(3X).
Mouse events are represented by \fB\%KEY_MOUSE\fP
pseudo-key values in the \fB\%wgetch\fP(3X) input stream.
+.SS has_mouse
+The \fB\%has_mouse\fP function returns \fBTRUE\fP if the mouse driver
+has been successfully initialized,
+and \fBFALSE\fP otherwise.
+.PP
+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 \fB\%getstr\fP that expects a linefeed for input-loop
+termination.
.SS mousemask
To make mouse events visible, use the \fB\%mousemask\fP function.
This sets the mouse events to be reported.
this function fills the indicated location with the previous value of the
current screen's mouse event mask.
.PP
-As a side effect, setting a zero mousemask may turn off the mouse pointer;
+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.
.SS "Mouse Events"
If the parameter is a pad,
\fB\%wenclose\fP uses the most recent screen coordinates used for
this pad in
-\fP\%prefresh\fP(3X) or
-\fP\%pnoutrefresh\fP(3X).
+\fB\%prefresh\fP(3X) or
+\fB\%pnoutrefresh\fP(3X).
.SS wmouse_trafo
The \fB\%wmouse_trafo\fP function transforms a given pair of coordinates
from \fB\%stdscr\fP-relative coordinates
The resulting \fB\%stdscr\fP-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 \fB\%ripoffline\fP and \fB\%slk_init\fP(3X) calls, for example).
+(see the \fB\%ripoffline\fP(3X) and \fB\%slk_init\fP(3X) calls, for example).
.bP
If the parameter \fIto_screen\fP is \fBTRUE\fP, the pointers
\fIpY, pX\fP must reference the coordinates of a location
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
-be resolved as a click.
+be resolved as a
+.IR 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\*(''.
.PP
Calling \fB\%mouseinterval(0)\fP disables click resolution.
-When ncurses detects a mouse event,
+When
+.I \%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.
The mouse interval is set to one sixth of a second
when the corresponding screen is initialized,
e.g., in \fBinitscr\fP(3X) or \fBsetupterm\fP(3X).
-.SS has_mouse
-The \fB\%has_mouse\fP function returns \fBTRUE\fP if the mouse driver
-has been successfully initialized,
-and \fBFALSE\fP otherwise.
-.PP
-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 \fB\%getstr\fP that expects a linefeed for input-loop
-termination.
.SH RETURN VALUE
\fB\%has_mouse\fP,
\fB\%wenclose\fP,
Additional fields may be added to the structure in the future.
.PP
Under
-.I \%ncurses,
+.IR \%ncurses ,
these calls are implemented using either
.IR \%xterm 's
built-in mouse-tracking API or
They are distinct.
For example,
in
-.I \%xterm,
+.IR \%xterm ,
wheel/scrolling mice send position reports as a sequence of
presses of buttons 4 or 5 without matching button-releases.
.SH EXTENSIONS
.IP
Those features required a terminal program that had been modified
to work with SVr4
-.I curses.
+.IR curses .
They were not part of the X Consortium's
-.I \%xterm.
+.IR \%xterm .
.PP
When developing the
.I \%xterm
Later, in 1998, Mark Hesseling provided support in
.I \%PDCurses
2.3 using the SVr4 interface.
-.I \%PDCurses,
+.IR \%PDCurses ,
however,
does not use video terminals,
making it unnecessary to be concerned about compatibility with the
projects / ncurses.git / blobdiff