X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_variables.3x.html;h=e193c6001435dd2a389403bc76beaaf733c80b95;hb=122d3739b3c11c83decc625d53f26fff6e825710;hp=7f8e1f3aac9c8597867f04e805a8900346825126;hpb=47d2fb4537d9ad5bb14f4810561a327930ca4280;p=ncurses.git diff --git a/doc/html/man/curs_variables.3x.html b/doc/html/man/curs_variables.3x.html index 7f8e1f3a..e193c600 100644 --- a/doc/html/man/curs_variables.3x.html +++ b/doc/html/man/curs_variables.3x.html @@ -1,6 +1,6 @@ -
--curs_variables(3x) curs_variables(3x) +curs_variables(3x) Library calls curs_variables(3x)
- COLORS, COLOR_PAIRS, COLS, ESCDELAY, LINES, TABSIZE, curscr, newscr, - stdscr - curses global variables + 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
#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; @@ -66,133 +82,180 @@
- 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 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. + + +
+ 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. + + +
+ curses and terminfo routines frequently return these constant integral + values indicating failure and success, respectively. - 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. + +
+ 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 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).
- 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: + 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, which do not follow this rule + 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 can be represented in a signed short - value. + number of color pairs that a signed short value can represent.
- After initializing curses, this variable contains the number of colors - which the terminal can support. + Once curses is initialized, COLORS contains the number of colors + supported by the terminal.
- After initializing curses, this variable contains the width of the - screen, i.e., the number of columns. + Once curses is initialized, COLS contains the screen's width in + character cells; that is, the number of columns.
- 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 func- - tion-keys (see curses(3x)). + 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.
- After initializing curses, this variable contains the height of the - screen, i.e., the number of lines. + Once curses is initialized, LINES contains the screen's height in + character cells; that is, the number of lines.
- 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 win- - dow (see curs_addch(3x). + The curses library converts a tab character to this number of spaces as + it adds a tab to a window; see curs_addch(3x). -
- This implementation of curses uses a special window curscr to record - its updates to the terminal screen. +
+ curses records updates to the terminal screen in a WINDOW structure + named curscr. - This is referred to as the "physical screen" in the curs_refresh(3x) - and curs_outopts(3x) manual pages. + 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 newscr to hold up- - dates to the terminal screen before applying them to curscr. +
+ ncurses collects pending updates to the terminal screen in a WINDOW + structure named newscr. - This is referred to as the "virtual screen" in the curs_kernel(3x), - curs_refresh(3x) and curs_outopts(3x) manual pages. + 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. -
- Upon initializing curses, a default window called stdscr, which is the - size of the terminal screen, is created. Many curses functions use - this window. +
+ 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.
- 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. - - o In SVr4 curses, TABSIZE is initially set from the terminal descrip- - tion's init_tabs capability. After that, it can be altered by the - applications using SVr4 curses. - - SVr4 curses uses the current value of TABSIZE to compute the posi- - tion of tabstops for updating both the virtual screen with add- - ch(3x) as well as the physical screen with mvcur(3x). - - o This implementation uses the current value of TABSIZE only for up- - dating 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 Other implementations differ. For instance, NetBSD curses allows - TABSIZE to be set through an environment variable. This implemen- - tation does not. - - NetBSD curses does not support hardware tabs; it uses the init_tabs - capability and the TABSIZE variable only for updating the virtual + 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 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 im- - plementation 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.
curses(3x), curs_opaque(3x), curs_terminfo(3x), curs_threads(3x), - term_variables(3x), terminfo(5). + term_variables(3x), terminfo(5) + + [UAX #29] "Unicode Standard Annex #29: Unicode Text Segmentation"; + <https://unicode.org/reports/tr29/> - curs_variables(3x) +ncurses 6.4 2023-10-07 curs_variables(3x)