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