aboutsummaryrefslogtreecommitdiff
path: root/man/user_caps.5
diff options
context:
space:
mode:
Diffstat (limited to 'man/user_caps.5')
-rw-r--r--man/user_caps.5425
1 files changed, 425 insertions, 0 deletions
diff --git a/man/user_caps.5 b/man/user_caps.5
new file mode 100644
index 000000000000..b07504c3e9b2
--- /dev/null
+++ b/man/user_caps.5
@@ -0,0 +1,425 @@
+.\"***************************************************************************
+.\" Copyright (c) 2017-2019,2020 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.11 2020/01/19 02:01:39 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@TIC@\fR(1M),
+\fB@INFOCMP@\fR(1M).
+.SH AUTHORS
+.PP
+Thomas E. Dickey
+.br
+beginning with ncurses 5.0 (1999)