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.47 2024/04/13 22:37:35 tom Exp @
  31 -->
  32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  33 <HTML>
  34 <HEAD>
  35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  37 <TITLE>curs_variables 3x 2024-04-13 ncurses 6.4 Library calls</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">curs_variables 3x 2024-04-13 ncurses 6.4 Library calls</H1>
  43 <PRE>
  44 <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>
  45
  46
  47
  48
  49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        <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>,
  51        <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>,
  52        <STRONG>TABSIZE</STRONG> - <EM>curses</EM> data types, constants, and global variables
  53
  54
  55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  56        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  57
  58        <EM>/*</EM> <EM>data</EM> <EM>types</EM> <EM>*/</EM>
  59        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>bool;</STRONG>
  60        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>chtype;</STRONG>
  61        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>cchar_t;</STRONG>
  62        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>attr_t;</STRONG>
  63        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>SCREEN;</STRONG>
  64        <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>WINDOW;</STRONG>
  65
  66        <EM>/*</EM> <EM>constants</EM> <EM>*/</EM>
  67        <STRONG>const</STRONG> <STRONG>bool</STRONG> <STRONG>TRUE;</STRONG>
  68        <STRONG>const</STRONG> <STRONG>bool</STRONG> <STRONG>FALSE;</STRONG>
  69
  70        <STRONG>const</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>ERR;</STRONG>
  71        <STRONG>const</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>OK;</STRONG>
  72
  73        <EM>/*</EM> <EM>variables</EM> <EM>*/</EM>
  74        <STRONG>int</STRONG> <STRONG>COLORS;</STRONG>
  75        <STRONG>int</STRONG> <STRONG>COLOR_PAIRS;</STRONG>
  76        <STRONG>int</STRONG> <STRONG>COLS;</STRONG>
  77        <STRONG>int</STRONG> <STRONG>LINES;</STRONG>
  78        <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>curscr;</STRONG>
  79        <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>stdscr;</STRONG>
  80
  81        <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
  82        <STRONG>int</STRONG> <STRONG>ESCDELAY;</STRONG>
  83        <STRONG>int</STRONG> <STRONG>TABSIZE;</STRONG>
  84        <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>newscr;</STRONG>
  85
  86
  87 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  88        This  page  summarizes data types, constants, and variables provided by
  89        the <EM>curses</EM> library.  Locate further discussion in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.
  90
  91        Depending on <EM>ncurses</EM>'s  build-time  configuration,  the  variables  may
  92        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
  93        provide read-only access to  the  library's  state.   In  either  case,
  94        applications  should  treat  them  as  read-only to avoid confusing the
  95        library.
  96
  97
  98 </PRE><H2><a name="h2-CONSTANTS">CONSTANTS</a></H2><PRE>
  99
 100 </PRE><H3><a name="h3-TRUE_FALSE">TRUE, FALSE</a></H3><PRE>
 101        The <EM>curses</EM> library defines <STRONG>TRUE</STRONG> and <STRONG>FALSE</STRONG> to represent  the  values  of
 102        the Boolean data type.
 103
 104
 105 </PRE><H3><a name="h3-ERR_OK">ERR, OK</a></H3><PRE>
 106        <EM>curses</EM>  and <EM>terminfo</EM> routines frequently return these constant integral
 107        values indicating failure and success, respectively.
 108
 109
 110 </PRE><H2><a name="h2-PREDEFINED-TYPES">PREDEFINED TYPES</a></H2><PRE>
 111
 112 </PRE><H3><a name="h3-bool"><EM>bool</EM></a></H3><PRE>
 113        X/Open Issue 4 <EM>curses</EM>  (1996)  preceded  the  ISO  C99  and  ISO  C++98
 114        standards,  each of which also defined a Boolean data type.  The <EM>curses</EM>
 115        library requires an integral type <EM>bool</EM>.
 116
 117        <STRONG>ncurses</STRONG>' configure script attempts to discover the data  type  used  by
 118        the system's C and C++ compilers, to reuse for the <EM>curses</EM> <EM>bool</EM>.
 119
 120
 121 </PRE><H3><a name="h3-chtype"><EM>chtype</EM></a></H3><PRE>
 122        The  <EM>chtype</EM>  integral  type combines a ("narrow", 8-bit) character with
 123        attributes encoding the character's <EM>rendition</EM>, such as the  styling  of
 124        its  typeface  and/or  foreground  and  background  colors.   See,  for
 125        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>.
 126
 127
 128 </PRE><H3><a name="h3-cchar_t_attr_t"><EM>cchar_t,</EM> attr_t</a></H3><PRE>
 129        <EM>chtype</EM> is too small for the standard C library's  wide-character  type,
 130        <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
 131        wide characters to store what  Unicode  terms  a  <EM>grapheme</EM>  <EM>cluster</EM>  (a
 132        "user-perceived  character"  [UAX  #29], which may nevertheless require
 133        several character encoding units to represent).  <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> is an  integral
 134        type  storing  "wide"  attributes  that  apply  to  <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>s.  See, for
 135        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>.
 136
 137
 138 </PRE><H3><a name="h3-SCREEN"><EM>SCREEN</EM></a></H3><PRE>
 139        <EM>curses</EM>  manages  a  terminal  device  with  this  structure  type;  see
 140        <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>.
 141
 142
 143 </PRE><H3><a name="h3-WINDOW"><EM>WINDOW</EM></a></H3><PRE>
 144        <EM>curses</EM>  represents rectangular portions of the terminal screen with the
 145        <EM>WINDOW</EM> structure type; see subsection "Overview" of <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
 146
 147
 148 </PRE><H2><a name="h2-VARIABLES">VARIABLES</a></H2><PRE>
 149
 150 </PRE><H3><a name="h3-curscr_stdscr_newscr">curscr, stdscr, newscr</a></H3><PRE>
 151        The library records updates to the terminal screen in  a  window  named
 152        <STRONG>curscr</STRONG>.   This  object  is  referred  to  as  the  "physical screen" in
 153        <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>.
 154
 155        <EM>ncurses</EM> collects pending updates to the terminal  screen  in  a  window
 156        named  <STRONG>newscr</STRONG>.   This  object is referred to as the "virtual screen" in
 157        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
 158        screen  is  refreshed, <EM>curses</EM> determines a minimal set of updates using
 159        the terminal's capabilities to make <STRONG>curscr</STRONG> look like <STRONG>newscr</STRONG>.
 160
 161        Once <EM>curses</EM> is initialized, it creates a window named  <STRONG>stdscr</STRONG>.   It  is
 162        the  same size as the terminal screen and is the default window used by
 163        routines that do not take a parameter  identifying  one.   Many  <EM>curses</EM>
 164        functions use this window.
 165
 166
 167 </PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE>
 168        Once  <EM>curses</EM>  is  initialized,  <STRONG>COLORS</STRONG>  contains  the  number of colors
 169        supported by the terminal; see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>.
 170
 171
 172 </PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE>
 173        Once <EM>curses</EM> is initialized, <STRONG>COLOR_PAIRS</STRONG> contains the  number  of  color
 174        pairs supported by the terminal; see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>.
 175
 176
 177 </PRE><H3><a name="h3-COLS_LINES">COLS, LINES</a></H3><PRE>
 178        Once  <EM>curses</EM>  is initialized, <STRONG>COLS</STRONG> and <STRONG>LINES</STRONG> contain the screen's width
 179        and height in character cells, respectively; that  is,  the  number  of
 180        columns and lines.
 181
 182
 183 </PRE><H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE>
 184        For  <EM>curses</EM>  to  distinguish  the ESC character resulting from a user's
 185        press of the "Escape" key on the input device  from  one  beginning  an
 186        <EM>escape</EM> <EM>sequence</EM> (as commonly produced by function keys), it waits after
 187        the escape character to see if further characters are available on  the
 188        input stream within a short interval.  <STRONG>ESCDELAY</STRONG> stores this interval in
 189        milliseconds.
 190
 191        If <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> is disabled for the  <EM>curses</EM>  window  receiving  input,  a
 192        program must disambiguate escape sequences itself.
 193
 194
 195 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
 196        The <EM>curses</EM> library converts a tab character to this number of spaces as
 197        it adds a tab to a window; see <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>.
 198
 199
 200 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 201        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>.
 202
 203        If  <EM>ncurses</EM>  is  configured  to  provide  separate  <EM>curses</EM>  and   <EM>tinfo</EM>
 204        libraries, most of these variables reside in the former.
 205
 206
 207 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 208        The  X/Open  Curses  standard  documents all of the foregoing types and
 209        symbols except for <STRONG>newscr</STRONG>, <STRONG>TABSIZE</STRONG>, and <STRONG>ESCDELAY</STRONG>.
 210
 211        X/Open Curses describes <STRONG>curscr</STRONG> only as "an  internal  data  structure";
 212        SVr4   gave  more  details,  noting  its  use  "for  certain  low-level
 213        operations like clearing and redrawing a  screen  containing  garbage".
 214        Neither specified its interaction with the rest of the interface beyond
 215        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>.
 216
 217        <STRONG>newscr</STRONG> is a feature of SVr4 <EM>curses</EM>.  When refreshing the screen, it  is
 218        used  as  a  working area for combining the standard window <STRONG>stdscr</STRONG> with
 219        any others the application may have created with <STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>.  When  the
 220        update of <STRONG>newscr</STRONG> is complete, <EM>curses</EM> modifies <STRONG>curscr</STRONG> to match <STRONG>newscr</STRONG>.
 221
 222        <STRONG>TABSIZE</STRONG> is a feature of SVr4 <EM>curses</EM>.
 223
 224        <STRONG>o</STRONG>   SVr4   initially  sets  <STRONG>TABSIZE</STRONG>  from  the  terminal  description's
 225            <STRONG>init_tabs</STRONG>  capability.   After  that,  it   can   be   altered   by
 226            applications using SVr4 <EM>curses</EM>.
 227
 228        <STRONG>o</STRONG>   SVr4  <EM>curses</EM>  uses  the value of <STRONG>TABSIZE</STRONG> to compute the position of
 229            tab stops when updating both the virtual screen with <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>  and
 230            the physical screen with <STRONG><A HREF="curs_terminfo.3x.html">mvcur(3x)</A></STRONG>.
 231
 232        <STRONG>o</STRONG>   <EM>ncurses</EM>  uses  the  value  of  <STRONG>TABSIZE</STRONG>  only  to update the virtual
 233            screen.   It  uses  the  terminal  description's  "<STRONG>it</STRONG>"  (<STRONG>init_tabs</STRONG>)
 234            capability  for  computing hardware tabs (that is, tab stops on the
 235            physical screen).
 236
 237        <STRONG>o</STRONG>   Other implementations differ.  For instance, NetBSD  <EM>curses</EM>  allows
 238            <STRONG>TABSIZE</STRONG>  to  be  set through an environment variable.  <EM>ncurses</EM> does
 239            not.
 240
 241            NetBSD <EM>curses</EM> does not support hardware tabs; it uses the <STRONG>init_tabs</STRONG>
 242            capability  and  the <STRONG>TABSIZE</STRONG> variable only for updating the virtual
 243            screen.
 244
 245        <STRONG>ESCDELAY</STRONG> is a feature of AIX <EM>curses</EM>.
 246
 247        <STRONG>o</STRONG>   In AIX, the units for <STRONG>ESCDELAY</STRONG> are <EM>fifths</EM> of milliseconds.
 248
 249        <STRONG>o</STRONG>   The default value for AIX's <STRONG>ESCDELAY</STRONG> equals 0.1 seconds.
 250
 251        <STRONG>o</STRONG>   AIX also enforces a limit of 10,000 seconds for  <STRONG>ESCDELAY</STRONG>;  <EM>ncurses</EM>
 252            does not enforce any upper limit.
 253
 254        <EM>ncurses</EM>  has  long  used <STRONG>ESCDELAY</STRONG> with units of milliseconds, making it
 255        impossible to be completely compatible with  AIX.   Consequently,  most
 256        users  have  decided  either to override the value, or to rely upon its
 257        default.
 258
 259
 260 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 261        <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>,
 262        <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>
 263
 264        [UAX  #29]  "Unicode  Standard  Annex  #29: Unicode Text Segmentation";
 265        &lt;https://unicode.org/reports/tr29/&gt;
 266
 267
 268
 269 ncurses 6.4                       2024-04-13                <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 270 </PRE>
 271 <div class="nav">
 272 <ul>
 273 <li><a href="#h2-NAME">NAME</a></li>
 274 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 275 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
 276 <li><a href="#h2-CONSTANTS">CONSTANTS</a>
 277 <ul>
 278 <li><a href="#h3-TRUE_FALSE">TRUE, FALSE</a></li>
 279 <li><a href="#h3-ERR_OK">ERR, OK</a></li>
 280 </ul>
 281 </li>
 282 <li><a href="#h2-PREDEFINED-TYPES">PREDEFINED TYPES</a>
 283 <ul>
 284 <li><a href="#h3-bool">bool</a></li>
 285 <li><a href="#h3-chtype">chtype</a></li>
 286 <li><a href="#h3-cchar_t_attr_t">cchar_t, attr_t</a></li>
 287 <li><a href="#h3-SCREEN">SCREEN</a></li>
 288 <li><a href="#h3-WINDOW">WINDOW</a></li>
 289 </ul>
 290 </li>
 291 <li><a href="#h2-VARIABLES">VARIABLES</a>
 292 <ul>
 293 <li><a href="#h3-curscr_stdscr_newscr">curscr, stdscr, newscr</a></li>
 294 <li><a href="#h3-COLORS">COLORS</a></li>
 295 <li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li>
 296 <li><a href="#h3-COLS_LINES">COLS, LINES</a></li>
 297 <li><a href="#h3-ESCDELAY">ESCDELAY</a></li>
 298 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
 299 </ul>
 300 </li>
 301 <li><a href="#h2-NOTES">NOTES</a></li>
 302 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 303 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 304 </ul>
 305 </div>
 306 </BODY>
 307 </HTML>