* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_variables.3x,v 1.35 2023/12/16 21:05:52 tom Exp @
+ * @Id: curs_variables.3x,v 1.40 2023/12/23 23:10:13 tom Exp @
+ * SVID 4, Volume 3, p. 408
-->
<!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-12-16 ncurses 6.4 Library calls</TITLE>
+<TITLE>curs_variables 3x 2023-12-23 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-12-16 ncurses 6.4 Library calls</H1>
+<H1 class="no-header">curs_variables 3x 2023-12-23 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>
- <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
+ <EM>bool</EM>, <EM>chtype</EM>, <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>, <EM>attr</EM><STRONG>_</STRONG><EM>t</EM>, <EM>SCREEN</EM>, <EM>WINDOW</EM>, <STRONG>TRUE</STRONG>, <STRONG>FALSE</STRONG>, <STRONG>ERR</STRONG>, <STRONG>OK</STRONG>,
+ <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>, <STRONG>stdscr</STRONG>, <STRONG>COLORS</STRONG>, <STRONG>COLOR_PAIRS</STRONG>, <STRONG>COLS</STRONG>, <STRONG>LINES</STRONG>, <STRONG>ESCDELAY</STRONG>,
+ <STRONG>TABSIZE</STRONG> - <EM>curses</EM> data types, constants, and global variables
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<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>SCREEN;</STRONG>
<STRONG>typedef</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>WINDOW;</STRONG>
<EM>/*</EM> <EM>constants</EM> <EM>*/</EM>
<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>COLOR_PAIRS;</STRONG>
<STRONG>int</STRONG> <STRONG>COLS;</STRONG>
<STRONG>int</STRONG> <STRONG>LINES;</STRONG>
<STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>curscr;</STRONG>
<STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>stdscr;</STRONG>
+
<EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
<STRONG>int</STRONG> <STRONG>ESCDELAY;</STRONG>
<STRONG>int</STRONG> <STRONG>TABSIZE;</STRONG>
library.
-</PRE><H3><a name="h3-bool_-TRUE_-FALSE"><EM>bool,</EM> 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><H2><a name="h2-CONSTANTS">CONSTANTS</a></H2><PRE>
+
+</PRE><H3><a name="h3-TRUE_-FALSE">TRUE, FALSE</a></H3><PRE>
+ The <EM>curses</EM> library defines <STRONG>TRUE</STRONG> and <STRONG>FALSE</STRONG> to represent the values of
+ the Boolean data type.
</PRE><H3><a name="h3-ERR_-OK">ERR, OK</a></H3><PRE>
values indicating failure and success, respectively.
+</PRE><H2><a name="h2-PREDEFINED-TYPES">PREDEFINED TYPES</a></H2><PRE>
+
+</PRE><H3><a name="h3-bool"><EM>bool</EM></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>.
+
+ <STRONG>ncurses</STRONG>' configure script attempts to discover the data type used by
+ the system's C and C++ compilers, to reuse for the <EM>curses</EM> <EM>bool</EM>.
+
+
</PRE><H3><a name="h3-chtype"><EM>chtype</EM></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
+ 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"><EM>cchar_t,</EM> 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
+ <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>
- 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.
+</PRE><H3><a name="h3-SCREEN"><EM>SCREEN</EM></a></H3><PRE>
+ <EM>curses</EM> manages a terminal device with this structure type; see
+ <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>.
+
- <STRONG>o</STRONG> A few terminals use HLS colors, ignoring this rule; and
+</PRE><H3><a name="h3-WINDOW"><EM>WINDOW</EM></a></H3><PRE>
+ <EM>curses</EM> represents rectangular portions of the terminal screen with the
+ <EM>WINDOW</EM> structure type; see subsection "Overview" of <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>.
- <STRONG>o</STRONG> terminals supporting a large number of colors are limited by the
- number of color pairs that a <EM>signed</EM> <EM>short</EM> value can represent.
+
+</PRE><H2><a name="h2-VARIABLES">VARIABLES</a></H2><PRE>
+
+</PRE><H3><a name="h3-curscr_-stdscr_-newscr">curscr, stdscr, newscr</a></H3><PRE>
+ The library records updates to the terminal screen in a window named
+ <STRONG>curscr</STRONG>. 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>.
+
+ <EM>ncurses</EM> collects pending updates to the terminal screen in a window
+ named <STRONG>newscr</STRONG>. 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>.
+
+ Once <EM>curses</EM> is initialized, it creates a window 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><H3><a name="h3-COLORS">COLORS</a></H3><PRE>
- Once <EM>curses</EM> is initialized, <STRONG>COLORS</STRONG> contains the number of colors
- supported by the terminal.
+ Once <EM>curses</EM> is initialized, <STRONG>COLORS</STRONG> contains the number of colors
+ supported by the terminal; see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>.
-</PRE><H3><a name="h3-COLS">COLS</a></H3><PRE>
- 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-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE>
+ Once <EM>curses</EM> is initialized, <STRONG>COLOR_PAIRS</STRONG> contains the number of color
+ pairs supported by the terminal; see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>.
+
+
+</PRE><H3><a name="h3-COLS_-LINES">COLS, LINES</a></H3><PRE>
+ Once <EM>curses</EM> is initialized, <STRONG>COLS</STRONG> and <STRONG>LINES</STRONG> contain the screen's width
+ and height in character cells, respectively; that is, the number of
+ columns and lines.
</PRE><H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE>
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
+ 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.
+ 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>
- 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>
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-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 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-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 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-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>
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 <EM>ncurses</EM> is configured to provide separate <EM>curses</EM> and <EM>terminfo</EM>
+ 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>
- The X/Open Curses standard documents all of the foregoing types and
+ 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".
+ X/Open Curses describes <STRONG>curscr</STRONG> 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 <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>newscr</STRONG> is a feature of SVr4 <EM>curses</EM>. When refreshing the screen, it is
+ used as a working area for combining the standard window <STRONG>stdscr</STRONG> with
+ any others the application may have created with <STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>. When the
+ update of <STRONG>newscr</STRONG> is complete, <EM>curses</EM> modifies <STRONG>curscr</STRONG> to match <STRONG>newscr</STRONG>.
<STRONG>TABSIZE</STRONG> is a feature of SVr4 <EM>curses</EM>.
</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="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_color.3x.html">curs_color(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>
[UAX #29] "Unicode Standard Annex #29: Unicode Text Segmentation";
<https://unicode.org/reports/tr29/>
-ncurses 6.4 2023-12-16 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
+ncurses 6.4 2023-12-23 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
-<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
+<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
+<li><a href="#h2-CONSTANTS">CONSTANTS</a>
<ul>
-<li><a href="#h3-bool_-TRUE_-FALSE">bool, TRUE, FALSE</a></li>
+<li><a href="#h3-TRUE_-FALSE">TRUE, FALSE</a></li>
<li><a href="#h3-ERR_-OK">ERR, OK</a></li>
+</ul>
+</li>
+<li><a href="#h2-PREDEFINED-TYPES">PREDEFINED TYPES</a>
+<ul>
+<li><a href="#h3-bool">bool</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-SCREEN">SCREEN</a></li>
+<li><a href="#h3-WINDOW">WINDOW</a></li>
+</ul>
+</li>
+<li><a href="#h2-VARIABLES">VARIABLES</a>
+<ul>
+<li><a href="#h3-curscr_-stdscr_-newscr">curscr, stdscr, newscr</a></li>
<li><a href="#h3-COLORS">COLORS</a></li>
-<li><a href="#h3-COLS">COLS</a></li>
+<li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li>
+<li><a href="#h3-COLS_-LINES">COLS, LINES</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-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>