.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_variables.3x,v 1.23 2023/09/16 23:37:03 tom Exp $
-.TH curs_variables 3X 2023-09-16 "ncurses 6.4" "Library calls"
+.\" $Id: curs_variables.3x,v 1.31 2023/10/01 22:36:35 tom Exp $
+.TH curs_variables 3X 2023-10-01 "ncurses 6.4" "Library calls"
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
.el .ds '' ''
+.ie \n(.g .ds : \:
+.el .ds : \" empty
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
.ds n 5
.SH NAME
+\fI\%bool\fP,
+\fI\%chtype\fP,
+\fI\%cchar_t\fP,
+\fI\%attr_t\fP,
+\fI\%WINDOW\fP,
+\fB\%TRUE\fP,
+\fB\%FALSE\fP,
+\fB\%ERR\fP,
+\fB\%OK\fP,
\fB\%COLORS\fP,
\fB\%COLOR_PAIRS\fP,
\fB\%COLS\fP,
\fB\%curscr\fP,
\fB\%newscr\fP,
\fB\%stdscr\fP \-
-\fIcurses\fR global variables
+\fIcurses\fR data types, constants, and global variables
.SH SYNOPSIS
.nf
\fB#include <curses.h>\fP
.PP
+\fI/* data types */\fP
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP bool;\fP
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP chtype;\fP
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP cchar_t;\fP
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP attr_t;\fP
+\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP WINDOW;\fP
+.PP
+\fI/* constants */\fP
+\fBconst bool TRUE;\fP
+\fBconst bool FALSE;\fP
+.PP
+\fBconst \fI/*\fP .\|.\|. \fI*/\fP ERR;\fP
+\fBconst \fI/*\fP .\|.\|. \fI*/\fP OK;\fP
+.PP
+\fI/* variables */\fP
\fBint COLOR_PAIRS;\fP
-.br
\fBint COLORS;\fP
-.br
\fBint COLS;\fP
-.br
\fBint ESCDELAY;\fP
-.br
\fBint LINES;\fP
-.br
\fBint TABSIZE;\fP
-.br
\fBWINDOW * curscr;\fP
-.br
\fBWINDOW * newscr;\fP
-.br
\fBWINDOW * stdscr;\fP
.fi
.SH DESCRIPTION
-This page summarizes variables provided by the \fBcurses\fP library.
-A more complete description is given in the \fBcurses\fP(3X) manual page.
+This page summarizes data types,
+constants,
+and variables provided by the \fIcurses\fP library.
+Locate further discussion in \fB\%curses\fP(3X).
.PP
-Depending on the configuration, these may be actual variables,
-or macros (see \fBcurs_threads\fP(3X) and \fBcurs_opaque\fP(3X))
-which provide read-only access to \fIcurses\fP's state.
-In either case, applications should treat them as read-only to avoid
+Depending on \fIncurses\fP's build-time configuration,
+the variables may instead be
+macros (see \fB\%curs_threads\fP(3X) and \fB\%curs_opaque\fP(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.
+.SS bool, TRUE, FALSE
+X/Open Issue 4 \fIcurses\fP (1996) preceded the ISO C99 and ISO C++98
+standards,
+each of which also defined a Boolean data type.
+The \fIcurses\fP library requires an integral type \fIbool\fP and
+constants \fBTRUE\fP and \fBFALSE\fP to store its two possible values.
+.SS ERR, OK
+\fIcurses\fP and \fIterminfo\fP routines frequently return these
+constant integral values indicating failure and success,
+respectively.
+.SS chtype
+The \fI\%chtype\fP integral type combines a
+(\*(``narrow\*('',
+8-bit)
+character with attributes encoding the character's \fIrendition\fP,
+such as the styling of its typeface and/or foreground and background
+colors.
+See,
+for example,
+\fB\%addch\fP(3X),
+\fB\%attron\fP(3X),
+and
+\fB\%inch\fP(3X).
+.SS cchar_t, attr_t
+\fI\%chtype\fP is too small for the standard C library's wide-character
+type,
+\fIwchar_t\fP.
+\fI\%cchar_t\fP is a type that can accommodate an \fI\%attr_t\fP and
+enough wide characters to store what Unicode terms a \fIgrapheme cluster\fP
+(a \*(``user-perceived character\*('' [UAX #29],
+which may nevertheless require several character encoding units to
+represent).
+\fI\%attr_t\fP is an integral type storing \*(``wide\*('' attributes that
+apply to \fI\%cchar_t\fPs.
+See,
+for example,
+\fB\%add_wch\fP(3X),
+\fB\%attr_on\fP(3X),
+and
+\fB\%in_wch\fP(3X).
.SS COLOR_PAIRS
-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 \fBCOLORS\fP*\fBCOLORS\fP,
-however this is not always true:
+Once \fIcurses\fP is initialized,
+\fB\%COLOR_PAIRS\fP
+contains the number of color pairs supported by the terminal.
+Often,
+its value is the product \fB\%COLORS\fP \(mu \fB\%COLORS\fP,
+but this is not always true.
.bP
-a few terminals use HLS colors, which do not follow this rule
+A few terminals use HLS colors,
+ignoring this rule;
+and
.bP
terminals supporting a large number of colors are limited by the number
-of color pairs that can be represented in a \fIsigned short\fP value.
+of color pairs that a \fIsigned short\fP value can represent.
.SS COLORS
-After initializing curses, this variable contains the number of colors
-which the terminal can support.
+Once \fIcurses\fP is initialized,
+\fB\%COLORS\fP
+contains the number of colors supported by the terminal.
.SS COLS
-After initializing curses, this variable contains the width of the screen,
-i.e., the number of columns.
+Once \fIcurses\fP is initialized,
+\fB\%COLS\fP
+contains the screen's width in character cells;
+that is,
+the number of columns.
.SS ESCDELAY
-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)).
+For \fIcurses\fP 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.
+\fB\%ESCDELAY\fP
+stores this interval in milliseconds.
.SS LINES
-After initializing curses, this variable contains the height of the screen,
-i.e., the number of lines.
+Once \fIcurses\fP is initialized,
+\fB\%LINES\fP
+contains the screen's height in character cells;
+that is,
+the number of lines.
.SS TABSIZE
-This variable holds the number of columns used by the \fIcurses\fP library
-when converting a tab character to spaces as it adds the tab to a window
-(see \fBcurs_addch\fP(3X).
-.SS The Current Screen
-This implementation of curses uses a special window \fBcurscr\fP to
-record its updates to the terminal screen.
+The \fIcurses\fP library converts a tab character to this number of
+spaces as it adds a tab to a window;
+see \fB\%curs_addch\fP(3X).
+.SS curscr
+\fIcurses\fP records updates to the terminal screen in a \fI\%WINDOW\fP
+structure named \fB\%curscr\fP.
.PP
-This is referred to as the \*(``physical screen\*('' in the
-\fBcurs_refresh\fP(3X) and
-\fBcurs_outopts\fP(3X) manual pages.
-.SS The New Screen
-This implementation of curses uses a special window \fBnewscr\fP to
-hold updates to the terminal screen before applying them to \fBcurscr\fP.
+This object is referred to as the \*(``physical screen\*('' in
+\fB\%curs_refresh\fP(3X) and
+\fB\%curs_outopts\fP(3X).
+.SS newscr
+\fIncurses\fP collects pending updates to the terminal screen in a
+\fI\%WINDOW\fP structure named \fB\%newscr\fP.
.PP
-This is referred to as the \*(``virtual screen\*('' in the
-\fBcurs_kernel\fP(3X),
-\fBcurs_refresh\fP(3X) and
-\fBcurs_outopts\fP(3X) manual pages.
-.SS The Standard Screen
-Upon initializing curses,
-a default window called \fBstdscr\fP,
-which is the size of the terminal screen, is created.
-Many curses functions use this window.
+This object is referred to as the \*(``virtual screen\*('' in the
+\fB\%curs_kernel\fP(3X),
+\fB\%curs_refresh\fP(3X),
+and
+\fB\%curs_outopts\fP(3X).
+When the screen is refreshed,
+\fIcurses\fP determines a minimal set of updates using the terminal's
+capabilities to make \fB\%curscr\fP look like \fB\%newscr\fP.
+.SS stdscr
+Once \fIcurses\fP is initialized,
+it creates a \fI\%WINDOW\fP structure named \fB\%stdscr\fP.
+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 \fIcurses\fP functions use this window.
.SH NOTES
-The curses library is initialized using either \fBinitscr\fP(3X),
-or \fBnewterm\fP(3X).
+Either \fB\%initscr\fP(3X) or \fB\%newterm\fP(3X) initializes
+\fIcurses\fP.
.PP
-If \fBcurses\fP is configured to use separate curses/terminfo libraries,
-most of these variables reside in the curses library.
+If \fIncurses\fP is configured to provide separate \fIcurses\fP and
+\fIterminfo\fP libraries,
+most of these variables reside in the \fIcurses\fP library.
.SH PORTABILITY
-\fBTABSIZE\fP 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 \fB\%newscr\fP,
+\fB\%TABSIZE\fP,
+and \fB\%ESCDELAY\fP.
+.PP
+X/Open Curses describes \fB\%curscr\fP 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 \fB\%clearok\fP(3X) and \fB\%wrefresh\fP(3X).
+.PP
+\fB\%newscr\fP is a feature of SVr4 \fIcurses\fP.
+When refreshing the screen, this window is used as a working area
+for combining the standard screen \fB\%stdscr\fP with any other windows
+which the application may have created with \fB\%newwin\fP(3X).
+When the updated \fB\%newscr\fP is complete,
+\fIcurses\fP updates \fB\%curscr\fP to match \fB\%newscr\fP.
+.PP
+\fB\%TABSIZE\fP is a feature of SVr4 \fIcurses\fP.
.bP
-In SVr4 curses, \fBTABSIZE\fP is initially set from the terminal description's
-\fBinit_tabs\fP capability.
-After that, it can be altered by the applications using SVr4 curses.
-.IP
-SVr4 curses uses the current value of \fBTABSIZE\fP to
-compute the position of tabstops for updating both
-the virtual screen with \fBaddch\fP(3X) as well as
-the physical screen with \fBmvcur\fP(3X).
+SVr4 initially sets \fB\%TABSIZE\fP from the terminal description's
+\fB\%init_tabs\fP capability.
+After that,
+it can be altered by applications using SVr4 \fIcurses\fP.
.bP
-This implementation uses the current value of \fBTABSIZE\fP only for
-updating the virtual screen.
-It uses the terminal description's \fBit\fP (\fBinit_tabs\fP) capability for
-computing hardware tabs (i.e., tab stops on the physical screen).
+SVr4 \fIcurses\fP uses the value of \fB\%TABSIZE\fP to compute the
+position of tab stops when updating both
+the virtual screen with \fB\%addch\fP(3X) and
+the physical screen with \fB\%mvcur\fP(3X).
+.bP
+\fIncurses\fP uses the value of \fB\%TABSIZE\fP only to update the
+virtual screen.
+It uses the terminal description's \*(``\fBit\fP\*(''
+(\fB\%init_tabs\fP) capability for computing hardware tabs
+(that is,
+tab stops on the physical screen).
.bP
Other implementations differ.
-For instance, NetBSD curses allows \fBTABSIZE\fP to be set through
-an environment variable.
-This implementation does not.
+For instance,
+NetBSD \fIcurses\fP allows \fB\%TABSIZE\fP to be set through an
+environment variable.
+\fIncurses\fP does not.
.IP
-NetBSD curses does not support hardware tabs;
-it uses the \fBinit_tabs\fP capability and the \fBTABSIZE\fP variable
-only for updating the virtual screen.
+NetBSD \fIcurses\fP does not support hardware tabs;
+it uses the \fB\%init_tabs\fP capability and the \fB\%TABSIZE\fP
+variable only for updating the virtual screen.
.PP
-\fBESCDELAY\fP is an extension in AIX curses:
+\fB\%ESCDELAY\fP is a feature of AIX \fIcurses\fP.
.bP
-In AIX, the units for \fBESCDELAY\fP are \fIfifths\fP of a millisecond.
+In AIX,
+the units for \fB\%ESCDELAY\fP are \fIfifths\fP of milliseconds.
.bP
-The default value for AIX's \fBESCDELAY\fP is 0.1 seconds.
+The default value for AIX's \fB\%ESCDELAY\fP equals 0.1 seconds.
.bP
-AIX also enforces a limit of 10,000 seconds for \fBESCDELAY\fP;
-this implementation currently has no upper limit.
+AIX also enforces a limit of 10,000 seconds for \fB\%ESCDELAY\fP;
+\fIncurses\fP does not enforce any upper limit.
.PP
-This implementation has long used \fBESCDELAY\fP with units of milliseconds,
+\fIncurses\fP has long used \fB\%ESCDELAY\fP 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.
+Consequently,
+most users have decided either to override the value,
+or to rely upon its default.
.SH SEE ALSO
-\fBcurses\fP(3X),
-\fBcurs_opaque\fP(3X),
-\fBcurs_terminfo\fP(3X),
-\fBcurs_threads\fP(3X),
-\fBterm_variables\fP(3X),
-\fBterminfo\fP(\*n).
+\fB\%curses\fP(3X),
+\fB\%curs_opaque\fP(3X),
+\fB\%curs_terminfo\fP(3X),
+\fB\%curs_threads\fP(3X),
+\fB\%term_variables\fP(3X),
+\fB\%terminfo\fP(\*n)
+.PP
+[UAX #29] \*(``Unicode Standard Annex #29: Unicode Text
+Segmentation\*('';
+\%<https://\*:unicode\*:.org/\*:reports/\*:tr29/>
projects / ncurses.git / blobdiff