curs_variables(3x) Library calls curs_variables(3x)
bool, chtype, cchar_t, attr_t, WINDOW, TRUE, FALSE, ERR, OK, COLORS,
COLOR_PAIRS, COLS, ESCDELAY, LINES, TABSIZE, curscr, newscr, stdscr -
curses data types, constants, and global variables
#include <curses.h>
/* data types */
typedef /* ... */ bool;
typedef /* ... */ chtype;
typedef /* ... */ cchar_t;
typedef /* ... */ attr_t;
typedef /* ... */ WINDOW;
/* constants */
const bool TRUE;
const bool FALSE;
const /* ... */ ERR;
const /* ... */ OK;
/* variables */
int COLOR_PAIRS;
int COLORS;
int COLS;
int ESCDELAY;
int LINES;
int TABSIZE;
WINDOW * curscr;
WINDOW * newscr;
WINDOW * stdscr;
This page summarizes data types, constants, and variables provided by
the curses library. Locate further discussion in curses(3x).
Depending on ncurses's build-time configuration, the variables may
instead be macros (see curs_threads(3x) and curs_opaque(3x)) that
provide read-only access to the library's state. In either case,
applications should treat them as read-only to avoid confusing the
library.
X/Open Issue 4 curses (1996) preceded the ISO C99 and ISO C++98
standards, each of which also defined a Boolean data type. The curses
library requires an integral type bool and constants TRUE and FALSE to
store its two possible values.
curses and terminfo routines frequently return these constant integral
values indicating failure and success, respectively.
The chtype integral type combines a ("narrow", 8-bit) character with
attributes encoding the character's rendition, such as the styling of
its typeface and/or foreground and background colors. See, for
example, addch(3x), attron(3x), and inch(3x).
chtype is too small for the standard C library's wide-character type,
wchar_t. cchar_t is a type that can accommodate an attr_t and enough
wide characters to store what Unicode terms a grapheme cluster (a
"user-perceived character" [UAX #29], which may nevertheless require
several character encoding units to represent). attr_t is an integral
type storing "wide" attributes that apply to cchar_ts. See, for
example, add_wch(3x), attr_on(3x), and in_wch(3x).
Once curses is initialized, COLOR_PAIRS contains the number of color
pairs supported by the terminal. Often, its value is the product
COLORS x COLORS, but this is not always true.
o A few terminals use HLS colors, ignoring this rule; and
o terminals supporting a large number of colors are limited by the
number of color pairs that a signed short value can represent.
Once curses is initialized, COLORS contains the number of colors
supported by the terminal.
Once curses is initialized, COLS contains the screen's width in
character cells; that is, the number of columns.
For curses to distinguish an escape character corresponding to a user's
press of an "Escape" key on the input device from one included in a
control sequence used by a cursor movement or function key, the library
waits to see if another key event occurs after the escape character.
ESCDELAY stores this interval in milliseconds.
Once curses is initialized, LINES contains the screen's height in
character cells; that is, the number of lines.
The curses library converts a tab character to this number of spaces as
it adds a tab to a window; see curs_addch(3x).
curses records updates to the terminal screen in a WINDOW structure
named curscr.
This object is referred to as the "physical screen" in curs_refresh(3x)
and curs_outopts(3x).
ncurses collects pending updates to the terminal screen in a WINDOW
structure named newscr.
This object is referred to as the "virtual screen" in the
curs_kernel(3x), curs_refresh(3x), and curs_outopts(3x). When the
screen is refreshed, curses determines a minimal set of updates using
the terminal's capabilities to make curscr look like newscr.
Once curses is initialized, it creates a WINDOW structure named stdscr.
It is the same size as the terminal screen and is the default window
used by routines that do not take a parameter identifying one. Many
curses functions use this window.
Either initscr(3x) or newterm(3x) initializes curses.
If ncurses is configured to provide separate curses and terminfo
libraries, most of these variables reside in the curses library.
The X/Open Curses standard documents all of the foregoing types and
symbols except for newscr, TABSIZE, and ESCDELAY.
X/Open Curses describes curscr only as "an internal data structure";
SVID gave more details, noting its use "for certain low-level
operations like clearing and redrawing a screen containing garbage".
Neither specified its interaction with the rest of the interface beyond
use as an argument to clearok(3x) and wrefresh(3x).
newscr is a feature of SVr4 curses. When refreshing the screen, this
window is used as a working area for combining the standard screen
stdscr with any other windows which the application may have created
with newwin(3x). When the updated newscr is complete, curses updates
curscr to match newscr.
TABSIZE is a feature of SVr4 curses.
o SVr4 initially sets TABSIZE from the terminal description's
init_tabs capability. After that, it can be altered by
applications using SVr4 curses.
o SVr4 curses uses the value of TABSIZE to compute the position of
tab stops when updating both the virtual screen with addch(3x) and
the physical screen with mvcur(3x).
o ncurses uses the value of TABSIZE only to update the virtual
screen. It uses the terminal description's "it" (init_tabs)
capability for computing hardware tabs (that is, tab stops on the
physical screen).
o Other implementations differ. For instance, NetBSD curses allows
TABSIZE to be set through an environment variable. ncurses does
not.
NetBSD curses does not support hardware tabs; it uses the init_tabs
capability and the TABSIZE variable only for updating the virtual
screen.
ESCDELAY is a feature of AIX curses.
o In AIX, the units for ESCDELAY are fifths of milliseconds.
o The default value for AIX's ESCDELAY equals 0.1 seconds.
o AIX also enforces a limit of 10,000 seconds for ESCDELAY; ncurses
does not enforce any upper limit.
ncurses has long used ESCDELAY with units of milliseconds, making it
impossible to be completely compatible with AIX. Consequently, most
users have decided either to override the value, or to rely upon its
default.
curses(3x), curs_opaque(3x), curs_terminfo(3x), curs_threads(3x),
term_variables(3x), terminfo(5)
[UAX #29] "Unicode Standard Annex #29: Unicode Text Segmentation";
<https://unicode.org/reports/tr29/>
ncurses 6.4 2023-10-07 curs_variables(3x)