- This page summarizes variables provided by the curses library. A more
- complete description is given in the curses(3x) manual page.
+ This page summarizes data types, constants, and variables provided by
+ the curses library. Locate further discussion in curses(3x).
- Depending on the configuration, these may be actual variables, or
- macros (see curs_threads(3x) and curs_opaque(3x)) which provide read-
- only access to curses's state. In either case, applications should
- treat them as read-only to avoid confusing the library.
+ 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.
-
- After initializing curses, this variable contains the number of color
- pairs which the terminal can support. Usually the number of color
- pairs will be the product COLORS*COLORS, however this is not always
- true:
+
+ The curses library defines TRUE and FALSE to represent the values of
+ the Boolean data type.
- o terminals supporting a large number of colors are limited by the
- number of color pairs that can be represented in a signedshort
- value.
+
+ 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 cursesbool.
-
- This variable holds the number of milliseconds to wait after reading an
- escape character, to distinguish between an individual escape character
- entered on the keyboard from escape sequences sent by cursor- and
- function-keys (see curses(3x)).
+
+ 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 graphemecluster (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).
-
- This variable holds the number of columns used by the curses library
- when converting a tab character to spaces as it adds the tab to a
- window (see curs_addch(3x).
+
+ The library records updates to the terminal screen in a window named
+ curscr. This object is referred to as the "physical screen" in
+ curs_refresh(3x) and curs_outopts(3x).
-
- This implementation of curses uses a special window curscr to record
- its updates to the terminal screen.
+ ncurses collects pending updates to the terminal screen in a window
+ 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.
- This is referred to as the "physical screen" in the curs_refresh(3x)
- and curs_outopts(3x) manual pages.
+ 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.
-
+ Once curses is initialized, COLOR_PAIRS contains the number of color
+ pairs supported by the terminal; see curs_color(3x).
+
- This is referred to as the "virtual screen" in the curs_kernel(3x),
- curs_refresh(3x) and curs_outopts(3x) manual pages.
+
+ 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.
-
- Upon initializing curses, a default window called stdscr, which is the
- size of the terminal screen, is created. Many curses functions use
- this window.
+
+ 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.
+
+
+
- The curses library is initialized using either initscr(3x), or
- newterm(3x).
+ Either initscr(3x) or newterm(3x) initializes curses.
- If curses is configured to use separate curses/terminfo libraries, most
- of these variables reside in the curses library.
+ If ncurses is configured to provide separate curses and terminfo
+ libraries, most of these variables reside in the curses library.
- TABSIZE is a feature of SVr4 curses which is not documented by X/Open
- curses.
+ 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(3x) and wrefresh(3x).
+
+ 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(3x). When the
+ update of newscr is complete, curses modifies curscr to match newscr.
- o In SVr4 curses, TABSIZE is initially set from the terminal
- description's init_tabs capability. After that, it can be altered
- by the applications using SVr4 curses.
+ TABSIZE is a feature of SVr4 curses.
- SVr4 curses uses the current value of TABSIZE to compute the
- position of tabstops for updating both the virtual screen with
- addch(3x) as well as the physical screen with mvcur(3x).
+ 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 This implementation uses the current value of TABSIZE only for
- updating the virtual screen. It uses the terminal description's it
- (init_tabs) capability for computing hardware tabs (i.e., tab stops
- on the physical screen).
+ 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 Other implementations differ. For instance, NetBSD curses allows
- TABSIZE to be set through an environment variable. This
- implementation does not.
+ oncurses 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).
- NetBSD curses does not support hardware tabs; it uses the init_tabs
- capability and the TABSIZE variable only for updating the virtual
+ 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 an extension in AIX curses:
+ ESCDELAY is a feature of AIX curses.
- o In AIX, the units for ESCDELAY are fifths of a millisecond.
+ o In AIX, the units for ESCDELAY are fifths of milliseconds.
- o The default value for AIX's ESCDELAY is 0.1 seconds.
+ o The default value for AIX's ESCDELAY equals 0.1 seconds.
- o AIX also enforces a limit of 10,000 seconds for ESCDELAY; this
- implementation currently has no upper limit.
+ o AIX also enforces a limit of 10,000 seconds for ESCDELAY; ncurses
+ does not enforce any upper limit.
- This implementation has long used ESCDELAY with units of milliseconds,
- making it impossible to be completely compatible with AIX. Likewise,
- most users have either decided to override the value, or rely upon its
- default value.
+ 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.