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

Provided by: ncurses-doc_6.4+20240113-1ubuntu2_all

NAME

       bool,  chtype,  cchar_t,  attr_t,  SCREEN,  WINDOW,  TRUE, FALSE, ERR, OK, 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;

       /* 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.

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, stdscr, newscr
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.

Once curses is initialized, it creates a window 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.

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

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 terminfo libraries, most of these
       variables reside in the curses library.

PORTABILITY

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”; 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.