path: root/doc/html/man/user_caps.5.html
diff options
authorBaptiste Daroussin <bapt@FreeBSD.org>2020-02-07 08:36:41 +0000
committerBaptiste Daroussin <bapt@FreeBSD.org>2020-02-07 08:36:41 +0000
commitf0179cb6083cc92e5947ae56e6a0a5c5328aead0 (patch)
treebcee0ba9c2149b71f0bfc036df1e61e3105bf980 /doc/html/man/user_caps.5.html
parentcea297eb34d2361e79529034397465068ae34ecd (diff)
Vendor import ncurses 6.1-20200118vendor/ncurses/6.1-20200118
Notes: svn path=/vendor/ncurses/dist/; revision=357645 svn path=/vendor/ncurses/6.1-20200118/; revision=357646; tag=vendor/ncurses/6.1-20200118
Diffstat (limited to 'doc/html/man/user_caps.5.html')
1 files changed, 400 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 000000000000..3c3a90243221
--- /dev/null
+++ b/doc/html/man/user_caps.5.html
@@ -0,0 +1,400 @@
+ ****************************************************************************
+ * Copyright (c) 2017-2019,2020 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. *
+ * *
+ * *
+ * 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.11 2020/01/19 02:01:39 tom Exp @
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
+<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">
+<H1 class="no-header">user_caps 5</H1>
+<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>
+</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.
+ <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[&lt;, XM=\E[?1006;1000%?%p1%{1}%=%th%el%;,
+ xm=\E[&lt;%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>
+<div class="nav">
+<li><a href="#h2-NAME">NAME</a></li>
+<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
+<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
+<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>
+<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>