ncurses 6.3 - patch 20220827

[ncurses.git] / man / curs_mouse.3x

diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x
index 19795ca7151bf7be50c84a193464ffbd7e2afd02..25d692011672a74805bed32eee985ccc132791e2 100644 (file)
--- a/man/curs_mouse.3x
+++ b/man/curs_mouse.3x
@@ -1,6 +1,6 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey                                *
+.\" Copyright 2018-2022,2022 Thomas E. Dickey                                *
 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
@@ -28,7 +28,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_mouse.3x,v 1.57 2021/12/25 21:49:32 tom Exp $
+.\" $Id: curs_mouse.3x,v 1.59 2022/02/12 20:05:11 tom Exp $
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
 .ie \n(.g .ds '' \(rq
@@ -69,28 +69,28 @@
 .PP
 .nf
 \fBtypedef struct {\fP
-\fB    short id;         \fP\fI/* ID to distinguish multiple devices */\fP
-\fB    int x, y, z;      \fP\fI/* event coordinates */\fP
-\fB    mmask_t bstate;   \fP\fI/* button state bits */\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
 .fi
 .PP
 \fBbool has_mouse(void);\fP
 .sp
-\fBint getmouse(MEVENT *\fP\fIevent\fP\fB);\fP
+\fBint getmouse(MEVENT *\fIevent\fB);\fR
 .br
-\fBint ungetmouse(MEVENT *\fP\fIevent\fP\fB);\fP
+\fBint ungetmouse(MEVENT *\fIevent\fB);\fR
 .sp
-\fBmmask_t mousemask(mmask_t \fP\fInewmask\fP\fB, mmask_t *\fP\fIoldmask\fP\fB);\fP
+\fBmmask_t mousemask(mmask_t \fInewmask\fB, mmask_t *\fIoldmask\fB);\fR
 .sp
-\fBbool wenclose(const WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fP
+\fBbool wenclose(const WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR
 .sp
-\fBbool mouse_trafo(int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB, bool \fP\fIto_screen\fP\fB);\fP
+\fBbool mouse_trafo(int* \fIpY\fB, int* \fIpX\fB, bool \fIto_screen\fB);\fR
 .br
-\fBbool wmouse_trafo(const WINDOW* \fP\fIwin\fP\fB,\fP
-                  \fBint* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB, bool \fP\fIto_screen\fP\fB);\fP
+\fBbool wmouse_trafo(const WINDOW* \fIwin\fB,\fR
+                  \fBint* \fIpY\fB, int* \fIpX\fB, bool \fIto_screen\fB);\fR
 .sp
-\fBint mouseinterval(int \fP\fIerval\fP\fB);\fP
+\fBint mouseinterval(int \fIerval\fB);\fR
 .br
 .SH DESCRIPTION
 These functions provide an interface to mouse events from
@@ -100,14 +100,19 @@ pseudo-key values in the \fBwgetch\fP(3X) input stream.
 .SS mousemask
 .PP
 To make mouse events visible, use the \fBmousemask\fP function.
-This will set
-the mouse events to be reported.
+This sets the mouse events to be reported.
 By default, no mouse events are reported.
-The function will return a mask to indicate which of the specified mouse events
-can be reported; on complete failure it returns 0.
-If oldmask is non-NULL,
-this function fills the indicated location with the previous value of the given
-window's mouse event mask.
+.bP
+The function returns an updated copy of \fInewmask\fP
+to indicate which of the specified mouse events can be reported.
+.IP
+If the screen has not been initialized,
+or if the terminal does not support mouse-events,
+this function returns 0.
+.bP
+If \fIoldmask\fP is non-NULL,
+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;
 setting a nonzero mask may turn it on.
@@ -255,6 +260,9 @@ returns an error.
 If no mouse driver was initialized, or
 if the mask parameter is zero,
 .bP
+It returns an error if a mouse event was detected which did not match the
+current \fImousemask\fP.
+.bP
 It also returns an error if no more events remain in the queue.
 .TP 5
 \fBungetmouse\fP
@@ -411,6 +419,7 @@ allowing the use of newer xterm mouse protocols
 such as xterm's private mode 1006.
 .SH SEE ALSO
 \fBcurses\fP(3X),
+\fBcurs_inopts\fP(3X),
 \fBcurs_kernel\fP(3X),
 \fBcurs_slk\fP(3X),
 \fBcurs_variables\fP(3X).