man/curs_variables.3x

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