1 files changed, 62 insertions, 32 deletions
diff --git a/upstream/debian-unstable/man3/mouse.3ncurses b/upstream/debian-unstable/man3/mouse.3ncurses
index 1ddf6c3c..051a6670 100644
--- a/upstream/debian-unstable/man3/mouse.3ncurses
+++ b/upstream/debian-unstable/man3/mouse.3ncurses
@@ -28,8 +28,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_mouse.3x,v 1.86 2024/01/13 22:05:39 tom Exp $
-.TH mouse 3NCURSES 2024-01-13 "ncurses 6.4" "Library calls"
+.\" $Id: curs_mouse.3x,v 1.98 2024/04/20 19:02:07 tom Exp $
+.TH mouse 3NCURSES 2024-04-20 "ncurses 6.5" "Library calls"
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
@@ -69,16 +69,17 @@ get mouse events in \fIcurses\fR
 .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
@@ -87,6 +88,15 @@ These functions provide an interface to mouse events from
 \fB\%ncurses\fP(3NCURSES).
 Mouse events are represented by \fB\%KEY_MOUSE\fP
 pseudo-key values in the \fB\%wgetch\fP(3NCURSES) 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.
@@ -103,7 +113,7 @@ If \fIoldmask\fP is non-\fBNULL\fP,
 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"
@@ -184,34 +194,41 @@ 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.
+.PP
+If the parameter is a pad,
+\fB\%wenclose\fP uses the most recent screen coordinates used for
+this pad in
+\fB\%prefresh\fP(3NCURSES) or
+\fB\%pnoutrefresh\fP(3NCURSES).
 .SS wmouse_trafo
 The \fB\%wmouse_trafo\fP function transforms a given pair of coordinates
 from \fB\%stdscr\fP-relative coordinates
 to coordinates relative to the given window or vice versa.
 The resulting \fB\%stdscr\fP-relative coordinates are not always
-identical to window-relative coordinates due to the mechanism to reserve
+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(3NCURSES) calls, for example).
+(see the \fB\%ripoffline\fP(3NCURSES) and \fB\%slk_init\fP(3NCURSES) 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
 inside the window \fIwin\fP.
-They are converted to window-relative coordinates and returned
+They are converted to \fB\%stdscr\fP-relative coordinates and returned
 through the pointers.
 If the conversion was successful, the function returns \fBTRUE\fP.
-.bP
+.IP
 If one of the parameters was \fBNULL\fP or the location is
 not inside the window, \fBFALSE\fP is returned.
 .bP
 If \fIto_screen\fP is
-\fBFALSE\fP, the pointers \fIpY, pX\fP must reference window-relative
-coordinates.
-They are converted to \fB\%stdscr\fP-relative coordinates if the
+\fBFALSE\fP, the pointers \fIpY, pX\fP must reference
+\fB\%stdscr\fP-relative coordinates.
+They are converted to window-relative coordinates if the
 window \fIwin\fP encloses this point.
 In this case the function returns \fBTRUE\fP.
-.bP
+.IP
 If one of the parameters is \fBNULL\fP or the point is not inside the
 window, \fBFALSE\fP is returned.
+.PP
 The referenced coordinates
 are only replaced by the converted coordinates if the transformation was
 successful.
@@ -220,22 +237,34 @@ The \fB\%mouse_trafo\fP function performs the same translation
 as \fB\%wmouse_trafo\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
-be recognized as a click.
-Use \fB\%mouseinterval(0)\fP to disable click resolution.
+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
+.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
+.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.
+If the timeout expires without input activity
+(which would happen with a zero interval),
+then no click resolution will occur.
+.PP
 This function returns the previous interval value.
 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,
-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.
+The mouse interval is set to one sixth of a second
+when the corresponding screen is initialized,
+e.g., in \fB\%initscr\fP(3NCURSES) or \fB\%setupterm\fP(3NCURSES).
 .SH RETURN VALUE
 \fB\%has_mouse\fP,
 \fB\%wenclose\fP,
@@ -271,7 +300,7 @@ 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
-.I \%ncurses,
+.IR \%ncurses ,
 these calls are implemented using either
 .IR \%xterm 's
 built-in mouse-tracking API or
@@ -324,7 +353,7 @@ include \fB\%REPORT_MOUSE_POSITION\fP.
 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
@@ -428,9 +457,9 @@ where the mouse was using the \fB\%req_mouse_pos\fP capability.
 .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
@@ -442,7 +471,7 @@ lack of documentation.
 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
@@ -491,5 +520,6 @@ such as its private mode 1006.
 \fB\%ncurses\fP(3NCURSES),
 \fB\%inopts\fP(3NCURSES),
 \fB\%kernel\fP(3NCURSES),
+\fB\%pad\fP(3NCURSES),
 \fB\%slk\fP(3NCURSES),
 \fB\%curses_variables\fP(3NCURSES)