ncurses 6.0 - patch 20171118
[ncurses.git] / man / user_caps.5
1 .\"***************************************************************************
2 .\" Copyright (c) 2017 Free Software Foundation, Inc.                        *
3 .\"                                                                          *
4 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
5 .\" copy of this software and associated documentation files (the            *
6 .\" "Software"), to deal in the Software without restriction, including      *
7 .\" without limitation the rights to use, copy, modify, merge, publish,      *
8 .\" distribute, distribute with modifications, sublicense, and/or sell       *
9 .\" copies of the Software, and to permit persons to whom the Software is    *
10 .\" furnished to do so, subject to the following conditions:                 *
11 .\"                                                                          *
12 .\" The above copyright notice and this permission notice shall be included  *
13 .\" in all copies or substantial portions of the Software.                   *
14 .\"                                                                          *
15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
16 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
18 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
19 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
20 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
21 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
22 .\"                                                                          *
23 .\" Except as contained in this notice, the name(s) of the above copyright   *
24 .\" holders shall not be used in advertising or otherwise to promote the     *
25 .\" sale, use or other dealings in this Software without prior written       *
26 .\" authorization.                                                           *
27 .\"***************************************************************************
28 .\"
29 .\" $Id: user_caps.5,v 1.3 2017/11/18 23:51:59 tom Exp $
30 .TH user_caps 5
31 .ie \n(.g .ds `` \(lq
32 .el       .ds `` ``
33 .ie \n(.g .ds '' \(rq
34 .el       .ds '' ''
35 .de NS
36 .ie n  .sp
37 .el    .sp .5
38 .ie n  .in +4
39 .el    .in +2
40 .nf
41 .ft C                   \" Courier
42 ..
43 .de NE
44 .fi
45 .ft R
46 .in -4
47 ..
48 .de bP
49 .ie n  .IP \(bu 4
50 .el    .IP \(bu 2
51 ..
52 .ds n 5
53 .SH NAME
54 user_caps \- user-defined terminfo capabilities
55 .SH SYNOPSIS
56 .B tic -x, infocmp -x
57 .SH DESCRIPTION
58 .SS Background
59 .PP
60 Before ncurses 5.0,
61 terminfo databases used a \fIfixed repertoire\fP of terminal
62 capabilities designed for the SVr2 terminal database in 1984,
63 and extended in stages through SVr4 (1989),
64 and standardized in the Single Unix Specification beginning in 1995.
65 .PP
66 Most of the \fIextensions\fP in this fixed repertoire were additions
67 to the tables of boolean, numeric and string capabilities.
68 Rather than change the meaning of an existing capability, a new name was added.
69 The terminfo database uses a binary format; binary compatibility was
70 ensured by using a header which gave the number of items in the
71 tables for each type of capability.
72 The standardization was incomplete:
73 .bP
74 The \fIbinary format\fP itself is not described
75 in the X/Open Curses documentation.
76 Only the \fIsource format\fP is described.
77 .IP
78 Library developers rely upon the SVr4 documentation,
79 and reverse-engineering the compiled terminfo files to match the binary format.
80 .bP
81 Lacking a standard for the binary format, most implementations
82 copy the SVr2 binary format, which uses 16-bit signed integers,
83 and is limited to 4096-byte entries.
84 .IP
85 The format cannot represent very large numeric capabilities,
86 nor can it represent large numbers of special keyboard definitions.
87 .bP
88 The tables of capability names differ between implementations.
89 .IP
90 Although they \fImay\fP provide all of the standard capability names,
91 the position in the tables differs because some features were added as needed,
92 while others were added (out of order) to comply with X/Open Curses.
93 .IP
94 While ncurses' repertoire of predefined capabilities is closest to Solaris,
95 Solaris's terminfo database has a few differences from
96 the list published by X/Open Curses.
97 .PP
98 During the 1990s, some users were reluctant to use terminfo
99 in spite of its performance advantages over termcap:
100 .bP
101 The fixed repertoire prevented users from adding features
102 for unanticipated terminal improvements
103 (or required them to reuse existing capabilities as a workaround).
104 .bP
105 The limitation to 16-bit signed integers was also mentioned.
106 Because termcap stores everything as a string,
107 it could represent larger numbers.
108 .PP
109 Although termcap's extensibility was rarely used
110 (it was never the \fIspeaker\fP who had actually used the feature),
111 the criticism had a point.
112 ncurses 5.0 provided a way to detect nonstandard capabilities,
113 determine their
114 type and optionally store and retrieve them in a way which did not interfere
115 with other applications.
116 These are referred to as \fIuser-defined capabilities\fP because no
117 modifications to the toolset's predefined capability names are needed.
118 .PP
119 The ncurses utilities \fBtic\fP and \fBinfocmp\fP have a command-line
120 option \*(``\-x\*('' to control whether the nonstandard capabilities
121 are stored or retrieved.  A library function \fBuse_extended_names\fP
122 is provided for the same purpose.
123 .PP
124 When compiling a terminal database, if \*(``\-x\*('' is set,
125 \fBtic\fP will store a user-defined capability if the capability name is not
126 one of the predefined names.
127 .PP
128 Because ncurses provides a termcap library interface,
129 these user-defined capabilities may be visible to termcap applications:
130 .bP
131 The termcap interface (like all implementations of termcap)
132 requires that the capability names are 2-characters.
133 .IP
134 When the capability is simple enough for use in a termcap application,
135 it is provided as a 2-character name.
136 .bP
137 There are other
138 user-defined capabilities which refer to features not usable in termcap,
139 e.g., parameterized strings that use more than two parameters
140 or use more than the trivial expression support provided by termcap.
141 For these, the terminfo database should have only capability names with
142 3 or more characters.
143 .bP
144 Some terminals can send distinct strings for special keys (cursor-,
145 keypad- or function-keys) depending on modifier keys (shift, control, etc.).
146 While terminfo and termcap have a set of 60 predefined function-key names,
147 to which a series of keys can be assigned,
148 that is insufficient for more than a dozen keys multiplied by more than
149 a couple of modifier combinations.
150 The ncurses database uses a convention based on \fBxterm\fP to
151 provide extended special-key names.
152 .IP
153 Fitting that into termcap's limitation of 2-character names
154 would be pointless.
155 These extended keys are available only with terminfo.
156 .SS Recognized capabilities
157 .PP
158 The ncurses library uses the user-definable capabilities.
159 While the terminfo database may have other extensions,
160 ncurses makes explicit checks for these:
161 .RS 3
162 .TP 3
163 AX
164 \fIboolean\fP, asserts that the terminal interprets SGR 39 and SGR 49
165 by resetting the foreground and background color, respectively, to the default. 
166 .IP
167 This is a feature recognized by the \fBscreen\fP program as well.
168 .TP 3
169 E3
170 \fIstring\fP, tells how to clear the terminal's scrollback buffer.
171 When present, the \fBclear\fP(1) program sends this before clearing
172 the terminal.
173 .IP
174 The command \*(``\fBtput clear\fP\*('' does the same thing.
175 .TP 3
176 RGB
177 \fIboolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
178 to assert that the
179 \fBset_a_foreground\fP and 
180 \fBset_a_background\fP capabilities correspond to \fIdirect colors\fP,
181 using an RGB (red/green/blue) convention. 
182 This capability allows the \fBcolor_content\fP function to
183 return appropriate values without requiring the application
184 to initialize colors using \fBinit_color\fP.
185 .IP
186 The capability type determines the values which ncurses sees:
187 .RS 3
188 .TP 3
189 \fIboolean\fP
190 implies that the number of bits for red, green and blue are the same.
191 Using the maximum number of colors,
192 ncurses adds two, divides that sum by three, and assigns the result
193 to red, green and blue in that order.
194 .IP
195 If the number of bits needed for the number of colors is not a multiple
196 of three, the blue (and green) components lose in comparison to red.
197 .TP 3
198 \fInumber\fP
199 tells ncurses what result to add to red, green and blue.
200 If ncurses runs out of bits,
201 blue (and green) lose just as in the \fIboolean\fP case.
202 .TP 3
203 \fIstring\fP
204 explicitly list the number of bits used for red, green and blue components
205 as a slash-separated list of decimal integers.
206 .RE
207 .TP 3
208 U8
209 \fIboolean\fP,
210 asserts that ncurses must use Unicode values for line-drawing characters,
211 and that it should ignore the alternate character set capabilities
212 when the locale uses UTF-8 encoding.
213 For more information, see the discussion of
214 \fBNCURSES_NO_UTF8_ACS\fP in \fBncurses\fP(3X).
215 .IP
216 Set this capability to a nonzero value to enable it.
217 .TP 3
218 XM
219 \fIstring\fP,
220 override ncurses's built-in string which
221 enables/disables \fBxterm\fP mouse mode.
222 .
223 .SS Extended key-definitions
224 .PP
225 Several terminals provide the ability to send distinct strings for
226 combinations of modified special keys.
227 There is no standard for what those keys can send.
228 .PP
229 Since 1999, \fBxterm\fP has supported
230 \fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce
231 distinct special-key strings.
232 In a terminal description, ncurses has no special knowledge of the
233 modifiers used.
234 Applications can use the \fInaming convention\fP established for \fBxterm\fP
235 to find these special keys in the terminal description.
236 .PP
237 Starting with the curses convention that \fIkey names\fP begin with \*(``k\*(''
238 and that shifted special keys are an uppercase name,
239 ncurses' terminal database defines these names to which a suffix is added:
240 .RS 5
241 .TS
242 tab(/) ;
243 l l .
244 \fIName\fR/\fIDescription\fR
245 _
246 kDC/special form of kdch1 (delete character)
247 kDN/special form of kcud1 (cursor down)
248 kEND/special form of kend (End)
249 kHOM/special form of khome (Home)
250 kLFT/special form of kcub1 (cursor-left or cursor-back)
251 kNXT/special form of knext (Next, or Page-Down)
252 kPRV/special form of kprev (Prev, or Page-Up) 
253 kRIT/special form of kcuf1 (cursor-right, or cursor-forward)
254 kUP/special form of kcuu1 (cursor-up)
255 .TE
256 .RE
257 .PP
258 These are the suffixes used to denote the modifiers:
259 .RS 5
260 .TS
261 tab(/) ;
262 l l .
263 \fIValue\fR/\fIDescription\fR
264 _
265 2/Shift
266 3/Alt
267 4/Shift + Alt
268 5/Control
269 6/Shift + Control
270 7/Alt + Control
271 8/Shift + Alt + Control
272 9/Meta
273 10/Meta + Shift
274 11/Meta + Alt
275 12/Meta + Alt + Shift
276 13/Meta + Ctrl
277 14/Meta + Ctrl + Shift
278 15/Meta + Ctrl + Alt
279 16/Meta + Ctrl + Alt + Shift
280 .TE
281 .RE
282 .PP
283 None of these are predefined; terminal descriptions can refer to \fInames\fP
284 which ncurses will allocate at runtime to \fIkey-codes\fP.
285 To use these keys in an ncurses program, an application could do this:
286 .bP
287 using a list of extended key \fInames\fP,
288 ask \fBtigetstr\fP(3X) for their values, and
289 .bP
290 given the list of values,
291 ask \fBkey_defined\fP(3X) for the \fIkey-code\fP which
292 would be returned for those keys by \fBwgetch\fP(3X).
293 .PP
294 .SH PORTABILITY
295 .PP
296 The \*(``\-x\*('' extension feature of \fBtic\fP and \fBinfocmp\fP
297 has been adopted in NetBSD curses.
298 That implementation stores user-defined capabilities,
299 but makes no use of these capabilities itself.
300 .SH SEE ALSO
301 .PP
302 \fBtic\fR(1),
303 \fBinfocmp\fR(1).
304 .SH AUTHORS
305 .PP
306 Thomas E. Dickey
307 .br
308 beginning with ncurses 5.0 (1999)