X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_variables.3x;h=e5265ab1e77b5bd1cce0b4c166be95f22f9bb884;hb=d90067f9008bb8338a77c1ed519bc108c275ed04;hp=8cfee5290e5ccbe47ec9cc595d074d0173694932;hpb=96d6b16de0d487e5d3aed0302a179dbce11b5d96;p=ncurses.git diff --git a/man/curs_variables.3x b/man/curs_variables.3x index 8cfee529..e5265ab1 100644 --- a/man/curs_variables.3x +++ b/man/curs_variables.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 2010 Free Software Foundation, Inc. * +.\" Copyright 2018-2021,2023 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 * @@ -26,110 +27,279 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_variables.3x,v 1.4 2010/12/04 18:38:55 tom Exp $ -.TH curs_variables 3X "" +.\" $Id: curs_variables.3x,v 1.35 2023/12/16 21:05:52 tom Exp $ +.TH curs_variables 3X 2023-12-16 "ncurses 6.4" "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 -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. -.ds n 5 -.na -.hy 0 +. .SH NAME -\fBCOLORS\fR, -\fBCOLOR_PAIRS\fR, -\fBCOLS\fR, -\fBESCDELAY\fR, -\fBLINES\fR, -\fBTABSIZE\fR, -\fBcurscr\fR, -\fBnewscr\fR, -\fBstdscr\fR -\- \fBcurses\fR global variables -.ad -.hy +\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\%ESCDELAY\fP, +\fB\%LINES\fP, +\fB\%TABSIZE\fP, +\fB\%curscr\fP, +\fB\%newscr\fP, +\fB\%stdscr\fP \- +\fIcurses\fR data types, constants, and global variables .SH SYNOPSIS .nf -\fB#include \fR +\fB#include .PP -\fBint COLOR_PAIRS;\fR -.br -\fBint COLORS;\fR -.br -\fBint COLS;\fR -.br -\fBint ESCDELAY;\fR -.br -\fBint LINES;\fR -.br -\fBint TABSIZE;\fR -.br -\fBWINDOW * curscr;\fR -.br -\fBWINDOW * newscr;\fR -.br -\fBWINDOW * stdscr;\fR +\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 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 COLOR_PAIRS; +\fBint COLORS; +\fBint COLS; +\fBint LINES; +\fBWINDOW * curscr; +\fBWINDOW * stdscr; +\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\fR(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 \fIbool\fP, 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 \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 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 curs_addch(3X). -.SS The Current Screen -This implementation of curses uses a special window \fBcurscr\fP to -record its updates to the terminal screen. -.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. -.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). +.SS curscr +\fIcurses\fP records updates to the terminal screen in a \fI\%WINDOW\fP +structure named \fB\%curscr\fP. +.PP +This object is referred to as the \*(``physical screen\*('' in +\fB\%curs_refresh\fP(3X) and +\fB\%curs_outopts\fP(3X). +.SS newscr +\fI\%ncurses\fP collects pending updates to the terminal screen in a +\fI\%WINDOW\fP structure named \fB\%newscr\fP. +.PP +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\fR(3X), -or \fBnewterm\fR(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 \fI\%ncurses\fP is configured to provide separate \fIcurses\fP and +\fIterminfo\fP libraries, +most of these variables reside in the \fIcurses\fP library. .SH PORTABILITY -ESCDELAY and TABSIZE are extensions, -not provided in most other implementations of 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 +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 +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 \fIcurses\fP allows \fB\%TABSIZE\fP to be set through an +environment variable. +\fI\%ncurses\fP does not. +.IP +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 +\fB\%ESCDELAY\fP is a feature of AIX \fIcurses\fP. +.bP +In AIX, +the units for \fB\%ESCDELAY\fP are \fIfifths\fP of milliseconds. +.bP +The default value for AIX's \fB\%ESCDELAY\fP equals 0.1 seconds. +.bP +AIX also enforces a limit of 10,000 seconds for \fB\%ESCDELAY\fP; +\fI\%ncurses\fP does not enforce any upper limit. +.PP +\fI\%ncurses\fP has long used \fB\%ESCDELAY\fP 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. .SH SEE ALSO -\fBcurses\fR(3X), -\fBcurs_threads\fR(3X), -\fBterm_variables\fR(3X), -\fBterminfo\fR(3X), -\fBterminfo\fR(\*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(5) +.PP +[UAX #29] \*(``Unicode Standard Annex #29: Unicode Text +Segmentation\*(''; +\%