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

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2021,2023 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.35 2023/12/16 21:05:52 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 2023-12-16 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 2023-12-16 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>WINDOW</EM>, <STRONG>TRUE</STRONG>, <STRONG>FALSE</STRONG>, <STRONG>ERR</STRONG>, <STRONG>OK</STRONG>, <STRONG>COLORS</STRONG>,
  51        <STRONG>COLOR_PAIRS</STRONG>, <STRONG>COLS</STRONG>, <STRONG>ESCDELAY</STRONG>, <STRONG>LINES</STRONG>, <STRONG>TABSIZE</STRONG>, <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>,  <STRONG>stdscr</STRONG>  -
  52        <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>WINDOW;</STRONG>
  64
  65        <EM>/*</EM> <EM>constants</EM> <EM>*/</EM>
  66        <STRONG>const</STRONG> <STRONG>bool</STRONG> <STRONG>TRUE;</STRONG>
  67        <STRONG>const</STRONG> <STRONG>bool</STRONG> <STRONG>FALSE;</STRONG>
  68
  69        <STRONG>const</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>ERR;</STRONG>
  70        <STRONG>const</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>OK;</STRONG>
  71
  72        <EM>/*</EM> <EM>variables</EM> <EM>*/</EM>
  73        <STRONG>int</STRONG> <STRONG>COLOR_PAIRS;</STRONG>
  74        <STRONG>int</STRONG> <STRONG>COLORS;</STRONG>
  75        <STRONG>int</STRONG> <STRONG>COLS;</STRONG>
  76        <STRONG>int</STRONG> <STRONG>LINES;</STRONG>
  77        <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>curscr;</STRONG>
  78        <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>stdscr;</STRONG>
  79        <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
  80        <STRONG>int</STRONG> <STRONG>ESCDELAY;</STRONG>
  81        <STRONG>int</STRONG> <STRONG>TABSIZE;</STRONG>
  82        <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>newscr;</STRONG>
  83
  84
  85 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  86        This  page  summarizes data types, constants, and variables provided by
  87        the <EM>curses</EM> library.  Locate further discussion in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.
  88
  89        Depending on <EM>ncurses</EM>'s  build-time  configuration,  the  variables  may
  90        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
  91        provide read-only access to  the  library's  state.   In  either  case,
  92        applications  should  treat  them  as  read-only to avoid confusing the
  93        library.
  94
  95
  96 </PRE><H3><a name="h3-bool_-TRUE_-FALSE"><EM>bool,</EM> TRUE, FALSE</a></H3><PRE>
  97        X/Open Issue 4 <EM>curses</EM>  (1996)  preceded  the  ISO  C99  and  ISO  C++98
  98        standards,  each of which also defined a Boolean data type.  The <EM>curses</EM>
  99        library requires an integral type <EM>bool</EM> and constants <STRONG>TRUE</STRONG> and <STRONG>FALSE</STRONG>  to
 100        store its two possible values.
 101
 102
 103 </PRE><H3><a name="h3-ERR_-OK">ERR, OK</a></H3><PRE>
 104        <EM>curses</EM>  and <EM>terminfo</EM> routines frequently return these constant integral
 105        values indicating failure and success, respectively.
 106
 107
 108 </PRE><H3><a name="h3-chtype"><EM>chtype</EM></a></H3><PRE>
 109        The <EM>chtype</EM> integral type combines a ("narrow",  8-bit)  character  with
 110        attributes  encoding  the character's <EM>rendition</EM>, such as the styling of
 111        its  typeface  and/or  foreground  and  background  colors.   See,  for
 112        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>.
 113
 114
 115 </PRE><H3><a name="h3-cchar_t_-attr_t"><EM>cchar_t,</EM> attr_t</a></H3><PRE>
 116        <EM>chtype</EM>  is  too small for the standard C library's wide-character type,
 117        <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
 118        wide  characters  to  store  what  Unicode  terms a <EM>grapheme</EM> <EM>cluster</EM> (a
 119        "user-perceived character" [UAX #29], which  may  nevertheless  require
 120        several  character encoding units to represent).  <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> is an integral
 121        type storing "wide"  attributes  that  apply  to  <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>s.   See,  for
 122        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>.
 123
 124
 125 </PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE>
 126        Once  <EM>curses</EM>  is  initialized, <STRONG>COLOR_PAIRS</STRONG> contains the number of color
 127        pairs supported by the terminal.   Often,  its  value  is  the  product
 128        <STRONG>COLORS</STRONG> x <STRONG>COLORS</STRONG>, but this is not always true.
 129
 130        <STRONG>o</STRONG>   A few terminals use HLS colors, ignoring this rule; and
 131
 132        <STRONG>o</STRONG>   terminals  supporting  a  large number of colors are limited by the
 133            number of color pairs that a <EM>signed</EM> <EM>short</EM> value can represent.
 134
 135
 136 </PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE>
 137        Once <EM>curses</EM> is  initialized,  <STRONG>COLORS</STRONG>  contains  the  number  of  colors
 138        supported by the terminal.
 139
 140
 141 </PRE><H3><a name="h3-COLS">COLS</a></H3><PRE>
 142        Once  <EM>curses</EM>  is  initialized,  <STRONG>COLS</STRONG>  contains  the  screen's  width in
 143        character cells; that is, the number of columns.
 144
 145
 146 </PRE><H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE>
 147        For <EM>curses</EM> to distinguish an escape character corresponding to a user's
 148        press  of  an  "Escape"  key on the input device from one included in a
 149        control sequence used by a cursor movement or function key, the library
 150        waits  to  see  if another key event occurs after the escape character.
 151        <STRONG>ESCDELAY</STRONG> stores this interval in milliseconds.
 152
 153
 154 </PRE><H3><a name="h3-LINES">LINES</a></H3><PRE>
 155        Once <EM>curses</EM> is initialized,  <STRONG>LINES</STRONG>  contains  the  screen's  height  in
 156        character cells; that is, the number of lines.
 157
 158
 159 </PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
 160        The <EM>curses</EM> library converts a tab character to this number of spaces as
 161        it adds a tab to a window; see <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>.
 162
 163
 164 </PRE><H3><a name="h3-curscr">curscr</a></H3><PRE>
 165        <EM>curses</EM> records updates to the terminal screen  in  a  <EM>WINDOW</EM>  structure
 166        named <STRONG>curscr</STRONG>.
 167
 168        This object is referred to as the "physical screen" in <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
 169        and <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>.
 170
 171
 172 </PRE><H3><a name="h3-newscr">newscr</a></H3><PRE>
 173        <EM>ncurses</EM> collects pending updates to the terminal  screen  in  a  <EM>WINDOW</EM>
 174        structure named <STRONG>newscr</STRONG>.
 175
 176        This   object   is   referred   to  as  the  "virtual  screen"  in  the
 177        <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
 178        screen  is  refreshed, <EM>curses</EM> determines a minimal set of updates using
 179        the terminal's capabilities to make <STRONG>curscr</STRONG> look like <STRONG>newscr</STRONG>.
 180
 181
 182 </PRE><H3><a name="h3-stdscr">stdscr</a></H3><PRE>
 183        Once <EM>curses</EM> is initialized, it creates a <EM>WINDOW</EM> structure named <STRONG>stdscr</STRONG>.
 184        It  is  the  same size as the terminal screen and is the default window
 185        used by routines that do not take a parameter  identifying  one.   Many
 186        <EM>curses</EM> functions use this window.
 187
 188
 189 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 190        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>.
 191
 192        If  <EM>ncurses</EM>  is  configured  to  provide  separate  <EM>curses</EM> and <EM>terminfo</EM>
 193        libraries, most of these variables reside in the <EM>curses</EM> library.
 194
 195
 196 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 197        The X/Open Curses standard documents all of  the  foregoing  types  and
 198        symbols except for <STRONG>newscr</STRONG>, <STRONG>TABSIZE</STRONG>, and <STRONG>ESCDELAY</STRONG>.
 199
 200        X/Open  Curses  describes  <STRONG>curscr</STRONG> only as "an internal data structure";
 201        SVID  gave  more  details,  noting  its  use  "for  certain   low-level
 202        operations  like  clearing  and redrawing a screen containing garbage".
 203        Neither specified its interaction with the rest of the interface beyond
 204        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>.
 205
 206        <STRONG>newscr</STRONG>  is  a feature of SVr4 <EM>curses</EM>.  When refreshing the screen, this
 207        window is used as a working area  for  combining  the  standard  screen
 208        <STRONG>stdscr</STRONG>  with  any  other windows which the application may have created
 209        with <STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>.  When the updated <STRONG>newscr</STRONG> is complete,  <EM>curses</EM>  updates
 210        <STRONG>curscr</STRONG> to match <STRONG>newscr</STRONG>.
 211
 212        <STRONG>TABSIZE</STRONG> is a feature of SVr4 <EM>curses</EM>.
 213
 214        <STRONG>o</STRONG>   SVr4   initially  sets  <STRONG>TABSIZE</STRONG>  from  the  terminal  description's
 215            <STRONG>init_tabs</STRONG>  capability.   After  that,  it   can   be   altered   by
 216            applications using SVr4 <EM>curses</EM>.
 217
 218        <STRONG>o</STRONG>   SVr4  <EM>curses</EM>  uses  the value of <STRONG>TABSIZE</STRONG> to compute the position of
 219            tab stops when updating both the virtual screen with <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>  and
 220            the physical screen with <STRONG><A HREF="curs_terminfo.3x.html">mvcur(3x)</A></STRONG>.
 221
 222        <STRONG>o</STRONG>   <EM>ncurses</EM>  uses  the  value  of  <STRONG>TABSIZE</STRONG>  only  to update the virtual
 223            screen.   It  uses  the  terminal  description's  "<STRONG>it</STRONG>"  (<STRONG>init_tabs</STRONG>)
 224            capability  for  computing hardware tabs (that is, tab stops on the
 225            physical screen).
 226
 227        <STRONG>o</STRONG>   Other implementations differ.  For instance, NetBSD  <EM>curses</EM>  allows
 228            <STRONG>TABSIZE</STRONG>  to  be  set through an environment variable.  <EM>ncurses</EM> does
 229            not.
 230
 231            NetBSD <EM>curses</EM> does not support hardware tabs; it uses the <STRONG>init_tabs</STRONG>
 232            capability  and  the <STRONG>TABSIZE</STRONG> variable only for updating the virtual
 233            screen.
 234
 235        <STRONG>ESCDELAY</STRONG> is a feature of AIX <EM>curses</EM>.
 236
 237        <STRONG>o</STRONG>   In AIX, the units for <STRONG>ESCDELAY</STRONG> are <EM>fifths</EM> of milliseconds.
 238
 239        <STRONG>o</STRONG>   The default value for AIX's <STRONG>ESCDELAY</STRONG> equals 0.1 seconds.
 240
 241        <STRONG>o</STRONG>   AIX also enforces a limit of 10,000 seconds for  <STRONG>ESCDELAY</STRONG>;  <EM>ncurses</EM>
 242            does not enforce any upper limit.
 243
 244        <EM>ncurses</EM>  has  long  used <STRONG>ESCDELAY</STRONG> with units of milliseconds, making it
 245        impossible to be completely compatible with  AIX.   Consequently,  most
 246        users  have  decided  either to override the value, or to rely upon its
 247        default.
 248
 249
 250 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 251        <STRONG><A HREF="ncurses.3x.html">curses(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>,   <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>,
 252        <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
 253
 254        [UAX  #29]  "Unicode  Standard  Annex  #29: Unicode Text Segmentation";
 255        &lt;https://unicode.org/reports/tr29/&gt;
 256
 257
 258
 259 ncurses 6.4                       2023-12-16                <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 260 </PRE>
 261 <div class="nav">
 262 <ul>
 263 <li><a href="#h2-NAME">NAME</a></li>
 264 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 265 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 266 <ul>
 267 <li><a href="#h3-bool_-TRUE_-FALSE">bool, TRUE, FALSE</a></li>
 268 <li><a href="#h3-ERR_-OK">ERR, OK</a></li>
 269 <li><a href="#h3-chtype">chtype</a></li>
 270 <li><a href="#h3-cchar_t_-attr_t">cchar_t, attr_t</a></li>
 271 <li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li>
 272 <li><a href="#h3-COLORS">COLORS</a></li>
 273 <li><a href="#h3-COLS">COLS</a></li>
 274 <li><a href="#h3-ESCDELAY">ESCDELAY</a></li>
 275 <li><a href="#h3-LINES">LINES</a></li>
 276 <li><a href="#h3-TABSIZE">TABSIZE</a></li>
 277 <li><a href="#h3-curscr">curscr</a></li>
 278 <li><a href="#h3-newscr">newscr</a></li>
 279 <li><a href="#h3-stdscr">stdscr</a></li>
 280 </ul>
 281 </li>
 282 <li><a href="#h2-NOTES">NOTES</a></li>
 283 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 284 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 285 </ul>
 286 </div>
 287 </BODY>
 288 </HTML>