diff options
Diffstat (limited to 'upstream/archlinux/man3/curs_variables.3x')
| -rw-r--r-- | upstream/archlinux/man3/curs_variables.3x | 403 |
1 files changed, 272 insertions, 131 deletions
diff --git a/upstream/archlinux/man3/curs_variables.3x b/upstream/archlinux/man3/curs_variables.3x index ad6a5b80..a4236ac6 100644 --- a/upstream/archlinux/man3/curs_variables.3x +++ b/upstream/archlinux/man3/curs_variables.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2020,2021 Thomas E. Dickey * +.\" 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 * @@ -27,162 +27,303 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_variables.3x,v 1.17 2021/12/25 21:49:32 tom Exp $ -.TH curs_variables 3X "" -.ie \n(.g .ds `` \(lq -.el .ds `` `` -.ie \n(.g .ds '' \(rq -.el .ds '' '' +.\" $Id: curs_variables.3x,v 1.47 2024/04/13 22:37:35 tom Exp $ +.TH curs_variables 3X 2024-04-13 "ncurses 6.5" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. +.ie \n(.g .ds : \: +.el .ds : \" empty +. .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 .. -.ds n 5 -.na -.hy 0 +. .SH NAME -\fBCOLORS\fP, -\fBCOLOR_PAIRS\fP, -\fBCOLS\fP, -\fBESCDELAY\fP, -\fBLINES\fP, -\fBTABSIZE\fP, -\fBcurscr\fP, -\fBnewscr\fP, -\fBstdscr\fP -\- \fBcurses\fP global variables -.ad -.hy +\fI\%bool\fP, +\fI\%chtype\fP, +\fI\%cchar_t\fP, +\fI\%attr_t\fP, +\fI\%SCREEN\fP, +\fI\%WINDOW\fP, +\fB\%TRUE\fP, +\fB\%FALSE\fP, +\fB\%ERR\fP, +\fB\%OK\fP, +\fB\%curscr\fP, +\fB\%newscr\fP, +\fB\%stdscr\fP, +\fB\%COLORS\fP, +\fB\%COLOR_PAIRS\fP, +\fB\%COLS\fP, +\fB\%LINES\fP, +\fB\%ESCDELAY\fP, +\fB\%TABSIZE\fP \- +\fIcurses\fR data types, constants, and global variables .SH SYNOPSIS .nf -\fB#include <curses.h>\fP -.PP -\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 +\fB#include <curses.h> +.PP +\fI/* data types */ +\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP bool; +\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP chtype; +\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP cchar_t; +\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP attr_t; +\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP SCREEN; +\fBtypedef \fI/*\fP .\|.\|. \fI*/\fP WINDOW; +.PP +\fI/* constants */ +\fBconst bool TRUE; +\fBconst bool FALSE; +.PP +\fBconst \fI/*\fP .\|.\|. \fI*/\fP ERR; +\fBconst \fI/*\fP .\|.\|. \fI*/\fP OK; +.PP +\fI/* variables */ +\fBint COLORS; +\fBint COLOR_PAIRS; +\fBint COLS; +\fBint LINES; +\fBWINDOW * curscr; +\fBWINDOW * stdscr; +.PP +\fI/* extensions */ +\fBint ESCDELAY; +\fBint TABSIZE; +\fBWINDOW * newscr; .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 \fI\%ncurses\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 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: -.bP -a few terminals use HLS colors, which do not follow this rule -.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. +.SH "CONSTANTS" +.SS "TRUE, FALSE" +The \fIcurses\fP library defines \fBTRUE\fP and \fBFALSE\fP +to represent the values of the Boolean data type. +.SS "ERR, OK" +\fIcurses\fP and \fIterminfo\fP routines frequently return these +constant integral values indicating failure and success, +respectively. +.SH "PREDEFINED TYPES" +.SS "\fIbool\fP" +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. +.PP +\fB\%ncurses\fP' configure script attempts to discover the +data type used by the system's C and C++ compilers, +to reuse for the \fIcurses\fP \fIbool\fP. +.SS "\fIchtype\fP" +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 "\fIcchar_t\fP, \fIattr_t\fP" +\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 "\fISCREEN\fP" +.I curses +manages a terminal device with this structure type; +see \fB\%initscr\fP(3X). +.SS "\fIWINDOW\fP" +.I curses +represents rectangular portions of the terminal screen with the +.I \%WINDOW +structure type; +see subsection \*(``Overview\*('' of \fB\%ncurses\fP(3X). +.SH "VARIABLES" +.SS "curscr, stdscr, newscr" +The library records updates to the terminal screen in a window named +\fB\%curscr\fP. +This object is referred to as the \*(``physical screen\*('' in +\fB\%curs_refresh\fP(3X) and +\fB\%curs_outopts\fP(3X). +.PP +\fI\%ncurses\fP collects pending updates to the terminal screen in a +window named \fB\%newscr\fP. +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. +.PP +Once \fIcurses\fP is initialized, +it creates a window 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. .SS COLORS -After initializing curses, this variable contains the number of colors -which the terminal can support. -.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\%COLORS\fP +contains the number of colors supported by the terminal; +see \fB\%curs_color\fP(3X). +.SS COLOR_PAIRS +Once \fIcurses\fP is initialized, +\fB\%COLOR_PAIRS\fP +contains the number of color pairs supported by the terminal; +see \fB\%curs_color\fP(3X). +.SS "COLS, LINES" +Once \fIcurses\fP is initialized, +.B \%COLS +and +.B LINES +contain the screen's width and height in character cells, +respectively; +that is, +the number of columns and lines. .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)). -.SS LINES -After initializing curses, this variable contains the height of the screen, -i.e., the number of lines. +For +.I curses +to distinguish the ESC character resulting from a user's press of the +\*(``Escape\*('' key on the input device from one beginning an +.I "escape sequence" +(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. +.B \%ESCDELAY +stores this interval in milliseconds. +.PP +If \fB\%keypad\fP(3X) is disabled for the +.I curses +window receiving input, +a program must disambiguate escape sequences itself. .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. -.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. -.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. +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). .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 +.I \%ncurses +is configured to provide separate +.I curses +and +.I \%tinfo +libraries, +most of these variables reside in the former. .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\*(''; +SVr4 gave more details, +noting its use \*(``for certain low-level operations like clearing and +redrawing a screen containing garbage\*(''. +.\" SVID 4, Volume 3, p. 408 +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, +it is used as a working area for combining the standard window +\fB\%stdscr\fP with any others the application may have created with +\fB\%newwin\fP(3X). +When the update of \fB\%newscr\fP is complete, +\fIcurses\fP modifies \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 +\fI\%ncurses\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. +\fI\%ncurses\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; +\fI\%ncurses\fP does not enforce any upper limit. .PP -This implementation has long used \fBESCDELAY\fP with units of milliseconds, +\fI\%ncurses\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_color\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(5) +.PP +[UAX #29] \*(``Unicode Standard Annex #29: Unicode Text +Segmentation\*(''; +\%<https://\*:unicode\*:.org/\*:reports/\*:tr29/> |