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

Provided by: ncurses-doc_6.5+20251123-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 functions frequently return these constant integral  values  indicating  failure  and
       success, respectively.

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

DATA TYPES

   bool
       curses defines an integral type 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 of the same name.

       ncurses's  configure  script attempts to discover the data type used by the system's C and C++ compilers,
       to reuse them as its own 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, (minus any lines reserved by
ripoffline(3NCURSES) or slk_init(3NCURSES)) 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 a curses screen is initialized, COLORS contains the number of colors supported by the terminal; see
color(3NCURSES).

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

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

ESCDELAY
When reading key strokes from a window in keypad mode, curses distinguishes the ESC character resulting
from a user's press of the “Escape” key on the input device from one beginning an escape sequence
(commonly produced by function keys), by waiting after receiving 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

       Initialize a curses screen with either initscr(3NCURSES) or newterm(3NCURSES).

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

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 (it) capability. After that,
it can be altered by applications using SVr4 curses.

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

• In ncurses, TABSIZE's value affects only the virtual screen. The library uses the terminal type
description's init_tabs (it) capability to compute 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 (it) capability and the TABSIZE
variable only to update the virtual screen.

ESCDELAY is a feature of AIX curses.

• AIX treats ESCDELAY's value as counting fifths of milliseconds.

• AIX's default ESCDELAY equals 0.1 seconds.

• AIX also enforces a limit of 10,000 seconds for ESCDELAY; ncurses does not enforce an upper limit.

ncurses has long interpreted ESCDELAY as a count 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.