--- /dev/null
+.\"***************************************************************************
+.\" Copyright (c) 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.1 2017/08/12 21:26:12 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
+.in -4
+..
+.de bP
+.IP \(bu 4
+..
+.ds n 5
+.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.
+.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 \fBtic\fP and \fBinfocmp\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,
+\fBtic\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
+.TP 3
+U8
+\fIboolean\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 \fBterminfo\fP(5).
+.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.
+.
+.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 \fBtic\fP and \fBinfocmp\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
+\fBtic\fR(1),
+\fBinfocmp\fR(1).
+.SH AUTHORS
+.PP
+Thomas E. Dickey
+.br
+beginning with ncurses 5.0 (1999)
projects / ncurses.git / blobdiff