440 lines
15 KiB
Groff
440 lines
15 KiB
Groff
.\"***************************************************************************
|
|
.\" 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 *
|
|
.\" "Software"), to deal in the Software without restriction, including *
|
|
.\" without limitation the rights to use, copy, modify, merge, publish, *
|
|
.\" distribute, distribute with modifications, sublicense, and/or sell *
|
|
.\" copies of the Software, and to permit persons to whom the Software is *
|
|
.\" furnished to do so, subject to the following conditions: *
|
|
.\" *
|
|
.\" The above copyright notice and this permission notice shall be included *
|
|
.\" in all copies or substantial portions of the Software. *
|
|
.\" *
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
|
|
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
|
|
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
|
|
.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
|
|
.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
|
|
.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
|
|
.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
|
|
.\" *
|
|
.\" Except as contained in this notice, the name(s) of the above copyright *
|
|
.\" holders shall not be used in advertising or otherwise to promote the *
|
|
.\" sale, use or other dealings in this Software without prior written *
|
|
.\" authorization. *
|
|
.\"***************************************************************************
|
|
.\"
|
|
.\" $Id: user_caps.5,v 1.16 2020/12/19 21:26:11 tom Exp $
|
|
.TH user_caps 5
|
|
.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
|
|
.ie n .IP \(bu 4
|
|
.el .IP \(bu 2
|
|
..
|
|
.SH NAME
|
|
user_caps \- user-defined terminfo capabilities
|
|
.SH SYNOPSIS
|
|
.B @TIC@ -x, @INFOCMP@ -x
|
|
.SH DESCRIPTION
|
|
.SS Background
|
|
.PP
|
|
Before ncurses 5.0,
|
|
terminfo databases used a \fIfixed repertoire\fP of terminal
|
|
capabilities designed for the SVr2 terminal database in 1984,
|
|
and extended in stages through SVr4 (1989),
|
|
and standardized in the Single Unix Specification beginning in 1995.
|
|
.PP
|
|
Most of the \fIextensions\fP in this fixed repertoire were additions
|
|
to the tables of boolean, numeric and string capabilities.
|
|
Rather than change the meaning of an existing capability, a new name was added.
|
|
The terminfo database uses a binary format; binary compatibility was
|
|
ensured by using a header which gave the number of items in the
|
|
tables for each type of capability.
|
|
The standardization was incomplete:
|
|
.bP
|
|
The \fIbinary format\fP itself is not described
|
|
in the X/Open Curses documentation.
|
|
Only the \fIsource format\fP is described.
|
|
.IP
|
|
Library developers rely upon the SVr4 documentation,
|
|
and reverse-engineering the compiled terminfo files to match the binary format.
|
|
.bP
|
|
Lacking a standard for the binary format, most implementations
|
|
copy the SVr2 binary format, which uses 16-bit signed integers,
|
|
and is limited to 4096-byte entries.
|
|
.IP
|
|
The format cannot represent very large numeric capabilities,
|
|
nor can it represent large numbers of special keyboard definitions.
|
|
.bP
|
|
The tables of capability names differ between implementations.
|
|
.IP
|
|
Although they \fImay\fP provide all of the standard capability names,
|
|
the position in the tables differs because some features were added as needed,
|
|
while others were added (out of order) to comply with X/Open Curses.
|
|
.IP
|
|
While ncurses' repertoire of predefined capabilities is closest to Solaris,
|
|
Solaris's terminfo database has a few differences from
|
|
the list published by X/Open Curses.
|
|
For example, ncurses can be configured with tables which match the
|
|
terminal databases for AIX, HP-UX or OSF/1,
|
|
rather than the default Solaris-like configuration.
|
|
.bP
|
|
In SVr4 curses and ncurses,
|
|
the terminal database is defined at compile-time using a text file
|
|
which lists the different terminal capabilities.
|
|
.IP
|
|
In principle, the text-file can be extended,
|
|
but doing this requires recompiling and reinstalling the library.
|
|
The text-file used in ncurses for terminal capabilities includes
|
|
details for various systems past the documented X/Open Curses features.
|
|
For example, ncurses supports these capabilities in each configuration:
|
|
.RS 8
|
|
.TP 5
|
|
memory_lock
|
|
(meml)
|
|
lock memory above cursor
|
|
.TP 5
|
|
memory_unlock
|
|
(memu)
|
|
unlock memory
|
|
.TP 5
|
|
box_chars_1
|
|
(box1)
|
|
box characters primary set
|
|
.RE
|
|
.IP
|
|
The memory lock/unlock capabilities were included because they were used
|
|
in the X11R6 terminal description for \fBxterm\fP.
|
|
The \fIbox1\fP capability is used in @TIC@ to help with terminal descriptions
|
|
written for AIX.
|
|
.PP
|
|
During the 1990s, some users were reluctant to use terminfo
|
|
in spite of its performance advantages over termcap:
|
|
.bP
|
|
The fixed repertoire prevented users from adding features
|
|
for unanticipated terminal improvements
|
|
(or required them to reuse existing capabilities as a workaround).
|
|
.bP
|
|
The limitation to 16-bit signed integers was also mentioned.
|
|
Because termcap stores everything as a string,
|
|
it could represent larger numbers.
|
|
.PP
|
|
Although termcap's extensibility was rarely used
|
|
(it was never the \fIspeaker\fP who had actually used the feature),
|
|
the criticism had a point.
|
|
ncurses 5.0 provided a way to detect nonstandard capabilities,
|
|
determine their
|
|
type and optionally store and retrieve them in a way which did not interfere
|
|
with other applications.
|
|
These are referred to as \fIuser-defined capabilities\fP because no
|
|
modifications to the toolset's predefined capability names are needed.
|
|
.PP
|
|
The ncurses utilities \fB@TIC@\fP and \fB@INFOCMP@\fP have a command-line
|
|
option \*(``\-x\*('' to control whether the nonstandard capabilities
|
|
are stored or retrieved.
|
|
A library function \fBuse_extended_names\fP
|
|
is provided for the same purpose.
|
|
.PP
|
|
When compiling a terminal database, if \*(``\-x\*('' is set,
|
|
\fB@TIC@\fP will store a user-defined capability if the capability name is not
|
|
one of the predefined names.
|
|
.PP
|
|
Because ncurses provides a termcap library interface,
|
|
these user-defined capabilities may be visible to termcap applications:
|
|
.bP
|
|
The termcap interface (like all implementations of termcap)
|
|
requires that the capability names are 2-characters.
|
|
.IP
|
|
When the capability is simple enough for use in a termcap application,
|
|
it is provided as a 2-character name.
|
|
.bP
|
|
There are other
|
|
user-defined capabilities which refer to features not usable in termcap,
|
|
e.g., parameterized strings that use more than two parameters
|
|
or use more than the trivial expression support provided by termcap.
|
|
For these, the terminfo database should have only capability names with
|
|
3 or more characters.
|
|
.bP
|
|
Some terminals can send distinct strings for special keys (cursor-,
|
|
keypad- or function-keys) depending on modifier keys (shift, control, etc.).
|
|
While terminfo and termcap have a set of 60 predefined function-key names,
|
|
to which a series of keys can be assigned,
|
|
that is insufficient for more than a dozen keys multiplied by more than
|
|
a couple of modifier combinations.
|
|
The ncurses database uses a convention based on \fBxterm\fP to
|
|
provide extended special-key names.
|
|
.IP
|
|
Fitting that into termcap's limitation of 2-character names
|
|
would be pointless.
|
|
These extended keys are available only with terminfo.
|
|
.SS Recognized capabilities
|
|
.PP
|
|
The ncurses library uses the user-definable capabilities.
|
|
While the terminfo database may have other extensions,
|
|
ncurses makes explicit checks for these:
|
|
.RS 3
|
|
.TP 3
|
|
AX
|
|
\fIboolean\fP, asserts that the terminal interprets SGR 39 and SGR 49
|
|
by resetting the foreground and background color, respectively, to the default.
|
|
.IP
|
|
This is a feature recognized by the \fBscreen\fP program as well.
|
|
.TP 3
|
|
E3
|
|
\fIstring\fP, tells how to clear the terminal's scrollback buffer.
|
|
When present, the \fBclear\fP(1) program sends this before clearing
|
|
the terminal.
|
|
.IP
|
|
The command \*(``\fBtput clear\fP\*('' does the same thing.
|
|
.TP 3
|
|
RGB
|
|
\fIboolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
|
|
to assert that the
|
|
\fBset_a_foreground\fP and
|
|
\fBset_a_background\fP capabilities correspond to \fIdirect colors\fP,
|
|
using an RGB (red/green/blue) convention.
|
|
This capability allows the \fBcolor_content\fP function to
|
|
return appropriate values without requiring the application
|
|
to initialize colors using \fBinit_color\fP.
|
|
.IP
|
|
The capability type determines the values which ncurses sees:
|
|
.RS 3
|
|
.TP 3
|
|
\fIboolean\fP
|
|
implies that the number of bits for red, green and blue are the same.
|
|
Using the maximum number of colors,
|
|
ncurses adds two, divides that sum by three, and assigns the result
|
|
to red, green and blue in that order.
|
|
.IP
|
|
If the number of bits needed for the number of colors is not a multiple
|
|
of three, the blue (and green) components lose in comparison to red.
|
|
.TP 3
|
|
\fInumber\fP
|
|
tells ncurses what result to add to red, green and blue.
|
|
If ncurses runs out of bits,
|
|
blue (and green) lose just as in the \fIboolean\fP case.
|
|
.TP 3
|
|
\fIstring\fP
|
|
explicitly list the number of bits used for red, green and blue components
|
|
as a slash-separated list of decimal integers.
|
|
.RE
|
|
.IP
|
|
Because there are several RGB encodings in use,
|
|
applications which make assumptions about the number of bits per color
|
|
are unlikely to work reliably.
|
|
As a trivial case, for example, one could define \fBRGB#1\fP
|
|
to represent the standard eight ANSI colors, i.e., one bit per color.
|
|
.TP 3
|
|
U8
|
|
\fInumber\fP,
|
|
asserts that ncurses must use Unicode values for line-drawing characters,
|
|
and that it should ignore the alternate character set capabilities
|
|
when the locale uses UTF-8 encoding.
|
|
For more information, see the discussion of
|
|
\fBNCURSES_NO_UTF8_ACS\fP in \fBncurses\fP(3X).
|
|
.IP
|
|
Set this capability to a nonzero value to enable it.
|
|
.TP 3
|
|
XM
|
|
\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
|
|
Several terminals provide the ability to send distinct strings for
|
|
combinations of modified special keys.
|
|
There is no standard for what those keys can send.
|
|
.PP
|
|
Since 1999, \fBxterm\fP has supported
|
|
\fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce
|
|
distinct special-key strings.
|
|
In a terminal description, ncurses has no special knowledge of the
|
|
modifiers used.
|
|
Applications can use the \fInaming convention\fP established for \fBxterm\fP
|
|
to find these special keys in the terminal description.
|
|
.PP
|
|
Starting with the curses convention that \fIkey names\fP begin with \*(``k\*(''
|
|
and that shifted special keys are an uppercase name,
|
|
ncurses' terminal database defines these names to which a suffix is added:
|
|
.RS 5
|
|
.TS
|
|
tab(/) ;
|
|
l l .
|
|
\fIName\fR/\fIDescription\fR
|
|
_
|
|
kDC/special form of kdch1 (delete character)
|
|
kDN/special form of kcud1 (cursor down)
|
|
kEND/special form of kend (End)
|
|
kHOM/special form of khome (Home)
|
|
kLFT/special form of kcub1 (cursor-left or cursor-back)
|
|
kNXT/special form of knext (Next, or Page-Down)
|
|
kPRV/special form of kprev (Prev, or Page-Up)
|
|
kRIT/special form of kcuf1 (cursor-right, or cursor-forward)
|
|
kUP/special form of kcuu1 (cursor-up)
|
|
.TE
|
|
.RE
|
|
.PP
|
|
These are the suffixes used to denote the modifiers:
|
|
.RS 5
|
|
.TS
|
|
tab(/) ;
|
|
l l .
|
|
\fIValue\fR/\fIDescription\fR
|
|
_
|
|
2/Shift
|
|
3/Alt
|
|
4/Shift + Alt
|
|
5/Control
|
|
6/Shift + Control
|
|
7/Alt + Control
|
|
8/Shift + Alt + Control
|
|
9/Meta
|
|
10/Meta + Shift
|
|
11/Meta + Alt
|
|
12/Meta + Alt + Shift
|
|
13/Meta + Ctrl
|
|
14/Meta + Ctrl + Shift
|
|
15/Meta + Ctrl + Alt
|
|
16/Meta + Ctrl + Alt + Shift
|
|
.TE
|
|
.RE
|
|
.PP
|
|
None of these are predefined; terminal descriptions can refer to \fInames\fP
|
|
which ncurses will allocate at runtime to \fIkey-codes\fP.
|
|
To use these keys in an ncurses program, an application could do this:
|
|
.bP
|
|
using a list of extended key \fInames\fP,
|
|
ask \fBtigetstr\fP(3X) for their values, and
|
|
.bP
|
|
given the list of values,
|
|
ask \fBkey_defined\fP(3X) for the \fIkey-code\fP which
|
|
would be returned for those keys by \fBwgetch\fP(3X).
|
|
.PP
|
|
.\"
|
|
.SH PORTABILITY
|
|
.PP
|
|
The \*(``\-x\*('' extension feature of \fB@TIC@\fP and \fB@INFOCMP@\fP
|
|
has been adopted in NetBSD curses.
|
|
That implementation stores user-defined capabilities,
|
|
but makes no use of these capabilities itself.
|
|
.\"
|
|
.SH SEE ALSO
|
|
.PP
|
|
\fB@INFOCMP@\fR(1M),
|
|
\fB@TIC@\fR(1M).
|
|
.PP
|
|
The terminal database section
|
|
.I "NCURSES USER-DEFINABLE CAPABILITIES"
|
|
summarizes commonly-used user-defined capabilities
|
|
which are used in the terminal descriptions.
|
|
Some of those features are mentioned in \fBscreen\fR(1) or \fBtmux\fR(1).
|
|
.PP
|
|
.I "XTerm Control Sequences"
|
|
provides further information on the \fBxterm\fP features
|
|
which are used in these extended capabilities.
|
|
.\"
|
|
.SH AUTHORS
|
|
.PP
|
|
Thomas E. Dickey
|
|
.br
|
|
beginning with ncurses 5.0 (1999)
|