doc/html/man/curs_variables.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2023,2024 Thomas E. Dickey                                *
   4   * Copyright 2010-2015,2017 Free Software Foundation, Inc.                  *
   5   *                                                                          *
   6   * Permission is hereby granted, free of charge, to any person obtaining a  *
   7   * copy of this software and associated documentation files (the            *
   8   * "Software"), to deal in the Software without restriction, including      *
   9   * without limitation the rights to use, copy, modify, merge, publish,      *
  10   * distribute, distribute with modifications, sublicense, and/or sell       *
  11   * copies of the Software, and to permit persons to whom the Software is    *
  12   * furnished to do so, subject to the following conditions:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24   *                                                                          *
  25   * Except as contained in this notice, the name(s) of the above copyright   *
  26   * holders shall not be used in advertising or otherwise to promote the     *
  27   * sale, use or other dealings in this Software without prior written       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: curs_variables.3x,v 1.43 2024/01/05 21:46:58 tom Exp @
  31   * SVID 4, Volume 3, p. 408
  32 -->
  33 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  34 <HTML>
  35 <HEAD>
  36 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  37 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  38 <TITLE>curs_variables 3x 2024-01-05 ncurses 6.4 Library calls</TITLE>
  39 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  40
  41 </HEAD>
  42 <BODY>
  43 <H1 class="no-header">curs_variables 3x 2024-01-05 ncurses 6.4 Library calls</H1>
  44 <PRE>
  45 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>               Library calls              <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
  46
  47
  48
  49
  50 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  51        <EM>bool</EM>,  <EM>chtype</EM>,  <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>,  <EM>attr</EM><STRONG>_</STRONG><EM>t</EM>, <EM>SCREEN</EM>, <EM>WINDOW</EM>, <STRONG>TRUE</STRONG>, <STRONG>FALSE</STRONG>, <STRONG>ERR</STRONG>, <STRONG>OK</STRONG>,
  52        <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>, <STRONG>stdscr</STRONG>, <STRONG>COLORS</STRONG>,  <STRONG>COLOR_PAIRS</STRONG>,  <STRONG>COLS</STRONG>,  <STRONG>LINES</STRONG>,  <STRONG>ESCDELAY</STRONG>,
  53        <STRONG>TABSIZE</STRONG> - <EM>curses</EM> data types, constants, and global variables
  54
  55
  56 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  57        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  58
  59        <EM>/*</EM> <EM>data</EM> <EM>types</EM> <EM>*/</EM>
  60        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>bool;</STRONG>
  61        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>chtype;</STRONG>
  62        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>cchar_t;</STRONG>
  63        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>attr_t;</STRONG>
  64        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>SCREEN;</STRONG>
  65        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>WINDOW;</STRONG>
  66
  67        <EM>/*</EM> <EM>constants</EM> <EM>*/</EM>
  68        <STRONG>const</STRONG> <STRONG>bool</STRONG> <STRONG>TRUE;</STRONG>
  69        <STRONG>const</STRONG> <STRONG>bool</STRONG> <STRONG>FALSE;</STRONG>
  70
  71        <STRONG>const</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>ERR;</STRONG>
  72        <STRONG>const</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>OK;</STRONG>
  73
  74        <EM>/*</EM> <EM>variables</EM> <EM>*/</EM>
  75        <STRONG>int</STRONG> <STRONG>COLORS;</STRONG>
  76        <STRONG>int</STRONG> <STRONG>COLOR_PAIRS;</STRONG>
  77        <STRONG>int</STRONG> <STRONG>COLS;</STRONG>
  78        <STRONG>int</STRONG> <STRONG>LINES;</STRONG>
  79        <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>curscr;</STRONG>
  80        <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>stdscr;</STRONG>
  81
  82        <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
  83        <STRONG>int</STRONG> <STRONG>ESCDELAY;</STRONG>
  84        <STRONG>int</STRONG> <STRONG>TABSIZE;</STRONG>
  85        <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>newscr;</STRONG>
  86
  87
  88 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  89        This  page  summarizes data types, constants, and variables provided by
  90        the <EM>curses</EM> library.  Locate further discussion in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.
  91
  92        Depending on <EM>ncurses</EM>'s  build-time  configuration,  the  variables  may
  93        instead  be  macros  (see  <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>  and  <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>) that
  94        provide read-only access to  the  library's  state.   In  either  case,
  95        applications  should  treat  them  as  read-only to avoid confusing the
  96        library.
  97
  98
  99 </PRE><H2><a name="h2-CONSTANTS">CONSTANTS</a></H2><PRE>
 100
 101 </PRE><H3><a name="h3-TRUE_FALSE">TRUE, FALSE</a></H3><PRE>
 102        The <EM>curses</EM> library defines <STRONG>TRUE</STRONG> and <STRONG>FALSE</STRONG> to represent  the  values  of
 103        the Boolean data type.
 104
 105
 106 </PRE><H3><a name="h3-ERR_OK">ERR, OK</a></H3><PRE>
 107        <EM>curses</EM>  and <EM>terminfo</EM> routines frequently return these constant integral
 108        values indicating failure and success, respectively.
 109
 110
 111 </PRE><H2><a name="h2-PREDEFINED-TYPES">PREDEFINED TYPES</a></H2><PRE>
 112
 113 </PRE><H3><a name="h3-bool"><EM>bool</EM></a></H3><PRE>
 114        X/Open Issue 4 <EM>curses</EM>  (1996)  preceded  the  ISO  C99  and  ISO  C++98
 115        standards,  each of which also defined a Boolean data type.  The <EM>curses</EM>
 116        library requires an integral type <EM>bool</EM>.
 117
 118        <STRONG>ncurses</STRONG>' configure script attempts to discover the data  type  used  by
 119        the system's C and C++ compilers, to reuse for the <EM>curses</EM> <EM>bool</EM>.
 120
 121
 122 </PRE><H3><a name="h3-chtype"><EM>chtype</EM></a></H3><PRE>
 123        The  <EM>chtype</EM>  integral  type combines a ("narrow", 8-bit) character with
 124        attributes encoding the character's <EM>rendition</EM>, such as the  styling  of
 125        its  typeface  and/or  foreground  and  background  colors.   See,  for
 126        example, <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">attron(3x)</A></STRONG>, and <STRONG><A HREF="curs_inch.3x.html">inch(3x)</A></STRONG>.
 127
 128
 129 </PRE><H3><a name="h3-cchar_t_attr_t"><EM>cchar_t,</EM> attr_t</a></H3><PRE>
 130        <EM>chtype</EM> is too small for the standard C library's  wide-character  type,
 131        <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>.   <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>  is a type that can accommodate an <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> and enough
 132        wide characters to store what  Unicode  terms  a  <EM>grapheme</EM>  <EM>cluster</EM>  (a
 133        "user-perceived  character"  [UAX  #29], which may nevertheless require
 134        several character encoding units to represent).  <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> is an  integral
 135        type  storing  "wide"  attributes  that  apply  to  <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>s.  See, for
 136        example, <STRONG><A HREF="curs_add_wch.3x.html">add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">attr_on(3x)</A></STRONG>, and <STRONG><A HREF="curs_in_wch.3x.html">in_wch(3x)</A></STRONG>.
 137
 138
 139 </PRE><H3><a name="h3-SCREEN"><EM>SCREEN</EM></a></H3><PRE>
 140        <EM>curses</EM>  manages  a  terminal  device  with  this  structure  type;  see
 141        <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>.
 142
 143
 144 </PRE><H3><a name="h3-WINDOW"><EM>WINDOW</EM></a></H3><PRE>
 145        <EM>curses</EM>  represents rectangular portions of the terminal screen with the
 146        <EM>WINDOW</EM> structure type; see subsection "Overview" of <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
 147
 148
 149 </PRE><H2><a name="h2-VARIABLES">VARIABLES</a></H2><PRE>
 150
 151 </PRE><H3><a name="h3-curscr_stdscr_newscr">curscr, stdscr, newscr</a></H3><PRE>
 152        The library records updates to the terminal screen in  a  window  named
 153        <STRONG>curscr</STRONG>.   This  object  is  referred  to  as  the  "physical screen" in
 154        <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> and <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>.
 155
 156        <EM>ncurses</EM> collects pending updates to the terminal  screen  in  a  window
 157        named  <STRONG>newscr</STRONG>.   This  object is referred to as the "virtual screen" in
 158        the <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, and <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>.  When  the
 159        screen  is  refreshed, <EM>curses</EM> determines a minimal set of updates using
 160        the terminal's capabilities to make <STRONG>curscr</STRONG> look like <STRONG>newscr</STRONG>.
 161
 162        Once <EM>curses</EM> is initialized, it creates a window named  <STRONG>stdscr</STRONG>.   It  is
 163        the  same size as the terminal screen and is the default window used by
 164        routines that do not take a parameter  identifying  one.   Many  <EM>curses</EM>
 165        functions use this window.
 166
 167
 168 </PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE>
 169        Once  <EM>curses</EM>  is  initialized,  <STRONG>COLORS</STRONG>  contains  the  number of colors
 170        supported by the terminal; see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>.
 171
 172
 173 </PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE>
 174        Once <EM>curses</EM> is initialized, <STRONG>COLOR_PAIRS</STRONG> contains the  number  of  color
 175        pairs supported by the terminal; see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>.
 176
 177
 178 </PRE><H3><a name="h3-COLS_LINES">COLS, LINES</a></H3><PRE>
 179        Once  <EM>curses</EM>  is initialized, <STRONG>COLS</STRONG> and <STRONG>LINES</STRONG> contain the screen's width
 180        and height in character cells, respectively; that  is,  the  number  of
 181        columns and lines.
 182
 183
 184 </PRE><H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE>
 185        For <EM>curses</EM> to distinguish an escape character corresponding to a user's
 186        press of an "Escape" key on the input device from  one  included  in  a
 187        control sequence used by a cursor movement or function key, the library
 188        waits to see if another key event occurs after  the  escape  character.
 189        <STRONG>ESCDELAY</STRONG> stores this interval in milliseconds.
 190
 191
 192 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
 193        The <EM>curses</EM> library converts a tab character to this number of spaces as
 194        it adds a tab to a window; see <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>.
 195
 196
 197 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 198        Either <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> initializes <EM>curses</EM>.
 199
 200        If <EM>ncurses</EM> is  configured  to  provide  separate  <EM>curses</EM>  and  <EM>terminfo</EM>
 201        libraries, most of these variables reside in the <EM>curses</EM> library.
 202
 203
 204 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 205        The  X/Open  Curses  standard  documents all of the foregoing types and
 206        symbols except for <STRONG>newscr</STRONG>, <STRONG>TABSIZE</STRONG>, and <STRONG>ESCDELAY</STRONG>.
 207
 208        X/Open Curses describes <STRONG>curscr</STRONG> only as "an  internal  data  structure";
 209        SVr4   gave  more  details,  noting  its  use  "for  certain  low-level
 210        operations like clearing and redrawing a  screen  containing  garbage".
 211        Neither specified its interaction with the rest of the interface beyond
 212        use as an argument to <STRONG><A HREF="curs_outopts.3x.html">clearok(3x)</A></STRONG> and <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>.
 213
 214        <STRONG>newscr</STRONG> is a feature of SVr4 <EM>curses</EM>.  When refreshing the screen, it  is
 215        used  as  a  working area for combining the standard window <STRONG>stdscr</STRONG> with
 216        any others the application may have created with <STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>.  When  the
 217        update of <STRONG>newscr</STRONG> is complete, <EM>curses</EM> modifies <STRONG>curscr</STRONG> to match <STRONG>newscr</STRONG>.
 218
 219        <STRONG>TABSIZE</STRONG> is a feature of SVr4 <EM>curses</EM>.
 220
 221        <STRONG>o</STRONG>   SVr4   initially  sets  <STRONG>TABSIZE</STRONG>  from  the  terminal  description's
 222            <STRONG>init_tabs</STRONG>  capability.   After  that,  it   can   be   altered   by
 223            applications using SVr4 <EM>curses</EM>.
 224
 225        <STRONG>o</STRONG>   SVr4  <EM>curses</EM>  uses  the value of <STRONG>TABSIZE</STRONG> to compute the position of
 226            tab stops when updating both the virtual screen with <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>  and
 227            the physical screen with <STRONG><A HREF="curs_terminfo.3x.html">mvcur(3x)</A></STRONG>.
 228
 229        <STRONG>o</STRONG>   <EM>ncurses</EM>  uses  the  value  of  <STRONG>TABSIZE</STRONG>  only  to update the virtual
 230            screen.   It  uses  the  terminal  description's  "<STRONG>it</STRONG>"  (<STRONG>init_tabs</STRONG>)
 231            capability  for  computing hardware tabs (that is, tab stops on the
 232            physical screen).
 233
 234        <STRONG>o</STRONG>   Other implementations differ.  For instance, NetBSD  <EM>curses</EM>  allows
 235            <STRONG>TABSIZE</STRONG>  to  be  set through an environment variable.  <EM>ncurses</EM> does
 236            not.
 237
 238            NetBSD <EM>curses</EM> does not support hardware tabs; it uses the <STRONG>init_tabs</STRONG>
 239            capability  and  the <STRONG>TABSIZE</STRONG> variable only for updating the virtual
 240            screen.
 241
 242        <STRONG>ESCDELAY</STRONG> is a feature of AIX <EM>curses</EM>.
 243
 244        <STRONG>o</STRONG>   In AIX, the units for <STRONG>ESCDELAY</STRONG> are <EM>fifths</EM> of milliseconds.
 245
 246        <STRONG>o</STRONG>   The default value for AIX's <STRONG>ESCDELAY</STRONG> equals 0.1 seconds.
 247
 248        <STRONG>o</STRONG>   AIX also enforces a limit of 10,000 seconds for  <STRONG>ESCDELAY</STRONG>;  <EM>ncurses</EM>
 249            does not enforce any upper limit.
 250
 251        <EM>ncurses</EM>  has  long  used <STRONG>ESCDELAY</STRONG> with units of milliseconds, making it
 252        impossible to be completely compatible with  AIX.   Consequently,  most
 253        users  have  decided  either to override the value, or to rely upon its
 254        default.
 255
 256
 257 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 258        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,   <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>,    <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>,    <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>,
 259        <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
 260
 261        [UAX  #29]  "Unicode  Standard  Annex  #29: Unicode Text Segmentation";
 262        &lt;https://unicode.org/reports/tr29/&gt;
 263
 264
 265
 266 ncurses 6.4                       2024-01-05                <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 267 </PRE>
 268 <div class="nav">
 269 <ul>
 270 <li><a href="#h2-NAME">NAME</a></li>
 271 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 272 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
 273 <li><a href="#h2-CONSTANTS">CONSTANTS</a>
 274 <ul>
 275 <li><a href="#h3-TRUE_FALSE">TRUE, FALSE</a></li>
 276 <li><a href="#h3-ERR_OK">ERR, OK</a></li>
 277 </ul>
 278 </li>
 279 <li><a href="#h2-PREDEFINED-TYPES">PREDEFINED TYPES</a>
 280 <ul>
 281 <li><a href="#h3-bool">bool</a></li>
 282 <li><a href="#h3-chtype">chtype</a></li>
 283 <li><a href="#h3-cchar_t_attr_t">cchar_t, attr_t</a></li>
 284 <li><a href="#h3-SCREEN">SCREEN</a></li>
 285 <li><a href="#h3-WINDOW">WINDOW</a></li>
 286 </ul>
 287 </li>
 288 <li><a href="#h2-VARIABLES">VARIABLES</a>
 289 <ul>
 290 <li><a href="#h3-curscr_stdscr_newscr">curscr, stdscr, newscr</a></li>
 291 <li><a href="#h3-COLORS">COLORS</a></li>
 292 <li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li>
 293 <li><a href="#h3-COLS_LINES">COLS, LINES</a></li>
 294 <li><a href="#h3-ESCDELAY">ESCDELAY</a></li>
 295 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
 296 </ul>
 297 </li>
 298 <li><a href="#h2-NOTES">NOTES</a></li>
 299 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 300 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 301 </ul>
 302 </div>
 303 </BODY>
 304 </HTML>