diff options
Diffstat (limited to 'doc/html/man/user_caps.5.html')
| -rw-r--r-- | doc/html/man/user_caps.5.html | 401 |
1 files changed, 401 insertions, 0 deletions
diff --git a/doc/html/man/user_caps.5.html b/doc/html/man/user_caps.5.html new file mode 100644 index 0000000..95bb74d --- /dev/null +++ b/doc/html/man/user_caps.5.html @@ -0,0 +1,401 @@ +<!-- + **************************************************************************** + * 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 @ +--> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<HTML> +<HEAD> +<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> +<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> +<TITLE>user_caps 5</TITLE> +<link rel="author" href="mailto:bug-ncurses@gnu.org"> +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> +</HEAD> +<BODY> +<H1 class="no-header">user_caps 5</H1> +<PRE> +<STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> File Formats Manual <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> + + + + +</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> + user_caps - user-defined terminfo capabilities + + +</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> + <STRONG>tic</STRONG> <STRONG>-x,</STRONG> <STRONG>infocmp</STRONG> <STRONG>-x</STRONG> + + +</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> + +</PRE><H3><a name="h3-Background">Background</a></H3><PRE> + Before ncurses 5.0, terminfo databases used a <EM>fixed</EM> <EM>repertoire</EM> of ter- + minal 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. + + Most of the <EM>extensions</EM> 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 ter- + minfo 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: + + <STRONG>o</STRONG> The <EM>binary</EM> <EM>format</EM> itself is not described in the X/Open Curses doc- + umentation. Only the <EM>source</EM> <EM>format</EM> is described. + + Library developers rely upon the SVr4 documentation, and reverse- + engineering the compiled terminfo files to match the binary format. + + <STRONG>o</STRONG> 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. + + The format cannot represent very large numeric capabilities, nor + can it represent large numbers of special keyboard definitions. + + <STRONG>o</STRONG> The tables of capability names differ between implementations. + + Although they <EM>may</EM> 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. + + 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 con- + figured with tables which match the terminal databases for AIX, HP- + UX or OSF/1, rather than the default Solaris-like configuration. + + <STRONG>o</STRONG> In SVr4 curses and ncurses, the terminal database is defined at + compile-time using a text file which lists the different terminal + capabilities. + + 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 var- + ious systems past the documented X/Open Curses features. For exam- + ple, ncurses supports these capabilities in each configuration: + + memory_lock + (meml) lock memory above cursor + + memory_unlock + (memu) unlock memory + + box_chars_1 + (box1) box characters primary set + + The memory lock/unlock capabilities were included because they were + used in the X11R6 terminal description for <STRONG>xterm</STRONG>. The <EM>box1</EM> capa- + bility is used in tic to help with terminal descriptions written + for AIX. + + During the 1990s, some users were reluctant to use terminfo in spite of + its performance advantages over termcap: + + <STRONG>o</STRONG> The fixed repertoire prevented users from adding features for unan- + ticipated terminal improvements (or required them to reuse existing + capabilities as a workaround). + + <STRONG>o</STRONG> The limitation to 16-bit signed integers was also mentioned. + Because termcap stores everything as a string, it could represent + larger numbers. + + Although termcap's extensibility was rarely used (it was never the + <EM>speaker</EM> who had actually used the feature), the criticism had a point. + ncurses 5.0 provided a way to detect nonstandard capabilities, deter- + mine their type and optionally store and retrieve them in a way which + did not interfere with other applications. These are referred to as + <EM>user-defined</EM> <EM>capabilities</EM> because no modifications to the toolset's + predefined capability names are needed. + + The ncurses utilities <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> have a command-line option "-x" + to control whether the nonstandard capabilities are stored or + retrieved. A library function <STRONG>use_extended_names</STRONG> is provided for the + same purpose. + + When compiling a terminal database, if "-x" is set, <STRONG>tic</STRONG> will store a + user-defined capability if the capability name is not one of the prede- + fined names. + + Because ncurses provides a termcap library interface, these user- + defined capabilities may be visible to termcap applications: + + <STRONG>o</STRONG> The termcap interface (like all implementations of termcap) + requires that the capability names are 2-characters. + + When the capability is simple enough for use in a termcap applica- + tion, it is provided as a 2-character name. + + <STRONG>o</STRONG> 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. + + <STRONG>o</STRONG> Some terminals can send distinct strings for special keys (cursor-, + keypad- or function-keys) depending on modifier keys (shift, con- + trol, etc.). While terminfo and termcap have a set of 60 prede- + fined function-key names, to which a series of keys can be + assigned, that is insufficient for more than a dozen keys multi- + plied by more than a couple of modifier combinations. The ncurses + database uses a convention based on <STRONG>xterm</STRONG> to provide extended spe- + cial-key names. + + Fitting that into termcap's limitation of 2-character names would + be pointless. These extended keys are available only with ter- + minfo. + + +</PRE><H3><a name="h3-Recognized-capabilities">Recognized capabilities</a></H3><PRE> + The ncurses library uses the user-definable capabilities. While the + terminfo database may have other extensions, ncurses makes explicit + checks for these: + + AX <EM>boolean</EM>, asserts that the terminal interprets SGR 39 and SGR 49 + by resetting the foreground and background color, respectively, + to the default. + + This is a feature recognized by the <STRONG>screen</STRONG> program as well. + + E3 <EM>string</EM>, tells how to clear the terminal's scrollback buffer. + When present, the <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG> program sends this before clearing the + terminal. + + The command "<STRONG>tput</STRONG> <STRONG>clear</STRONG>" does the same thing. + + RGB + <EM>boolean</EM>, <EM>number</EM> <STRONG>or</STRONG> <EM>string</EM>, to assert that the <STRONG>set_a_foreground</STRONG> + and <STRONG>set_a_background</STRONG> capabilities correspond to <EM>direct</EM> <EM>colors</EM>, + using an RGB (red/green/blue) convention. This capability allows + the <STRONG>color_content</STRONG> function to return appropriate values without + requiring the application to initialize colors using <STRONG>init_color</STRONG>. + + The capability type determines the values which ncurses sees: + + <EM>boolean</EM> + 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. + + 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. + + <EM>number</EM> + 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 + <EM>boolean</EM> case. + + <EM>string</EM> + explicitly list the number of bits used for red, green and + blue components as a slash-separated list of decimal integers. + + 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 <STRONG>RGB#1</STRONG> to represent the standard eight ANSI colors, + i.e., one bit per color. + + U8 <EM>number</EM>, asserts that ncurses must use Unicode values for line- + drawing characters, and that it should ignore the alternate char- + acter set capabilities when the locale uses UTF-8 encoding. For + more information, see the discussion of <STRONG>NCURSES_NO_UTF8_ACS</STRONG> in + <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. + + Set this capability to a nonzero value to enable it. + + XM <EM>string</EM>, override ncurses's built-in string which enables/disables + <STRONG>xterm</STRONG> mouse mode. + + 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. + + The mouse protocol is enabled when the <EM>mask</EM> passed in the <STRONG>mouse-</STRONG> + <STRONG>mask</STRONG> function is nonzero. By default, ncurses handles the + responses for the X11 xterm mouse protocol. It also knows about + the <EM>SGR</EM> <EM>1006</EM> 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 confu- + sion would result. + + The <STRONG>XM</STRONG> 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 <EM>SGR</EM> <EM>1006</EM> xterm mouse protocol. + + 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 descrip- + tions. + + The terminal database building blocks for this mouse feature also + have an experimental capability <EM>xm</EM>. The "xm" capability + describes the mouse response. Currently there is no interpreter + which would use this information to make the mouse support com- + pletely data-driven. + + <EM>xm</EM> shows the format of the mouse responses. In this experimental + capability, the parameters are + + <EM>p1</EM> y-ordinate + + <EM>p2</EM> x-ordinate + + <EM>p3</EM> button + + <EM>p4</EM> state, e.g., pressed or released + + <EM>p5</EM> y-ordinate starting region + + <EM>p6</EM> x-ordinate starting region + + <EM>p7</EM> y-ordinate ending region + + <EM>p8</EM> x-ordinate ending region + + Here are examples from the terminal database for the most com- + monly used xterm mouse protocols: + + 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%;, + + +</PRE><H3><a name="h3-Extended-key-definitions">Extended key-definitions</a></H3><PRE> + Several terminals provide the ability to send distinct strings for com- + binations of modified special keys. There is no standard for what + those keys can send. + + Since 1999, <STRONG>xterm</STRONG> has supported <EM>shift</EM>, <EM>control</EM>, <EM>alt</EM>, and <EM>meta</EM> modifiers + which produce distinct special-key strings. In a terminal description, + ncurses has no special knowledge of the modifiers used. Applications + can use the <EM>naming</EM> <EM>convention</EM> established for <STRONG>xterm</STRONG> to find these spe- + cial keys in the terminal description. + + Starting with the curses convention that <EM>key</EM> <EM>names</EM> begin with "k" and + that shifted special keys are an uppercase name, ncurses' terminal + database defines these names to which a suffix is added: + + <EM>Name</EM> <EM>Description</EM> + --------------------------------------------------------------- + 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) + + These are the suffixes used to denote the modifiers: + + <EM>Value</EM> <EM>Description</EM> + ---------------------------------- + 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 + + None of these are predefined; terminal descriptions can refer to <EM>names</EM> + which ncurses will allocate at runtime to <EM>key-codes</EM>. To use these keys + in an ncurses program, an application could do this: + + <STRONG>o</STRONG> using a list of extended key <EM>names</EM>, ask <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> for their val- + ues, and + + <STRONG>o</STRONG> given the list of values, ask <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> for the <EM>key-code</EM> + which would be returned for those keys by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>. + + +</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> + The "-x" extension feature of <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> has been adopted in Net- + BSD curses. That implementation stores user-defined capabilities, but + makes no use of these capabilities itself. + + +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>. + + +</PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> + Thomas E. Dickey + beginning with ncurses 5.0 (1999) + + + + <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> +</PRE> +<div class="nav"> +<ul> +<li><a href="#h2-NAME">NAME</a></li> +<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> +<li><a href="#h2-DESCRIPTION">DESCRIPTION</a> +<ul> +<li><a href="#h3-Background">Background</a></li> +<li><a href="#h3-Recognized-capabilities">Recognized capabilities</a></li> +<li><a href="#h3-Extended-key-definitions">Extended key-definitions</a></li> +</ul> +</li> +<li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> +<li><a href="#h2-AUTHORS">AUTHORS</a></li> +</ul> +</div> +</BODY> +</HTML> |