| <!-- |
| **************************************************************************** |
| * Copyright 2018-2023,2024 Thomas E. Dickey * |
| * Copyright 2010-2015,2017 Free Software Foundation, Inc. * |
| * * |
| * Permission is hereby granted, free of charge, to any person obtaining a * |
| * copy of this software and associated documentation files (the * |
| * "Software"), to deal in the Software without restriction, including * |
| * without limitation the rights to use, copy, modify, merge, publish, * |
| * distribute, distribute with modifications, sublicense, and/or sell * |
| * copies of the Software, and to permit persons to whom the Software is * |
| * furnished to do so, subject to the following conditions: * |
| * * |
| * The above copyright notice and this permission notice shall be included * |
| * in all copies or substantial portions of the Software. * |
| * * |
| * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * |
| * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * |
| * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * |
| * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * |
| * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * |
| * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * |
| * THE USE OR OTHER DEALINGS IN THE SOFTWARE. * |
| * * |
| * Except as contained in this notice, the name(s) of the above copyright * |
| * holders shall not be used in advertising or otherwise to promote the * |
| * sale, use or other dealings in this Software without prior written * |
| * authorization. * |
| **************************************************************************** |
| * @Id: curs_variables.3x,v 1.47 2024/04/13 22:37: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 2024-04-13 ncurses 6.5 Library calls</TITLE> |
| <link rel="author" href="mailto:bug-ncurses@gnu.org"> |
| |
| </HEAD> |
| <BODY> |
| <H1 class="no-header">curs_variables 3x 2024-04-13 ncurses 6.5 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>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>#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>SCREEN;</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>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> |
| <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>newscr;</STRONG> |
| |
| |
| </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> |
| 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><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> |
| <EM>curses</EM> and <EM>terminfo</EM> routines frequently return these constant integral |
| 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 |
| 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 |
| 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-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>. |
| |
| |
| </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>. |
| |
| |
| </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; see <STRONG><A HREF="curs_color.3x.html">curs_color(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; 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 the ESC character resulting from a user's |
| press of the "Escape" key on the input device from one beginning an |
| <EM>escape</EM> <EM>sequence</EM> (as commonly produced by function keys), it waits after |
| the escape character to see if further characters are available on the |
| input stream within a short interval. <STRONG>ESCDELAY</STRONG> stores this interval in |
| milliseconds. |
| |
| If <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> is disabled for the <EM>curses</EM> window receiving input, a |
| program must disambiguate escape sequences itself. |
| |
| |
| </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><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>tinfo</EM> |
| libraries, most of these variables reside in the former. |
| |
| |
| </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> |
| 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"; |
| 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, 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>. |
| |
| <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 a feature of AIX <EM>curses</EM>. |
| |
| <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> equals 0.1 seconds. |
| |
| <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. |
| |
| <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_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.5 2024-04-13 <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> |
| <li><a href="#h2-CONSTANTS">CONSTANTS</a> |
| <ul> |
| <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-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-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-TABSIZE">TABSIZE</a></li> |
| </ul> |
| </li> |
| <li><a href="#h2-NOTES">NOTES</a></li> |
| <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> |
| <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> |
| </ul> |
| </div> |
| </BODY> |
| </HTML> |