Ubuntu Manpage: bool, chtype, cchar_t, attr_t, SCREEN, WINDOW, TRUE, FALSE, ERR, OK, CCHARW

name
synopsis
description
constants
predefined types
variables
notes
extensions
portability
see also

Provided by: ncurses-doc_6.5+20250216-1_all

NAME

       bool,  chtype, cchar_t, attr_t, SCREEN, WINDOW, TRUE, FALSE, ERR, OK, CCHARW_MAX, curscr, newscr, stdscr,
       COLORS, COLOR_PAIRS, COLS, LINES, ESCDELAY, TABSIZE - curses data types, constants, and global variables

SYNOPSIS

       #include <curses.h>

       /* data types */
       typedef /* ... */ bool;
       typedef /* ... */ chtype;
       typedef /* ... */ cchar_t;
       typedef /* ... */ attr_t;
       typedef /* ... */ SCREEN;
       typedef /* ... */ WINDOW;

       /* constants */
       const bool TRUE;
       const bool FALSE;

       const /* ... */ ERR;
       const /* ... */ OK;

       /* extension */
       const /* ... */ CCHARW_MAX;

       /* variables */
       int COLORS;
       int COLOR_PAIRS;
       int COLS;
       int LINES;
       WINDOW * curscr;
       WINDOW * stdscr;

       /* extensions */
       int ESCDELAY;
       int TABSIZE;
       WINDOW * newscr;

DESCRIPTION

       This page summarizes data types, constants, and variables provided by the curses library.  Locate further
       discussion in ncurses(3NCURSES).

       Depending   on   ncurses's   build-time   configuration,   the  variables  may  instead  be  macros  (see
       threads(3NCURSES) and opaque(3NCURSES)) 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.

CONSTANTS

   TRUE, FALSE
       The curses library defines TRUE and FALSE to represent the values of the Boolean data type.

   ERR, OK
       curses  and  terminfo  routines  frequently  return these constant integral values indicating failure and
       success, respectively.

   CCHARW_MAX
       This integral value, an ncurses extension, contains the maximum number of wchar_t  wide  characters  that
       can be stored in a curses complex character cchar_t.

PREDEFINED TYPES

   bool
       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.

       ncurses' configure script attempts to discover the data type used by the system's C and C++ compilers, to
       reuse for the curses bool.

   chtype
       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(3NCURSES), attron(3NCURSES), and inch(3NCURSES).

   cchar_t, attr_t
       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(3NCURSES), attr_on(3NCURSES), and in_wch(3NCURSES).

   SCREEN
       curses manages a terminal device with this structure type; see initscr(3NCURSES).

   WINDOW
       curses  represents  rectangular  portions  of  the  terminal  screen  with the WINDOW structure type; see
       subsection “Overview” of ncurses(3NCURSES).

VARIABLES

curscr, newscr, stdscr
When a curses application calls initscr(3NCURSES) or newterm(3NCURSES), the library creates a window
named stdscr that is the same size as the terminal screen and is the implicit window used by functions
that interact with a window but do not take a parameter identifying one; many curses functions use it.
An application need not use stdscr; it might prefer to tile the display into multiple windows instead.

The library records updates to the terminal screen in a window named curscr. This object is referred to
as the “physical screen” in refresh(3NCURSES) and outopts(3NCURSES).

ncurses collects pending updates to the terminal screen in a window named newscr. This object is
referred to as the “virtual screen” in the kernel(3NCURSES), refresh(3NCURSES), and outopts(3NCURSES).
When the screen is refreshed, curses determines a minimal set of updates using the terminal's
capabilities to make curscr look like newscr.

COLORS
Once curses is initialized, COLORS contains the number of colors supported by the terminal; see
color(3NCURSES).

COLOR_PAIRS
Once curses is initialized, COLOR_PAIRS contains the number of color pairs supported by the terminal; see
color(3NCURSES).

COLS, LINES
Once curses is initialized, COLS and LINES contain the screen's width and height in character cells,
respectively; that is, the number of columns and lines.

ESCDELAY
For curses to distinguish the ESC character resulting from a user's press of the “Escape” key on the
input device from one beginning an escape sequence (as commonly produced by function keys), it waits
after the escape character to see if further characters are available on the input stream within a short
interval. ESCDELAY stores this interval in milliseconds.

If keypad(3NCURSES) is disabled for the curses window receiving input, a program must disambiguate escape
sequences itself.

TABSIZE
The curses library converts a tab character to this number of spaces as it adds a tab to a window; see
addch(3NCURSES).

NOTES

       Either initscr(3NCURSES) or newterm(3NCURSES) initializes curses.

       If  ncurses is configured to provide separate curses and tinfo libraries, most of these symbols reside in
       the former.  The bool data type is used by both.

EXTENSIONS

       The CCHARW_MAX constant, and ESCDELAY, TABSIZE, and newscr variables, are extensions, the first of  these
       originating in ncurses.

PORTABILITY

Applications employing ncurses extensions should condition their use on the visibility of the
NCURSES_VERSION preprocessor macro.

The X/Open Curses standard documents all of the foregoing types and symbols except for CCHARW_MAX,
newscr, TABSIZE, and ESCDELAY.

X/Open Curses describes curscr only as “an internal data structure”; SVr4 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(3NCURSES)
and wrefresh(3NCURSES).

newscr is a feature of SVr4 curses. When refreshing the screen, it is used as a working area for
combining the standard window stdscr with any others the application may have created with
newwin(3NCURSES). When the update of newscr is complete, curses modifies curscr to match newscr.

TABSIZE is a feature of SVr4 curses.

• SVr4 initially sets TABSIZE from the terminal description's init_tabs capability. After that, it can
be altered by applications using SVr4 curses.

• SVr4 curses uses the value of TABSIZE to compute the position of tab stops when updating both the
virtual screen with addch(3NCURSES) and the physical screen with mvcur(3NCURSES).

• 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).

• 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.

• In AIX, the units for ESCDELAY are fifths of milliseconds.

• The default value for AIX's ESCDELAY equals 0.1 seconds.

• 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.