ncurses 6.2 - patch 20201219
[ncurses.git] / man / curs_mouse.3x
index b7cf4c6ca2399fae8b21bec9785c5948d0fab2b7..c18be3fa3378ed4eebd1bcde57fca5f6d8cebad9 100644 (file)
@@ -1,6 +1,7 @@
 '\" t
 .\"***************************************************************************
-.\" Copyright (c) 1998-2014,2015 Free Software Foundation, Inc.              *
+.\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
+.\" Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_mouse.3x,v 1.42 2015/07/21 09:27:39 tom Exp $
+.\" $Id: curs_mouse.3x,v 1.53 2020/10/17 23:25:08 tom Exp $
+.ie \n(.g .ds `` \(lq
+.el       .ds `` ``
+.ie \n(.g .ds '' \(rq
+.el       .ds '' ''
+.de NS
+.ie n  .sp
+.el    .sp .5
+.ie n  .in +4
+.el    .in +2
+.nf
+.ft C                  \" Courier
+..
+.de NE
+.fi
+.ft R
+.ie n  .in -4
+.el    .in -2
+..
 .de bP
-.IP \(bu 4
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
 ..
 .TH curs_mouse 3X ""
 .na
 .fi
 .PP
 \fBbool has_mouse(void);\fR
-.br
+.sp
 \fBint getmouse(MEVENT *\fP\fIevent\fP\fB);\fR
 .br
 \fBint ungetmouse(MEVENT *\fP\fIevent\fP\fB);\fR
-.br
+.sp
 \fBmmask_t mousemask(mmask_t \fP\fInewmask\fP\fB, mmask_t *\fP\fIoldmask\fP\fB);\fR
-.br
+.sp
 \fBbool wenclose(const WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
-.br
+.sp
 \fBbool mouse_trafo(int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB, bool \fP\fIto_screen\fP\fB);\fR
 .br
-\fBbool wmouse_trafo(const WINDOW* \fP\fIwin\fP\fB, int* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB,\fR
-.br
-       \fBbool \fP\fIto_screen\fP\fB);\fR
-.br
+\fBbool wmouse_trafo(const WINDOW* \fP\fIwin\fP\fB,\fR
+                  \fBint* \fP\fIpY\fP\fB, int* \fP\fIpX\fP\fB, bool \fP\fIto_screen\fP\fB);\fR
+.sp
 \fBint mouseinterval(int \fP\fIerval\fP\fB);\fR
 .br
 .SH DESCRIPTION
 These functions provide an interface to mouse events from
 \fBncurses\fR(3X).
 Mouse events are represented by \fBKEY_MOUSE\fR
-pseudo-key values in the \fBwgetch\fR input stream.
+pseudo-key values in the \fBwgetch\fR(3X) input stream.
 .SS mousemask
 .PP
 To make mouse events visible, use the \fBmousemask\fR function.
@@ -177,7 +196,7 @@ 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
-(see the \fBripoffline\fP and \fBslk_init\fR calls, for example).
+(see the \fBripoffline\fP and \fBslk_init\fR(3X) calls, for example).
 .bP
 If the parameter \fBto_screen\fR is \fBTRUE\fR, the pointers
 \fBpY, pX\fR must reference the coordinates of a location
@@ -257,6 +276,52 @@ on their test result.
 These calls were designed for \fBncurses\fR(3X), and are not found in SVr4
 curses, 4.4BSD curses, or any other previous version of curses.
 .PP
+SVr4 curses had support for the mouse in a variant of \fBxterm\fP.
+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 ncurses) about the escape sequences
+sent to and received from the terminal.
+.IP
+For instance
+the SVr4 curses library used the \fBget_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 \fBreq_mouse_pos\fP capability.
+.IP
+Those features required a terminal which had been modified to work with curses.
+They were not part of the X Consortium's xterm.
+.PP
+When developing the xterm mouse support for ncurses 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
 The feature macro \fBNCURSES_MOUSE_VERSION\fR is provided so the preprocessor
 can be used to test whether these features are present.
 If the interface is changed, the value of \fBNCURSES_MOUSE_VERSION\fR will be
@@ -305,6 +370,12 @@ corresponds to private mode 1000 of xterm:
 \\E[?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%;
+.RE
+.PP
 The \fIz\fP member in the event structure is not presently used.
 It is intended
 for use with touch screens (which may be pressure-sensitive) or with
@@ -323,7 +394,7 @@ 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.
-Your terminfo description should have \fBkmous\fR set to "\\E[M"
+Your terminfo description should have \fBkmous\fR set to \*(``\\E[M\*(''
 (the beginning of the response from xterm for mouse clicks).
 Other values for \fBkmous\fR are permitted,
 but under the same assumption,
@@ -331,9 +402,13 @@ 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\fR assumes that
-if your $TERM environment variable contains "xterm",
-or \fBkmous\fR is defined in
-the terminal description, then the terminal may send mouse events.
+if \fBkmous\fR 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.
+The \fBkmous\fP capability is checked first,
+allowing the use of newer xterm mouse protocols
+such as xterm's private mode 1006.
 .SH SEE ALSO
 \fBcurses\fR(3X),
 \fBcurs_kernel\fR(3X),