ncurses 6.2 - patch 20200212
[ncurses.git] / man / user_caps.5
1 .\"***************************************************************************
2 .\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
3 .\" Copyright 2017 Free Software Foundation, Inc.                            *
4 .\"                                                                          *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
6 .\" copy of this software and associated documentation files (the            *
7 .\" "Software"), to deal in the Software without restriction, including      *
8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
10 .\" copies of the Software, and to permit persons to whom the Software is    *
11 .\" furnished to do so, subject to the following conditions:                 *
12 .\"                                                                          *
13 .\" The above copyright notice and this permission notice shall be included  *
14 .\" in all copies or substantial portions of the Software.                   *
15 .\"                                                                          *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
23 .\"                                                                          *
24 .\" Except as contained in this notice, the name(s) of the above copyright   *
25 .\" holders shall not be used in advertising or otherwise to promote the     *
26 .\" sale, use or other dealings in this Software without prior written       *
27 .\" authorization.                                                           *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: user_caps.5,v 1.12 2020/02/02 23:34:34 tom Exp $
31 .TH user_caps 5
32 .ie \n(.g .ds `` \(lq
33 .el       .ds `` ``
34 .ie \n(.g .ds '' \(rq
35 .el       .ds '' ''
36 .de NS
37 .ie n  .sp
38 .el    .sp .5
39 .ie n  .in +4
40 .el    .in +2
41 .nf
42 .ft C                   \" Courier
43 ..
44 .de NE
45 .fi
46 .ft R
47 .ie n  .in -4
48 .el    .in -2
49 ..
50 .de bP
51 .ie n  .IP \(bu 4
52 .el    .IP \(bu 2
53 ..
54 .SH NAME
55 user_caps \- user-defined terminfo capabilities
56 .SH SYNOPSIS
57 .B @TIC@ -x, @INFOCMP@ -x
58 .SH DESCRIPTION
59 .SS Background
60 .PP
61 Before ncurses 5.0,
62 terminfo databases used a \fIfixed repertoire\fP of terminal
63 capabilities designed for the SVr2 terminal database in 1984,
64 and extended in stages through SVr4 (1989),
65 and standardized in the Single Unix Specification beginning in 1995.
66 .PP
67 Most of the \fIextensions\fP in this fixed repertoire were additions
68 to the tables of boolean, numeric and string capabilities.
69 Rather than change the meaning of an existing capability, a new name was added.
70 The terminfo database uses a binary format; binary compatibility was
71 ensured by using a header which gave the number of items in the
72 tables for each type of capability.
73 The standardization was incomplete:
74 .bP
75 The \fIbinary format\fP itself is not described
76 in the X/Open Curses documentation.
77 Only the \fIsource format\fP is described.
78 .IP
79 Library developers rely upon the SVr4 documentation,
80 and reverse-engineering the compiled terminfo files to match the binary format.
81 .bP
82 Lacking a standard for the binary format, most implementations
83 copy the SVr2 binary format, which uses 16-bit signed integers,
84 and is limited to 4096-byte entries.
85 .IP
86 The format cannot represent very large numeric capabilities,
87 nor can it represent large numbers of special keyboard definitions.
88 .bP
89 The tables of capability names differ between implementations.
90 .IP
91 Although they \fImay\fP provide all of the standard capability names,
92 the position in the tables differs because some features were added as needed,
93 while others were added (out of order) to comply with X/Open Curses.
94 .IP
95 While ncurses' repertoire of predefined capabilities is closest to Solaris,
96 Solaris's terminfo database has a few differences from
97 the list published by X/Open Curses.
98 For example, ncurses can be configured with tables which match the
99 terminal databases for AIX, HP-UX or OSF/1,
100 rather than the default Solaris-like configuration.
101 .bP
102 In SVr4 curses and ncurses,
103 the terminal database is defined at compile-time using a text file
104 which lists the different terminal capabilities.
105 .IP
106 In principle, the text-file can be extended,
107 but doing this requires recompiling and reinstalling the library.
108 The text-file used in ncurses for terminal capabilities includes
109 details for various systems past the documented X/Open Curses features.
110 For example, ncurses supports these capabilities in each configuration:
111 .RS 8
112 .TP 5
113 memory_lock
114 (meml)
115 lock memory above cursor
116 .TP 5
117 memory_unlock
118 (memu)
119 unlock memory
120 .TP 5
121 box_chars_1
122 (box1)
123 box characters primary set
124 .RE
125 .IP
126 The memory lock/unlock capabilities were included because they were used
127 in the X11R6 terminal description for \fBxterm\fP.
128 The \fIbox1\fP capability is used in @TIC@ to help with terminal descriptions
129 written for AIX. 
130 .PP
131 During the 1990s, some users were reluctant to use terminfo
132 in spite of its performance advantages over termcap:
133 .bP
134 The fixed repertoire prevented users from adding features
135 for unanticipated terminal improvements
136 (or required them to reuse existing capabilities as a workaround).
137 .bP
138 The limitation to 16-bit signed integers was also mentioned.
139 Because termcap stores everything as a string,
140 it could represent larger numbers.
141 .PP
142 Although termcap's extensibility was rarely used
143 (it was never the \fIspeaker\fP who had actually used the feature),
144 the criticism had a point.
145 ncurses 5.0 provided a way to detect nonstandard capabilities,
146 determine their
147 type and optionally store and retrieve them in a way which did not interfere
148 with other applications.
149 These are referred to as \fIuser-defined capabilities\fP because no
150 modifications to the toolset's predefined capability names are needed.
151 .PP
152 The ncurses utilities \fB@TIC@\fP and \fB@INFOCMP@\fP have a command-line
153 option \*(``\-x\*('' to control whether the nonstandard capabilities
154 are stored or retrieved.
155 A library function \fBuse_extended_names\fP
156 is provided for the same purpose.
157 .PP
158 When compiling a terminal database, if \*(``\-x\*('' is set,
159 \fB@TIC@\fP will store a user-defined capability if the capability name is not
160 one of the predefined names.
161 .PP
162 Because ncurses provides a termcap library interface,
163 these user-defined capabilities may be visible to termcap applications:
164 .bP
165 The termcap interface (like all implementations of termcap)
166 requires that the capability names are 2-characters.
167 .IP
168 When the capability is simple enough for use in a termcap application,
169 it is provided as a 2-character name.
170 .bP
171 There are other
172 user-defined capabilities which refer to features not usable in termcap,
173 e.g., parameterized strings that use more than two parameters
174 or use more than the trivial expression support provided by termcap.
175 For these, the terminfo database should have only capability names with
176 3 or more characters.
177 .bP
178 Some terminals can send distinct strings for special keys (cursor-,
179 keypad- or function-keys) depending on modifier keys (shift, control, etc.).
180 While terminfo and termcap have a set of 60 predefined function-key names,
181 to which a series of keys can be assigned,
182 that is insufficient for more than a dozen keys multiplied by more than
183 a couple of modifier combinations.
184 The ncurses database uses a convention based on \fBxterm\fP to
185 provide extended special-key names.
186 .IP
187 Fitting that into termcap's limitation of 2-character names
188 would be pointless.
189 These extended keys are available only with terminfo.
190 .SS Recognized capabilities
191 .PP
192 The ncurses library uses the user-definable capabilities.
193 While the terminfo database may have other extensions,
194 ncurses makes explicit checks for these:
195 .RS 3
196 .TP 3
197 AX
198 \fIboolean\fP, asserts that the terminal interprets SGR 39 and SGR 49
199 by resetting the foreground and background color, respectively, to the default.
200 .IP
201 This is a feature recognized by the \fBscreen\fP program as well.
202 .TP 3
203 E3
204 \fIstring\fP, tells how to clear the terminal's scrollback buffer.
205 When present, the \fBclear\fP(1) program sends this before clearing
206 the terminal.
207 .IP
208 The command \*(``\fBtput clear\fP\*('' does the same thing.
209 .TP 3
210 RGB
211 \fIboolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
212 to assert that the
213 \fBset_a_foreground\fP and
214 \fBset_a_background\fP capabilities correspond to \fIdirect colors\fP,
215 using an RGB (red/green/blue) convention.
216 This capability allows the \fBcolor_content\fP function to
217 return appropriate values without requiring the application
218 to initialize colors using \fBinit_color\fP.
219 .IP
220 The capability type determines the values which ncurses sees:
221 .RS 3
222 .TP 3
223 \fIboolean\fP
224 implies that the number of bits for red, green and blue are the same.
225 Using the maximum number of colors,
226 ncurses adds two, divides that sum by three, and assigns the result
227 to red, green and blue in that order.
228 .IP
229 If the number of bits needed for the number of colors is not a multiple
230 of three, the blue (and green) components lose in comparison to red.
231 .TP 3
232 \fInumber\fP
233 tells ncurses what result to add to red, green and blue.
234 If ncurses runs out of bits,
235 blue (and green) lose just as in the \fIboolean\fP case.
236 .TP 3
237 \fIstring\fP
238 explicitly list the number of bits used for red, green and blue components
239 as a slash-separated list of decimal integers.
240 .RE
241 .IP
242 Because there are several RGB encodings in use,
243 applications which make assumptions about the number of bits per color
244 are unlikely to work reliably.
245 As a trivial case, for example, one could define \fBRGB#1\fP
246 to represent the standard eight ANSI colors, i.e., one bit per color.
247 .TP 3
248 U8
249 \fInumber\fP,
250 asserts that ncurses must use Unicode values for line-drawing characters,
251 and that it should ignore the alternate character set capabilities
252 when the locale uses UTF-8 encoding.
253 For more information, see the discussion of
254 \fBNCURSES_NO_UTF8_ACS\fP in \fBncurses\fP(3X).
255 .IP
256 Set this capability to a nonzero value to enable it.
257 .TP 3
258 XM
259 \fIstring\fP,
260 override ncurses's built-in string which
261 enables/disables \fBxterm\fP mouse mode.
262 .IP
263 ncurses sends a character sequence to the terminal to initialize mouse mode,
264 and when the user clicks the mouse buttons or (in certain modes) moves the
265 mouse, handles the characters sent back by the terminal to tell it what
266 was done with the mouse.
267 .IP
268 The mouse protocol is enabled when
269 the \fImask\fP passed in the \fBmousemask\fP function is nonzero.
270 By default, ncurses handles the responses for the X11 xterm mouse protocol.
271 It also knows about the \fISGR 1006\fP xterm mouse protocol,
272 but must to be told to look for this specifically.
273 It will not be able to guess which mode is used,
274 because the responses are enough alike that only confusion would result.
275 .IP
276 The \fBXM\fP capability has a single parameter.
277 If nonzero, the mouse protocol should be enabled.
278 If zero, the mouse protocol should be disabled.
279 ncurses inspects this capability if it is present,
280 to see whether the 1006 protocol is used.
281 If so, it expects the responses to use the \fISGR 1006\fP xterm mouse protocol.
282 .IP
283 The xterm mouse protocol is used by other terminal emulators.
284 The terminal database uses building-blocks for the various xterm mouse
285 protocols which can be used in customized terminal descriptions.
286 .IP
287 The terminal database building blocks for this mouse
288 feature also have an experimental capability \fIxm\fP.
289 The \*(``xm\*('' capability describes the mouse response.
290 Currently there is no interpreter which would use this
291 information to make the mouse support completely data-driven.
292 .IP
293 \fIxm\fP shows the format of the mouse responses.
294 In this experimental capability, the parameters are
295 .RS 5
296 .TP 5
297 .I p1
298 y-ordinate
299 .TP 5
300 .I p2
301 x-ordinate
302 .TP 5
303 .I p3
304 button
305 .TP 5
306 .I p4
307 state, e.g., pressed or released
308 .TP 5
309 .I p5
310 y-ordinate starting region
311 .TP 5
312 .I p6
313 x-ordinate starting region
314 .TP 5
315 .I p7
316 y-ordinate ending region
317 .TP 5
318 .I p8
319 x-ordinate ending region
320 .RE
321 .IP
322 Here are examples from the terminal database for the most commonly used
323 xterm mouse protocols:
324 .IP
325 .nf
326   xterm+x11mouse|X11 xterm mouse protocol,
327           kmous=\\E[M, XM=\\E[?1000%?%p1%{1}%=%th%el%;,
328           xm=\\E[M
329              %?%p4%t%p3%e%{3}%;%'\ '%+%c
330              %p2%'!'%+%c
331              %p1%'!'%+%c,
332
333   xterm+sm+1006|xterm SGR-mouse,
334           kmous=\\E[<, XM=\\E[?1006;1000%?%p1%{1}%=%th%el%;,
335           xm=\\E[<%i%p3%d;
336              %p1%d;
337              %p2%d;
338              %?%p4%tM%em%;,
339 .fi
340 .
341 .SS Extended key-definitions
342 .PP
343 Several terminals provide the ability to send distinct strings for
344 combinations of modified special keys.
345 There is no standard for what those keys can send.
346 .PP
347 Since 1999, \fBxterm\fP has supported
348 \fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce
349 distinct special-key strings.
350 In a terminal description, ncurses has no special knowledge of the
351 modifiers used.
352 Applications can use the \fInaming convention\fP established for \fBxterm\fP
353 to find these special keys in the terminal description.
354 .PP
355 Starting with the curses convention that \fIkey names\fP begin with \*(``k\*(''
356 and that shifted special keys are an uppercase name,
357 ncurses' terminal database defines these names to which a suffix is added:
358 .RS 5
359 .TS
360 tab(/) ;
361 l l .
362 \fIName\fR/\fIDescription\fR
363 _
364 kDC/special form of kdch1 (delete character)
365 kDN/special form of kcud1 (cursor down)
366 kEND/special form of kend (End)
367 kHOM/special form of khome (Home)
368 kLFT/special form of kcub1 (cursor-left or cursor-back)
369 kNXT/special form of knext (Next, or Page-Down)
370 kPRV/special form of kprev (Prev, or Page-Up)
371 kRIT/special form of kcuf1 (cursor-right, or cursor-forward)
372 kUP/special form of kcuu1 (cursor-up)
373 .TE
374 .RE
375 .PP
376 These are the suffixes used to denote the modifiers:
377 .RS 5
378 .TS
379 tab(/) ;
380 l l .
381 \fIValue\fR/\fIDescription\fR
382 _
383 2/Shift
384 3/Alt
385 4/Shift + Alt
386 5/Control
387 6/Shift + Control
388 7/Alt + Control
389 8/Shift + Alt + Control
390 9/Meta
391 10/Meta + Shift
392 11/Meta + Alt
393 12/Meta + Alt + Shift
394 13/Meta + Ctrl
395 14/Meta + Ctrl + Shift
396 15/Meta + Ctrl + Alt
397 16/Meta + Ctrl + Alt + Shift
398 .TE
399 .RE
400 .PP
401 None of these are predefined; terminal descriptions can refer to \fInames\fP
402 which ncurses will allocate at runtime to \fIkey-codes\fP.
403 To use these keys in an ncurses program, an application could do this:
404 .bP
405 using a list of extended key \fInames\fP,
406 ask \fBtigetstr\fP(3X) for their values, and
407 .bP
408 given the list of values,
409 ask \fBkey_defined\fP(3X) for the \fIkey-code\fP which
410 would be returned for those keys by \fBwgetch\fP(3X).
411 .PP
412 .SH PORTABILITY
413 .PP
414 The \*(``\-x\*('' extension feature of \fB@TIC@\fP and \fB@INFOCMP@\fP
415 has been adopted in NetBSD curses.
416 That implementation stores user-defined capabilities,
417 but makes no use of these capabilities itself.
418 .SH SEE ALSO
419 .PP
420 \fB@TIC@\fR(1M),
421 \fB@INFOCMP@\fR(1M).
422 .SH AUTHORS
423 .PP
424 Thomas E. Dickey
425 .br
426 beginning with ncurses 5.0 (1999)