* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_variables.3x,v 1.23 2023/09/16 23:37:03 tom Exp @
+ * @Id: curs_variables.3x,v 1.31 2023/10/01 22:36:35 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
-<TITLE>curs_variables 3x 2023-09-16 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_variables 3x 2023-10-01 ncurses 6.4 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">
</HEAD>
<BODY>
-<H1 class="no-header">curs_variables 3x 2023-09-16 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_variables 3x 2023-10-01 ncurses 6.4 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
- <STRONG>COLORS</STRONG>, <STRONG>COLOR_PAIRS</STRONG>, <STRONG>COLS</STRONG>, <STRONG>ESCDELAY</STRONG>, <STRONG>LINES</STRONG>, <STRONG>TABSIZE</STRONG>, <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>,
- <STRONG>stdscr</STRONG> - <EM>curses</EM> global variables
+ <EM>bool</EM>, <EM>chtype</EM>, <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>, <EM>attr</EM><STRONG>_</STRONG><EM>t</EM>, <EM>WINDOW</EM>, <STRONG>TRUE</STRONG>, <STRONG>FALSE</STRONG>, <STRONG>ERR</STRONG>, <STRONG>OK</STRONG>, <STRONG>COLORS</STRONG>,
+ <STRONG>COLOR_PAIRS</STRONG>, <STRONG>COLS</STRONG>, <STRONG>ESCDELAY</STRONG>, <STRONG>LINES</STRONG>, <STRONG>TABSIZE</STRONG>, <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>, <STRONG>stdscr</STRONG> -
+ <EM>curses</EM> data types, constants, and global variables
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
+ <EM>/*</EM> <EM>data</EM> <EM>types</EM> <EM>*/</EM>
+ <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>bool;</STRONG>
+ <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>chtype;</STRONG>
+ <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>cchar_t;</STRONG>
+ <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>attr_t;</STRONG>
+ <STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>WINDOW;</STRONG>
+
+ <EM>/*</EM> <EM>constants</EM> <EM>*/</EM>
+ <STRONG>const</STRONG> <STRONG>bool</STRONG> <STRONG>TRUE;</STRONG>
+ <STRONG>const</STRONG> <STRONG>bool</STRONG> <STRONG>FALSE;</STRONG>
+
+ <STRONG>const</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>ERR;</STRONG>
+ <STRONG>const</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>OK;</STRONG>
+
+ <EM>/*</EM> <EM>variables</EM> <EM>*/</EM>
<STRONG>int</STRONG> <STRONG>COLOR_PAIRS;</STRONG>
<STRONG>int</STRONG> <STRONG>COLORS;</STRONG>
<STRONG>int</STRONG> <STRONG>COLS;</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
- This page summarizes variables provided by the <STRONG>curses</STRONG> library. A more
- complete description is given in the <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> manual page.
+ This page summarizes data types, constants, and variables provided by
+ the <EM>curses</EM> library. Locate further discussion in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.
+
+ Depending on <EM>ncurses</EM>'s build-time configuration, the variables may
+ instead be macros (see <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> and <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>) 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.
+
+
+</PRE><H3><a name="h3-bool_-TRUE_-FALSE">bool, TRUE, FALSE</a></H3><PRE>
+ X/Open Issue 4 <EM>curses</EM> (1996) preceded the ISO C99 and ISO C++98
+ standards, each of which also defined a Boolean data type. The <EM>curses</EM>
+ library requires an integral type <EM>bool</EM> and constants <STRONG>TRUE</STRONG> and <STRONG>FALSE</STRONG> to
+ store its two possible values.
+
+
+</PRE><H3><a name="h3-ERR_-OK">ERR, OK</a></H3><PRE>
+ <EM>curses</EM> and <EM>terminfo</EM> routines frequently return these constant integral
+ values indicating failure and success, respectively.
+
- Depending on the configuration, these may be actual variables, or
- macros (see <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> and <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>) which provide read-
- only access to <EM>curses</EM>'s state. In either case, applications should
- treat them as read-only to avoid confusing the library.
+</PRE><H3><a name="h3-chtype">chtype</a></H3><PRE>
+ The <EM>chtype</EM> integral type combines a ("narrow", 8-bit) character with
+ attributes encoding the character's <EM>rendition</EM>, such as the styling of
+ its typeface and/or foreground and background colors. See, for
+ example, <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">attron(3x)</A></STRONG>, and <STRONG><A HREF="curs_inch.3x.html">inch(3x)</A></STRONG>.
+
+
+</PRE><H3><a name="h3-cchar_t_-attr_t">cchar_t, attr_t</a></H3><PRE>
+ <EM>chtype</EM> is too small for the standard C library's wide-character type,
+ <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>. <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> is a type that can accommodate an <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> and enough
+ wide characters to store what Unicode terms a <EM>grapheme</EM> <EM>cluster</EM> (a
+ "user-perceived character" [UAX #29], which may nevertheless require
+ several character encoding units to represent). <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> is an integral
+ type storing "wide" attributes that apply to <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>s. See, for
+ example, <STRONG><A HREF="curs_add_wch.3x.html">add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">attr_on(3x)</A></STRONG>, and <STRONG><A HREF="curs_in_wch.3x.html">in_wch(3x)</A></STRONG>.
</PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE>
- 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 <STRONG>COLORS</STRONG>*<STRONG>COLORS</STRONG>, however this is not always
- true:
+ Once <EM>curses</EM> is initialized, <STRONG>COLOR_PAIRS</STRONG> contains the number of color
+ pairs supported by the terminal. Often, its value is the product
+ <STRONG>COLORS</STRONG> x <STRONG>COLORS</STRONG>, but this is not always true.
- <STRONG>o</STRONG> a few terminals use HLS colors, which do not follow this rule
+ <STRONG>o</STRONG> A few terminals use HLS colors, ignoring this rule; and
<STRONG>o</STRONG> terminals supporting a large number of colors are limited by the
- number of color pairs that can be represented in a <EM>signed</EM> <EM>short</EM>
- value.
+ number of color pairs that a <EM>signed</EM> <EM>short</EM> value can represent.
</PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE>
- After initializing curses, this variable contains the number of colors
- which the terminal can support.
+ Once <EM>curses</EM> is initialized, <STRONG>COLORS</STRONG> contains the number of colors
+ supported by the terminal.
</PRE><H3><a name="h3-COLS">COLS</a></H3><PRE>
- After initializing curses, this variable contains the width of the
- screen, i.e., the number of columns.
+ Once <EM>curses</EM> is initialized, <STRONG>COLS</STRONG> contains the screen's width in
+ character cells; that is, the number of columns.
</PRE><H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE>
- 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 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>).
+ For <EM>curses</EM> 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.
+ <STRONG>ESCDELAY</STRONG> stores this interval in milliseconds.
</PRE><H3><a name="h3-LINES">LINES</a></H3><PRE>
- After initializing curses, this variable contains the height of the
- screen, i.e., the number of lines.
+ Once <EM>curses</EM> is initialized, <STRONG>LINES</STRONG> contains the screen's height in
+ character cells; that is, the number of lines.
</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE>
- This variable holds the number of columns used by the <EM>curses</EM> library
- when converting a tab character to spaces as it adds the tab to a
- window (see <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>.
+ The <EM>curses</EM> library converts a tab character to this number of spaces as
+ it adds a tab to a window; see <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>.
-</PRE><H3><a name="h3-
The-Current-Screen">The Current Screen</a></H3><PRE>
- This implementation of curses uses a special window <STRONG>curscr</STRONG> to record
- its updates to the terminal screen.
+</PRE><H3><a name="h3-
curscr">curscr</a></H3><PRE>
+ <EM>curses</EM> records updates to the terminal screen in a <EM>WINDOW</EM> structure
+ named <STRONG>curscr</STRONG>.
- This
is referred to as the "physical screen" in the <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
- and <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> manual pages.
+ This
object is referred to as the "physical screen" in <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
+ and <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>.
-</PRE><H3><a name="h3-
The-New-Screen">The New Screen</a></H3><PRE>
- This implementation of curses uses a special window <STRONG>newscr</STRONG> to hold
- updates to the terminal screen before applying them to <STRONG>curscr</STRONG>.
+</PRE><H3><a name="h3-
newscr">newscr</a></H3><PRE>
+ <EM>ncurses</EM> collects pending updates to the terminal screen in a <EM>WINDOW</EM>
+ structure named <STRONG>newscr</STRONG>.
- This is referred to as the "virtual screen" in the <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,
- <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> and <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> manual pages.
+ This object is referred to as the "virtual screen" in the
+ <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, and <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>. When the
+ screen is refreshed, <EM>curses</EM> determines a minimal set of updates using
+ the terminal's capabilities to make <STRONG>curscr</STRONG> look like <STRONG>newscr</STRONG>.
-</PRE><H3><a name="h3-The-Standard-Screen">The Standard Screen</a></H3><PRE>
- Upon initializing curses, a default window called <STRONG>stdscr</STRONG>, which is the
- size of the terminal screen, is created. Many curses functions use
- this window.
+</PRE><H3><a name="h3-stdscr">stdscr</a></H3><PRE>
+ Once <EM>curses</EM> is initialized, it creates a <EM>WINDOW</EM> structure named <STRONG>stdscr</STRONG>.
+ 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
+ <EM>curses</EM> functions use this window.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- The curses library is initialized using either <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>, or
- <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>.
+ Either <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> initializes <EM>curses</EM>.
- If <STRONG>curses</STRONG> is configured to use separate curses/terminfo libraries, most
- of these variables reside in the curses library.
+ If <EM>ncurses</EM> is configured to provide separate <EM>curses</EM> and <EM>terminfo</EM>
+ libraries, most of these variables reside in the <EM>curses</EM> library.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- <STRONG>TABSIZE</STRONG> is a feature of SVr4 curses which is not documented by X/Open
- curses.
-
- <STRONG>o</STRONG> In SVr4 curses, <STRONG>TABSIZE</STRONG> is initially set from the terminal
- description's <STRONG>init_tabs</STRONG> capability. After that, it can be altered
- by the applications using SVr4 curses.
-
- SVr4 curses uses the current value of <STRONG>TABSIZE</STRONG> to compute the
- position of tabstops for updating both the virtual screen with
- <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG> as well as the physical screen with <STRONG><A HREF="curs_terminfo.3x.html">mvcur(3x)</A></STRONG>.
-
- <STRONG>o</STRONG> This implementation uses the current value of <STRONG>TABSIZE</STRONG> only for
- updating the virtual screen. It uses the terminal description's <STRONG>it</STRONG>
- (<STRONG>init_tabs</STRONG>) capability for computing hardware tabs (i.e., tab stops
- on the physical screen).
-
- <STRONG>o</STRONG> Other implementations differ. For instance, NetBSD curses allows
- <STRONG>TABSIZE</STRONG> to be set through an environment variable. This
- implementation does not.
-
- NetBSD curses does not support hardware tabs; it uses the <STRONG>init_tabs</STRONG>
- capability and the <STRONG>TABSIZE</STRONG> variable only for updating the virtual
+ The X/Open Curses standard documents all of the foregoing types and
+ symbols except for <STRONG>newscr</STRONG>, <STRONG>TABSIZE</STRONG>, and <STRONG>ESCDELAY</STRONG>.
+
+ X/Open Curses describes <STRONG>curscr</STRONG> 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 <STRONG><A HREF="curs_outopts.3x.html">clearok(3x)</A></STRONG> and <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>.
+
+ <STRONG>newscr</STRONG> is a feature of SVr4 <EM>curses</EM>. When refreshing the screen, this
+ window is used as a working area for combining the standard screen
+ <STRONG>stdscr</STRONG> with any other windows which the application may have created
+ with <STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>. When the updated <STRONG>newscr</STRONG> is complete, <EM>curses</EM> updates
+ <STRONG>curscr</STRONG> to match <STRONG>newscr</STRONG>.
+
+ <STRONG>TABSIZE</STRONG> is a feature of SVr4 <EM>curses</EM>.
+
+ <STRONG>o</STRONG> SVr4 initially sets <STRONG>TABSIZE</STRONG> from the terminal description's
+ <STRONG>init_tabs</STRONG> capability. After that, it can be altered by
+ applications using SVr4 <EM>curses</EM>.
+
+ <STRONG>o</STRONG> SVr4 <EM>curses</EM> uses the value of <STRONG>TABSIZE</STRONG> to compute the position of
+ tab stops when updating both the virtual screen with <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG> and
+ the physical screen with <STRONG><A HREF="curs_terminfo.3x.html">mvcur(3x)</A></STRONG>.
+
+ <STRONG>o</STRONG> <EM>ncurses</EM> uses the value of <STRONG>TABSIZE</STRONG> only to update the virtual
+ screen. It uses the terminal description's "<STRONG>it</STRONG>" (<STRONG>init_tabs</STRONG>)
+ capability for computing hardware tabs (that is, tab stops on the
+ physical screen).
+
+ <STRONG>o</STRONG> Other implementations differ. For instance, NetBSD <EM>curses</EM> allows
+ <STRONG>TABSIZE</STRONG> to be set through an environment variable. <EM>ncurses</EM> does
+ not.
+
+ NetBSD <EM>curses</EM> does not support hardware tabs; it uses the <STRONG>init_tabs</STRONG>
+ capability and the <STRONG>TABSIZE</STRONG> variable only for updating the virtual
screen.
- <STRONG>ESCDELAY</STRONG> is an extension in AIX curses:
+ <STRONG>ESCDELAY</STRONG> is a feature of AIX <EM>curses</EM>.
- <STRONG>o</STRONG> In AIX, the units for <STRONG>ESCDELAY</STRONG> are <EM>fifths</EM> of a millisecond.
+ <STRONG>o</STRONG> In AIX, the units for <STRONG>ESCDELAY</STRONG> are <EM>fifths</EM> of milliseconds.
- <STRONG>o</STRONG> The default value for AIX's <STRONG>ESCDELAY</STRONG> is 0.1 seconds.
+ <STRONG>o</STRONG> The default value for AIX's <STRONG>ESCDELAY</STRONG> equals 0.1 seconds.
- <STRONG>o</STRONG> AIX also enforces a limit of 10,000 seconds for <STRONG>ESCDELAY</STRONG>; this
- implementation currently has no upper limit.
+ <STRONG>o</STRONG> AIX also enforces a limit of 10,000 seconds for <STRONG>ESCDELAY</STRONG>; <EM>ncurses</EM>
+ does not enforce any upper limit.
- This implementation has long used <STRONG>ESCDELAY</STRONG> 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.
+ <EM>ncurses</EM> has long used <STRONG>ESCDELAY</STRONG> 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.
</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
<STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>,
- <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.
+ <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>
+
+ [UAX #29] "Unicode Standard Annex #29: Unicode Text Segmentation";
+ <https://unicode.org/reports/tr29/>
-ncurses 6.4 2023-
09-16 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
+ncurses 6.4 2023-
10-01 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
+<li><a href="#h3-bool_-TRUE_-FALSE">bool, TRUE, FALSE</a></li>
+<li><a href="#h3-ERR_-OK">ERR, OK</a></li>
+<li><a href="#h3-chtype">chtype</a></li>
+<li><a href="#h3-cchar_t_-attr_t">cchar_t, attr_t</a></li>
<li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li>
<li><a href="#h3-COLORS">COLORS</a></li>
<li><a href="#h3-COLS">COLS</a></li>
<li><a href="#h3-ESCDELAY">ESCDELAY</a></li>
<li><a href="#h3-LINES">LINES</a></li>
<li><a href="#h3-TABSIZE">TABSIZE</a></li>
-<li><a href="#h3-The-Current-Screen">The Current Screen</a></li>
-<li><a href="#h3-The-New-Screen">The New Screen</a></li>
-<li><a href="#h3-The-Standard-Screen">The Standard Screen</a></li>
+<li><a href="#h3-curscr">curscr</a></li>
+<li><a href="#h3-newscr">newscr</a></li>
+<li><a href="#h3-stdscr">stdscr</a></li>
</ul>
</li>
<li><a href="#h2-NOTES">NOTES</a></li>
projects / ncurses.git / blobdiff