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 -->
  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-01-05 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-01-05 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 an escape character corresponding to a user's
 185        press of an "Escape" key on the input device from  one  included  in  a
 186        control sequence used by a cursor movement or function key, the library
 187        waits to see if another key event occurs after  the  escape  character.
 188        <STRONG>ESCDELAY</STRONG> stores this interval in milliseconds.
 189
 190
 191 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
 192        The <EM>curses</EM> library converts a tab character to this number of spaces as
 193        it adds a tab to a window; see <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>.
 194
 195
 196 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 197        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>.
 198
 199        If <EM>ncurses</EM> is  configured  to  provide  separate  <EM>curses</EM>  and  <EM>terminfo</EM>
 200        libraries, most of these variables reside in the <EM>curses</EM> library.
 201
 202
 203 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 204        The  X/Open  Curses  standard  documents all of the foregoing types and
 205        symbols except for <STRONG>newscr</STRONG>, <STRONG>TABSIZE</STRONG>, and <STRONG>ESCDELAY</STRONG>.
 206
 207        X/Open Curses describes <STRONG>curscr</STRONG> only as "an  internal  data  structure";
 208        SVr4   gave  more  details,  noting  its  use  "for  certain  low-level
 209        operations like clearing and redrawing a  screen  containing  garbage".
 210        Neither specified its interaction with the rest of the interface beyond
 211        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>.
 212
 213        <STRONG>newscr</STRONG> is a feature of SVr4 <EM>curses</EM>.  When refreshing the screen, it  is
 214        used  as  a  working area for combining the standard window <STRONG>stdscr</STRONG> with
 215        any others the application may have created with <STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>.  When  the
 216        update of <STRONG>newscr</STRONG> is complete, <EM>curses</EM> modifies <STRONG>curscr</STRONG> to match <STRONG>newscr</STRONG>.
 217
 218        <STRONG>TABSIZE</STRONG> is a feature of SVr4 <EM>curses</EM>.
 219
 220        <STRONG>o</STRONG>   SVr4   initially  sets  <STRONG>TABSIZE</STRONG>  from  the  terminal  description's
 221            <STRONG>init_tabs</STRONG>  capability.   After  that,  it   can   be   altered   by
 222            applications using SVr4 <EM>curses</EM>.
 223
 224        <STRONG>o</STRONG>   SVr4  <EM>curses</EM>  uses  the value of <STRONG>TABSIZE</STRONG> to compute the position of
 225            tab stops when updating both the virtual screen with <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>  and
 226            the physical screen with <STRONG><A HREF="curs_terminfo.3x.html">mvcur(3x)</A></STRONG>.
 227
 228        <STRONG>o</STRONG>   <EM>ncurses</EM>  uses  the  value  of  <STRONG>TABSIZE</STRONG>  only  to update the virtual
 229            screen.   It  uses  the  terminal  description's  "<STRONG>it</STRONG>"  (<STRONG>init_tabs</STRONG>)
 230            capability  for  computing hardware tabs (that is, tab stops on the
 231            physical screen).
 232
 233        <STRONG>o</STRONG>   Other implementations differ.  For instance, NetBSD  <EM>curses</EM>  allows
 234            <STRONG>TABSIZE</STRONG>  to  be  set through an environment variable.  <EM>ncurses</EM> does
 235            not.
 236
 237            NetBSD <EM>curses</EM> does not support hardware tabs; it uses the <STRONG>init_tabs</STRONG>
 238            capability  and  the <STRONG>TABSIZE</STRONG> variable only for updating the virtual
 239            screen.
 240
 241        <STRONG>ESCDELAY</STRONG> is a feature of AIX <EM>curses</EM>.
 242
 243        <STRONG>o</STRONG>   In AIX, the units for <STRONG>ESCDELAY</STRONG> are <EM>fifths</EM> of milliseconds.
 244
 245        <STRONG>o</STRONG>   The default value for AIX's <STRONG>ESCDELAY</STRONG> equals 0.1 seconds.
 246
 247        <STRONG>o</STRONG>   AIX also enforces a limit of 10,000 seconds for  <STRONG>ESCDELAY</STRONG>;  <EM>ncurses</EM>
 248            does not enforce any upper limit.
 249
 250        <EM>ncurses</EM>  has  long  used <STRONG>ESCDELAY</STRONG> with units of milliseconds, making it
 251        impossible to be completely compatible with  AIX.   Consequently,  most
 252        users  have  decided  either to override the value, or to rely upon its
 253        default.
 254
 255
 256 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 257        <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>,
 258        <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>
 259
 260        [UAX  #29]  "Unicode  Standard  Annex  #29: Unicode Text Segmentation";
 261        &lt;https://unicode.org/reports/tr29/&gt;
 262
 263
 264
 265 ncurses 6.4                       2024-01-05                <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 266 </PRE>
 267 <div class="nav">
 268 <ul>
 269 <li><a href="#h2-NAME">NAME</a></li>
 270 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 271 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
 272 <li><a href="#h2-CONSTANTS">CONSTANTS</a>
 273 <ul>
 274 <li><a href="#h3-TRUE_FALSE">TRUE, FALSE</a></li>
 275 <li><a href="#h3-ERR_OK">ERR, OK</a></li>
 276 </ul>
 277 </li>
 278 <li><a href="#h2-PREDEFINED-TYPES">PREDEFINED TYPES</a>
 279 <ul>
 280 <li><a href="#h3-bool">bool</a></li>
 281 <li><a href="#h3-chtype">chtype</a></li>
 282 <li><a href="#h3-cchar_t_attr_t">cchar_t, attr_t</a></li>
 283 <li><a href="#h3-SCREEN">SCREEN</a></li>
 284 <li><a href="#h3-WINDOW">WINDOW</a></li>
 285 </ul>
 286 </li>
 287 <li><a href="#h2-VARIABLES">VARIABLES</a>
 288 <ul>
 289 <li><a href="#h3-curscr_stdscr_newscr">curscr, stdscr, newscr</a></li>
 290 <li><a href="#h3-COLORS">COLORS</a></li>
 291 <li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li>
 292 <li><a href="#h3-COLS_LINES">COLS, LINES</a></li>
 293 <li><a href="#h3-ESCDELAY">ESCDELAY</a></li>
 294 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
 295 </ul>
 296 </li>
 297 <li><a href="#h2-NOTES">NOTES</a></li>
 298 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 299 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 300 </ul>
 301 </div>
 302 </BODY>
 303 </HTML>