.\"***************************************************************************
-.\" Copyright (c) 2017,2018 Free Software Foundation, Inc. *
+.\" Copyright 2018-2019,2020 Thomas E. Dickey *
+.\" Copyright 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: user_caps.5,v 1.9 2018/07/28 22:05:23 tom Exp $
+.\" $Id: user_caps.5,v 1.12 2020/02/02 23:34:34 tom Exp $
.TH user_caps 5
.ie \n(.g .ds `` \(lq
.el .ds `` ``
\fIstring\fP,
override ncurses's built-in string which
enables/disables \fBxterm\fP mouse mode.
+.IP
+ncurses sends a character sequence to the terminal to initialize mouse mode,
+and when the user clicks the mouse buttons or (in certain modes) moves the
+mouse, handles the characters sent back by the terminal to tell it what
+was done with the mouse.
+.IP
+The mouse protocol is enabled when
+the \fImask\fP passed in the \fBmousemask\fP function is nonzero.
+By default, ncurses handles the responses for the X11 xterm mouse protocol.
+It also knows about the \fISGR 1006\fP xterm mouse protocol,
+but must to be told to look for this specifically.
+It will not be able to guess which mode is used,
+because the responses are enough alike that only confusion would result.
+.IP
+The \fBXM\fP capability has a single parameter.
+If nonzero, the mouse protocol should be enabled.
+If zero, the mouse protocol should be disabled.
+ncurses inspects this capability if it is present,
+to see whether the 1006 protocol is used.
+If so, it expects the responses to use the \fISGR 1006\fP xterm mouse protocol.
+.IP
+The xterm mouse protocol is used by other terminal emulators.
+The terminal database uses building-blocks for the various xterm mouse
+protocols which can be used in customized terminal descriptions.
+.IP
+The terminal database building blocks for this mouse
+feature also have an experimental capability \fIxm\fP.
+The \*(``xm\*('' capability describes the mouse response.
+Currently there is no interpreter which would use this
+information to make the mouse support completely data-driven.
+.IP
+\fIxm\fP shows the format of the mouse responses.
+In this experimental capability, the parameters are
+.RS 5
+.TP 5
+.I p1
+y-ordinate
+.TP 5
+.I p2
+x-ordinate
+.TP 5
+.I p3
+button
+.TP 5
+.I p4
+state, e.g., pressed or released
+.TP 5
+.I p5
+y-ordinate starting region
+.TP 5
+.I p6
+x-ordinate starting region
+.TP 5
+.I p7
+y-ordinate ending region
+.TP 5
+.I p8
+x-ordinate ending region
+.RE
+.IP
+Here are examples from the terminal database for the most commonly used
+xterm mouse protocols:
+.IP
+.nf
+ xterm+x11mouse|X11 xterm mouse protocol,
+ kmous=\\E[M, XM=\\E[?1000%?%p1%{1}%=%th%el%;,
+ xm=\\E[M
+ %?%p4%t%p3%e%{3}%;%'\ '%+%c
+ %p2%'!'%+%c
+ %p1%'!'%+%c,
+
+ xterm+sm+1006|xterm SGR-mouse,
+ kmous=\\E[<, XM=\\E[?1006;1000%?%p1%{1}%=%th%el%;,
+ xm=\\E[<%i%p3%d;
+ %p1%d;
+ %p2%d;
+ %?%p4%tM%em%;,
+.fi
.
.SS Extended key-definitions
.PP