ncurses 6.1 - patch 20200118
[ncurses.git] / man / user_caps.5
1 .\"***************************************************************************
2 .\" Copyright (c) 2017-2019,2020 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.11 2020/01/19 02:01:39 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 .ie n  .in -4
47 .el    .in -2
48 ..
49 .de bP
50 .ie n  .IP \(bu 4
51 .el    .IP \(bu 2
52 ..
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 For example, ncurses can be configured with tables which match the
98 terminal databases for AIX, HP-UX or OSF/1,
99 rather than the default Solaris-like configuration.
100 .bP
101 In SVr4 curses and ncurses,
102 the terminal database is defined at compile-time using a text file
103 which lists the different terminal capabilities.
104 .IP
105 In principle, the text-file can be extended,
106 but doing this requires recompiling and reinstalling the library.
107 The text-file used in ncurses for terminal capabilities includes
108 details for various systems past the documented X/Open Curses features.
109 For example, ncurses supports these capabilities in each configuration:
110 .RS 8
111 .TP 5
112 memory_lock
113 (meml)
114 lock memory above cursor
115 .TP 5
116 memory_unlock
117 (memu)
118 unlock memory
119 .TP 5
120 box_chars_1
121 (box1)
122 box characters primary set
123 .RE
124 .IP
125 The memory lock/unlock capabilities were included because they were used
126 in the X11R6 terminal description for \fBxterm\fP.
127 The \fIbox1\fP capability is used in @TIC@ to help with terminal descriptions
128 written for AIX. 
129 .PP
130 During the 1990s, some users were reluctant to use terminfo
131 in spite of its performance advantages over termcap:
132 .bP
133 The fixed repertoire prevented users from adding features
134 for unanticipated terminal improvements
135 (or required them to reuse existing capabilities as a workaround).
136 .bP
137 The limitation to 16-bit signed integers was also mentioned.
138 Because termcap stores everything as a string,
139 it could represent larger numbers.
140 .PP
141 Although termcap's extensibility was rarely used
142 (it was never the \fIspeaker\fP who had actually used the feature),
143 the criticism had a point.
144 ncurses 5.0 provided a way to detect nonstandard capabilities,
145 determine their
146 type and optionally store and retrieve them in a way which did not interfere
147 with other applications.
148 These are referred to as \fIuser-defined capabilities\fP because no
149 modifications to the toolset's predefined capability names are needed.
150 .PP
151 The ncurses utilities \fB@TIC@\fP and \fB@INFOCMP@\fP have a command-line
152 option \*(``\-x\*('' to control whether the nonstandard capabilities
153 are stored or retrieved.
154 A library function \fBuse_extended_names\fP
155 is provided for the same purpose.
156 .PP
157 When compiling a terminal database, if \*(``\-x\*('' is set,
158 \fB@TIC@\fP will store a user-defined capability if the capability name is not
159 one of the predefined names.
160 .PP
161 Because ncurses provides a termcap library interface,
162 these user-defined capabilities may be visible to termcap applications:
163 .bP
164 The termcap interface (like all implementations of termcap)
165 requires that the capability names are 2-characters.
166 .IP
167 When the capability is simple enough for use in a termcap application,
168 it is provided as a 2-character name.
169 .bP
170 There are other
171 user-defined capabilities which refer to features not usable in termcap,
172 e.g., parameterized strings that use more than two parameters
173 or use more than the trivial expression support provided by termcap.
174 For these, the terminfo database should have only capability names with
175 3 or more characters.
176 .bP
177 Some terminals can send distinct strings for special keys (cursor-,
178 keypad- or function-keys) depending on modifier keys (shift, control, etc.).
179 While terminfo and termcap have a set of 60 predefined function-key names,
180 to which a series of keys can be assigned,
181 that is insufficient for more than a dozen keys multiplied by more than
182 a couple of modifier combinations.
183 The ncurses database uses a convention based on \fBxterm\fP to
184 provide extended special-key names.
185 .IP
186 Fitting that into termcap's limitation of 2-character names
187 would be pointless.
188 These extended keys are available only with terminfo.
189 .SS Recognized capabilities
190 .PP
191 The ncurses library uses the user-definable capabilities.
192 While the terminfo database may have other extensions,
193 ncurses makes explicit checks for these:
194 .RS 3
195 .TP 3
196 AX
197 \fIboolean\fP, asserts that the terminal interprets SGR 39 and SGR 49
198 by resetting the foreground and background color, respectively, to the default.
199 .IP
200 This is a feature recognized by the \fBscreen\fP program as well.
201 .TP 3
202 E3
203 \fIstring\fP, tells how to clear the terminal's scrollback buffer.
204 When present, the \fBclear\fP(1) program sends this before clearing
205 the terminal.
206 .IP
207 The command \*(``\fBtput clear\fP\*('' does the same thing.
208 .TP 3
209 RGB
210 \fIboolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
211 to assert that the
212 \fBset_a_foreground\fP and
213 \fBset_a_background\fP capabilities correspond to \fIdirect colors\fP,
214 using an RGB (red/green/blue) convention.
215 This capability allows the \fBcolor_content\fP function to
216 return appropriate values without requiring the application
217 to initialize colors using \fBinit_color\fP.
218 .IP
219 The capability type determines the values which ncurses sees:
220 .RS 3
221 .TP 3
222 \fIboolean\fP
223 implies that the number of bits for red, green and blue are the same.
224 Using the maximum number of colors,
225 ncurses adds two, divides that sum by three, and assigns the result
226 to red, green and blue in that order.
227 .IP
228 If the number of bits needed for the number of colors is not a multiple
229 of three, the blue (and green) components lose in comparison to red.
230 .TP 3
231 \fInumber\fP
232 tells ncurses what result to add to red, green and blue.
233 If ncurses runs out of bits,
234 blue (and green) lose just as in the \fIboolean\fP case.
235 .TP 3
236 \fIstring\fP
237 explicitly list the number of bits used for red, green and blue components
238 as a slash-separated list of decimal integers.
239 .RE
240 .IP
241 Because there are several RGB encodings in use,
242 applications which make assumptions about the number of bits per color
243 are unlikely to work reliably.
244 As a trivial case, for example, one could define \fBRGB#1\fP
245 to represent the standard eight ANSI colors, i.e., one bit per color.
246 .TP 3
247 U8
248 \fInumber\fP,
249 asserts that ncurses must use Unicode values for line-drawing characters,
250 and that it should ignore the alternate character set capabilities
251 when the locale uses UTF-8 encoding.
252 For more information, see the discussion of
253 \fBNCURSES_NO_UTF8_ACS\fP in \fBncurses\fP(3X).
254 .IP
255 Set this capability to a nonzero value to enable it.
256 .TP 3
257 XM
258 \fIstring\fP,
259 override ncurses's built-in string which
260 enables/disables \fBxterm\fP mouse mode.
261 .IP
262 ncurses sends a character sequence to the terminal to initialize mouse mode,
263 and when the user clicks the mouse buttons or (in certain modes) moves the
264 mouse, handles the characters sent back by the terminal to tell it what
265 was done with the mouse.
266 .IP
267 The mouse protocol is enabled when
268 the \fImask\fP passed in the \fBmousemask\fP function is nonzero.
269 By default, ncurses handles the responses for the X11 xterm mouse protocol.
270 It also knows about the \fISGR 1006\fP xterm mouse protocol,
271 but must to be told to look for this specifically.
272 It will not be able to guess which mode is used,
273 because the responses are enough alike that only confusion would result.
274 .IP
275 The \fBXM\fP capability has a single parameter.
276 If nonzero, the mouse protocol should be enabled.
277 If zero, the mouse protocol should be disabled.
278 ncurses inspects this capability if it is present,
279 to see whether the 1006 protocol is used.
280 If so, it expects the responses to use the \fISGR 1006\fP xterm mouse protocol.
281 .IP
282 The xterm mouse protocol is used by other terminal emulators.
283 The terminal database uses building-blocks for the various xterm mouse
284 protocols which can be used in customized terminal descriptions.
285 .IP
286 The terminal database building blocks for this mouse
287 feature also have an experimental capability \fIxm\fP.
288 The \*(``xm\*('' capability describes the mouse response.
289 Currently there is no interpreter which would use this
290 information to make the mouse support completely data-driven.
291 .IP
292 \fIxm\fP shows the format of the mouse responses.
293 In this experimental capability, the parameters are
294 .RS 5
295 .TP 5
296 .I p1
297 y-ordinate
298 .TP 5
299 .I p2
300 x-ordinate
301 .TP 5
302 .I p3
303 button
304 .TP 5
305 .I p4
306 state, e.g., pressed or released
307 .TP 5
308 .I p5
309 y-ordinate starting region
310 .TP 5
311 .I p6
312 x-ordinate starting region
313 .TP 5
314 .I p7
315 y-ordinate ending region
316 .TP 5
317 .I p8
318 x-ordinate ending region
319 .RE
320 .IP
321 Here are examples from the terminal database for the most commonly used
322 xterm mouse protocols:
323 .IP
324 .nf
325   xterm+x11mouse|X11 xterm mouse protocol,
326           kmous=\\E[M, XM=\\E[?1000%?%p1%{1}%=%th%el%;,
327           xm=\\E[M
328              %?%p4%t%p3%e%{3}%;%'\ '%+%c
329              %p2%'!'%+%c
330              %p1%'!'%+%c,
331
332   xterm+sm+1006|xterm SGR-mouse,
333           kmous=\\E[<, XM=\\E[?1006;1000%?%p1%{1}%=%th%el%;,
334           xm=\\E[<%i%p3%d;
335              %p1%d;
336              %p2%d;
337              %?%p4%tM%em%;,
338 .fi
339 .
340 .SS Extended key-definitions
341 .PP
342 Several terminals provide the ability to send distinct strings for
343 combinations of modified special keys.
344 There is no standard for what those keys can send.
345 .PP
346 Since 1999, \fBxterm\fP has supported
347 \fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce
348 distinct special-key strings.
349 In a terminal description, ncurses has no special knowledge of the
350 modifiers used.
351 Applications can use the \fInaming convention\fP established for \fBxterm\fP
352 to find these special keys in the terminal description.
353 .PP
354 Starting with the curses convention that \fIkey names\fP begin with \*(``k\*(''
355 and that shifted special keys are an uppercase name,
356 ncurses' terminal database defines these names to which a suffix is added:
357 .RS 5
358 .TS
359 tab(/) ;
360 l l .
361 \fIName\fR/\fIDescription\fR
362 _
363 kDC/special form of kdch1 (delete character)
364 kDN/special form of kcud1 (cursor down)
365 kEND/special form of kend (End)
366 kHOM/special form of khome (Home)
367 kLFT/special form of kcub1 (cursor-left or cursor-back)
368 kNXT/special form of knext (Next, or Page-Down)
369 kPRV/special form of kprev (Prev, or Page-Up)
370 kRIT/special form of kcuf1 (cursor-right, or cursor-forward)
371 kUP/special form of kcuu1 (cursor-up)
372 .TE
373 .RE
374 .PP
375 These are the suffixes used to denote the modifiers:
376 .RS 5
377 .TS
378 tab(/) ;
379 l l .
380 \fIValue\fR/\fIDescription\fR
381 _
382 2/Shift
383 3/Alt
384 4/Shift + Alt
385 5/Control
386 6/Shift + Control
387 7/Alt + Control
388 8/Shift + Alt + Control
389 9/Meta
390 10/Meta + Shift
391 11/Meta + Alt
392 12/Meta + Alt + Shift
393 13/Meta + Ctrl
394 14/Meta + Ctrl + Shift
395 15/Meta + Ctrl + Alt
396 16/Meta + Ctrl + Alt + Shift
397 .TE
398 .RE
399 .PP
400 None of these are predefined; terminal descriptions can refer to \fInames\fP
401 which ncurses will allocate at runtime to \fIkey-codes\fP.
402 To use these keys in an ncurses program, an application could do this:
403 .bP
404 using a list of extended key \fInames\fP,
405 ask \fBtigetstr\fP(3X) for their values, and
406 .bP
407 given the list of values,
408 ask \fBkey_defined\fP(3X) for the \fIkey-code\fP which
409 would be returned for those keys by \fBwgetch\fP(3X).
410 .PP
411 .SH PORTABILITY
412 .PP
413 The \*(``\-x\*('' extension feature of \fB@TIC@\fP and \fB@INFOCMP@\fP
414 has been adopted in NetBSD curses.
415 That implementation stores user-defined capabilities,
416 but makes no use of these capabilities itself.
417 .SH SEE ALSO
418 .PP
419 \fB@TIC@\fR(1M),
420 \fB@INFOCMP@\fR(1M).
421 .SH AUTHORS
422 .PP
423 Thomas E. Dickey
424 .br
425 beginning with ncurses 5.0 (1999)