diff options
Diffstat (limited to 'man/user_caps.5')
| -rw-r--r-- | man/user_caps.5 | 426 |
1 files changed, 426 insertions, 0 deletions
diff --git a/man/user_caps.5 b/man/user_caps.5 new file mode 100644 index 0000000..31f4f72 --- /dev/null +++ b/man/user_caps.5 @@ -0,0 +1,426 @@ +.\"*************************************************************************** +.\" 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.12 2020/02/02 23:34:34 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) |