X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fuser_caps.5.html;h=0fd1f15d202aae3fd90affd49680d5e37ec4a128;hp=6d6e9126a28025603d05d3a89f0262fe6fefb1fe;hb=81304798ee736c467839c779c9ca5dca48db7bea;hpb=8f6d94b8d6211a2323caef53fa4c96c475ec9a62 diff --git a/doc/html/man/user_caps.5.html b/doc/html/man/user_caps.5.html index 6d6e9126..0fd1f15d 100644 --- a/doc/html/man/user_caps.5.html +++ b/doc/html/man/user_caps.5.html @@ -1,6 +1,7 @@ - @@ -56,20 +57,20 @@
- Before ncurses 5.0, terminfo databases used a fixed repertoire 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. + Before ncurses 5.0, terminfo databases used a fixed repertoire of + terminal 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 extensions 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: + the meaning of an existing capability, a new name was added. The + terminfo 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: - o The binary format itself is not described in the X/Open Curses doc- - umentation. Only the source format is described. + o The binary format itself is not described in the X/Open Curses + documentation. Only the source format is described. Library developers rely upon the SVr4 documentation, and reverse- engineering the compiled terminfo files to match the binary format. @@ -90,9 +91,9 @@ 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. + list published by X/Open Curses. For example, ncurses can be + configured with tables which match the terminal databases for AIX, + HP-UX or OSF/1, rather than the default Solaris-like configuration. o In SVr4 curses and ncurses, the terminal database is defined at compile-time using a text file which lists the different terminal @@ -100,9 +101,9 @@ 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: + used in ncurses for terminal capabilities includes details for + various systems past the documented X/Open Curses features. For + example, ncurses supports these capabilities in each configuration: memory_lock (meml) lock memory above cursor @@ -114,16 +115,16 @@ (box1) box characters primary set The memory lock/unlock capabilities were included because they were - used in the X11R6 terminal description for xterm. The box1 capa- - bility is used in tic to help with terminal descriptions written - for AIX. + used in the X11R6 terminal description for xterm. The box1 + capability 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: - o The fixed repertoire prevented users from adding features for unan- - ticipated terminal improvements (or required them to reuse existing - capabilities as a workaround). + o The fixed repertoire prevented users from adding features for + unanticipated terminal improvements (or required them to reuse + existing capabilities as a workaround). o The limitation to 16-bit signed integers was also mentioned. Because termcap stores everything as a string, it could represent @@ -131,10 +132,10 @@ Although termcap's extensibility was rarely used (it was never the speaker 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 - user-defined capabilities because no modifications to the toolset's + ncurses 5.0 provided a way to detect nonstandard capabilities, + determine their type and optionally store and retrieve them in a way + which did not interfere with other applications. These are referred to + as user-defined capabilities because no modifications to the toolset's predefined capability names are needed. The ncurses utilities tic and infocmp have a command-line option "-x" @@ -143,8 +144,8 @@ same purpose. When compiling a terminal database, if "-x" is set, tic will store a - user-defined capability if the capability name is not one of the prede- - fined names. + user-defined capability if the capability name is not one of the + predefined names. Because ncurses provides a termcap library interface, these user- defined capabilities may be visible to termcap applications: @@ -152,8 +153,8 @@ o 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. + When the capability is simple enough for use in a termcap + application, it is provided as a 2-character name. o There are other user-defined capabilities which refer to features not usable in termcap, e.g., parameterized strings that use more @@ -162,17 +163,17 @@ only capability names with 3 or more characters. o 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 xterm to provide extended spe- - cial-key names. + keypad- or function-keys) depending on modifier keys (shift, + control, etc.). While terminfo and termcap have a set of 60 + predefined function-key names, to which a series of keys can be + assigned, that is insufficient for more than a dozen keys + multiplied by more than a couple of modifier combinations. The + ncurses database uses a convention based on xterm to provide + extended special-key names. Fitting that into termcap's limitation of 2-character names would - be pointless. These extended keys are available only with ter- - minfo. + be pointless. These extended keys are available only with + terminfo.
@@ -227,27 +228,93 @@ i.e., one bit per color. U8 number, 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 NCURSES_NO_UTF8_ACS in - ncurses(3x). + drawing characters, and that it should ignore the alternate + character set capabilities when the locale uses UTF-8 encoding. + For more information, see the discussion of NCURSES_NO_UTF8_ACS + in ncurses(3x). Set this capability to a nonzero value to enable it. XM string, override ncurses's built-in string which enables/disables xterm 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 mask passed in the + mousemask function is nonzero. By default, ncurses handles the + responses for the X11 xterm mouse protocol. It also knows about + the SGR 1006 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 + confusion would result. + + The XM 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 SGR 1006 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 + descriptions. + + The terminal database building blocks for this mouse feature also + have an experimental capability xm. The "xm" capability + describes the mouse response. Currently there is no interpreter + which would use this information to make the mouse support + completely data-driven. + + xm shows the format of the mouse responses. In this experimental + capability, the parameters are + + p1 y-ordinate + + p2 x-ordinate + + p3 button + + p4 state, e.g., pressed or released + + p5 y-ordinate starting region + + p6 x-ordinate starting region + + p7 y-ordinate ending region + + p8 x-ordinate ending region + + Here are examples from the terminal database for the most + commonly 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%;, +
- Several terminals provide the ability to send distinct strings for com- - binations of modified special keys. There is no standard for what + Several terminals provide the ability to send distinct strings for + combinations of modified special keys. There is no standard for what those keys can send. Since 1999, xterm has supported shift, control, alt, and meta modifiers which produce distinct special-key strings. In a terminal description, ncurses has no special knowledge of the modifiers used. Applications - can use the naming convention established for xterm to find these spe- - cial keys in the terminal description. + can use the naming convention established for xterm to find these + special keys in the terminal description. Starting with the curses convention that key names begin with "k" and that shifted special keys are an uppercase name, ncurses' terminal @@ -289,21 +356,29 @@ which ncurses will allocate at runtime to key-codes. To use these keys in an ncurses program, an application could do this: - o using a list of extended key names, ask tigetstr(3x) for their val- - ues, and + o using a list of extended key names, ask tigetstr(3x) for their + values, and o given the list of values, ask key_defined(3x) for the key-code which would be returned for those keys by wgetch(3x).
- The "-x" extension feature of tic and infocmp has been adopted in Net- - BSD curses. That implementation stores user-defined capabilities, but - makes no use of these capabilities itself. + The "-x" extension feature of tic and infocmp has been adopted in + NetBSD curses. That implementation stores user-defined capabilities, + but makes no use of these capabilities itself.
- tic(1m), infocmp(1m). + infocmp(1m), tic(1m). + + The terminal database section NCURSES USER-DEFINABLE CAPABILITIES + summarizes commonly-used user-defined capabilities which are used in + the terminal descriptions. Some of those features are mentioned in + screen(1) or tmux(1). + + XTerm Control Sequences provides further information on the xterm + features which are used in these extended capabilities.