ncurses 6.2 - patch 20210626
[ncurses.git] / doc / html / man / user_caps.5.html
index 6d6e9126a28025603d05d3a89f0262fe6fefb1fe..0fd1f15d202aae3fd90affd49680d5e37ec4a128 100644 (file)
@@ -1,6 +1,7 @@
-<!-- 
+<!--
   ****************************************************************************
-  * Copyright (c) 2017,2018 Free Software Foundation, Inc.                   *
+  * Copyright 2018-2020,2021 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            *
@@ -26,7 +27,7 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: user_caps.5,v 1.9 2018/07/28 22:05:23 tom Exp @
+  * @Id: user_caps.5,v 1.17 2021/06/17 21:30:22 tom Exp @
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 </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.
+       Before  ncurses  5.0,  terminfo  databases  used  a <EM>fixed</EM> <EM>repertoire</EM> 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 <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:
+       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:
 
-       <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.
+       <STRONG>o</STRONG>   The  <EM>binary</EM>  <EM>format</EM>  itself  is  not described in the X/Open Curses
+           documentation.  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.
@@ -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.
 
        <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
 
            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
                     (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.
+           used in  the  X11R6  terminal  description  for  <STRONG>xterm</STRONG>.   The  <EM>box1</EM>
+           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:
 
-       <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  fixed  repertoire  prevented  users  from  adding features for
+           unanticipated 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
 
        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
+       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 <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"
        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.
+       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:
        <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.
+           When  the  capability  is  simple  enough  for  use  in  a  termcap
+           application, 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
            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.
+           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  <STRONG>xterm</STRONG> 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.
 
 
 </PRE><H3><a name="h3-Recognized-capabilities">Recognized capabilities</a></H3><PRE>
              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>.
+             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 <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>mousemask</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
+             confusion 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
+             descriptions.
+
+             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
+             completely 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
+             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[&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
+       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, <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.
+       can use the <EM>naming</EM> <EM>convention</EM>  established  for  <STRONG>xterm</STRONG>  to  find  these
+       special 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
        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>   using  a  list  of  extended  key <EM>names</EM>, ask <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> for their
+           values, 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.
+       The  "-x"  extension  feature  of  <STRONG>tic</STRONG>  and <STRONG>infocmp</STRONG> has been adopted in
+       NetBSD 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>.
+       <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>.
+
+       The  terminal  database  section  <EM>NCURSES</EM>  <EM>USER-DEFINABLE</EM>  <EM>CAPABILITIES</EM>
+       summarizes commonly-used user-defined capabilities which  are  used  in
+       the  terminal  descriptions.   Some  of those features are mentioned in
+       <STRONG>screen(1)</STRONG> or <STRONG>tmux(1)</STRONG>.
+
+       <EM>XTerm</EM> <EM>Control</EM> <EM>Sequences</EM>  provides  further  information  on  the  <STRONG>xterm</STRONG>
+       features which are used in these extended capabilities.
 
 
 </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE>