X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_mouse.3x;h=775bc33f01db5f4b94b4360b86e74bd154613ff0;hp=b7cf4c6ca2399fae8b21bec9785c5948d0fab2b7;hb=c0f109a299a82a33c16bd7af942a12ce9aefaaf0;hpb=6a530b46563470c2ca73579d1994a0c8e275dd98 diff --git a/man/curs_mouse.3x b/man/curs_mouse.3x index b7cf4c6c..775bc33f 100644 --- a/man/curs_mouse.3x +++ b/man/curs_mouse.3x @@ -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 * @@ -27,9 +28,28 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_mouse.3x,v 1.42 2015/07/21 09:27:39 tom Exp $ +.\" $Id: curs_mouse.3x,v 1.52 2020/02/02 23:34:34 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 @@ -77,7 +97,7 @@ 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 +197,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 +277,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 +371,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 +395,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 +403,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),