# curs_variables 3x 2023-10-07 ncurses 6.4 Library calls

    curs_variables(3x)               Library calls              curs_variables(3x)

## NAME

           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

## SYNOPSIS

           #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;

## DESCRIPTION

           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.

### bool, TRUE, FALSE

           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.

### ERR, OK

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

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

### 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(3x), attr_on(3x), and in_wch(3x).

### COLOR_PAIRS

           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.

### COLORS

           Once curses is  initialized,  COLORS  contains  the  number  of  colors
           supported by the terminal.

### COLS

           Once  curses  is  initialized,  COLS  contains  the  screen's  width in
           character cells; that is, the number of columns.

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

### LINES

           Once curses is initialized,  LINES  contains  the  screen's  height  in
           character cells; that is, the number of lines.

### TABSIZE

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

### curscr

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

### newscr

           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.

### stdscr

           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.

## NOTES

           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.

## 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";
           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.

## SEE ALSO

           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)