.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: ncurses.3x,v 1.217 2024/05/18 20:02:27 tom Exp $
-.TH ncurses 3X 2024-05-18 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: ncurses.3x,v 1.223 2024/06/08 20:45:43 tom Exp $
+.TH ncurses 3X 2024-06-08 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.EE
.RE
.PP
-Most applications perform further setup as follows.
+Most applications would perform further setup as follows.
.PP
.RS 4
.EX
-intrflush(stdscr, FALSE);
+noqiflush();
keypad(stdscr, TRUE);
.EE
.RE
A
.I window
is a rectangular grid of character cells,
-addressed by row and column coordinates
+addressed by line and column coordinates
.RI ( y ,
.IR x ),
with the upper left corner as (0, 0).
.PP
Functions permit manipulation of a window and the
.I cursor
-identifying the cell within it at which the next output operation will
-occur.
+identifying the cell within it at which the next operation will occur.
Among those,
the most basic are \fB\%move\fP(3X) and \fB\%addch\fP(3X):
-these place the cursor and write a character to
+these place the cursor within and write a character to
.BR \%stdscr ,
respectively.
.PP
See \fB\%curs_pad\fP(3X).
.PP
Many terminals support configuration of character cell foreground and
-background colors as well as rendering
+background colors as well as
.IR attributes ","
-which cause characters to show up in such modes as
+which cause characters to render in such modes as
boldfaced,
underlined,
or in reverse video.
appears as a control character or a multibyte
.I "escape sequence."
.I curses
-translates the latter into unique
+can translate the latter into unique
.I "key codes."
-See \fB\%getch\fP(3X).
+See \fB\%keypad\fP(3X) and \fB\%getch\fP(3X).
.PP
.I \%ncurses
provides reimplementations of the SVr4 \fBpanel\fP(3X), \fBform\fP(3X),
In function synopses,
.I \%ncurses
man pages apply the following names to parameters.
+We introduce the character types in the next subsection.
.PP
.TS
center;
.I \%WINDOW
is stored as a
.IR \%chtype .
+X/Open Curses does not specify the sizes of the character code or
+color pair identifier,
+nor the quantity of attribute bits,
+in
+.IR chtype ";"
+these are implementation-dependent.
+.I \%ncurses
+uses eight bits for the character code.
+An application requiring a wider character type,
+for instance to represent Unicode,
+should use the wide-character API.
.TP 10
.I \%ncursesw
is the library in its \*(``wide\*('' configuration,
.I \%char
(a byte-sized type)
can represent.
-It adds about one third more calls using additional data types that
-can store such
-.I multibyte
-characters.
+It provides additional functions that complement those in
+the non-wide library where the size of the underlying character type is
+significant.
+A somewhat regular naming convention relates many of the wide variants
+to their non-wide counterparts;
+where a non-wide function name contains \*(``ch\*('' or \*(``str\*('',
+prefix it with \*(``_w\*('' to obtain the wide counterpart.
+For example,
+\fB\%waddch\fP becomes \fB\%wadd_wch\fP.
+(Exceptions that add only \*(``w\*('' comprise
+.BR \%addwstr ,
+.BR \%inwstr ,
+and their variants.)
+.\" This is because they operate on "plain" wide-character strings
+.\" (`wchar_t*`) and not curses complex character strings (`cchar_t*`).
+.\" SVID 4 did specify functions like `addwch()` and `inswch()` that
+.\" operated on `chtype`s assuming that they were wide enough for a
+.\" `wchar_t` plus attribute and color pair bits; X/Open Curses did not
+.\" standardize these.
+.IP
+This convention is inapplicable to some non-wide function names,
+so other transformations are used for the wide configuration:
+the window background management function \*(``bkgd\*('' becomes
+\*(``bkgrnd\*('';
+the window border-drawing and -clearing functions are suffixed with
+\*(``_set\*('';
+and character attribute manipulation functions like
+\*(``attron\*('' become \*(``attr_on\*(''.
.RS 10 \" same as foregoing tag width
.TP 9 \" "cchar_t" + 2n
.I \%cchar_t
corresponds to the non-wide configuration's
.IR \%chtype .
-It always a structure type,
-because it stores more data than fit into a standard scalar type.
+It is a structure type
+because it requires more storage than a standard scalar type offers.
A character code may not be representable as a
.IR \%char ,
and moreover more than one character may occupy a cell
character manipulation functions of ISO C and its constant
.BR \%EOF .
.RE
-.IP
-The wide library provides additional functions that complement those in
-the non-wide library where the size of the underlying character type is
-significant.
-A somewhat regular naming convention relates many of the wide variants
-to their non-wide counterparts;
-where a non-wide function name contains \*(``ch\*('' or \*(``str\*('',
-prefix it with \*(``_w\*('' to obtain the wide counterpart.
-For example,
-\fB\%waddch\fP becomes \fB\%wadd_wch\fP.
-(Exceptions that add only \*(``w\*('' comprise
-.BR \%addwstr ,
-.BR \%inwstr ,
-and their variants.)
-.IP
-This convention is inapplicable to some non-wide function names,
-so other transformations are used for the wide configuration:
-the window background management function \*(``bkgd\*('' becomes
-\*(``bkgrnd\*('';
-the window border-drawing and -clearing functions are suffixed with
-\*(``_set\*('';
-and character attribute manipulation functions like
-\*(``attron\*('' become \*(``attr_on\*(''.
.\"
.SS "Function Name Index"
The following table lists the
mvaddstr/\fBcurs_addstr\fP(3X)
mvaddwstr/\fBcurs_addwstr\fP(3X)
mvchgat/\fBcurs_attr\fP(3X)
-mvcur/\fBcurs_terminfo\fP(3X)
+mvcur/\fBcurs_kernel\fP(3X)
mvdelch/\fBcurs_delch\fP(3X)
mvderwin/\fBcurs_window\fP(3X)
mvget_wch/\fBcurs_get_wch\fP(3X)
When set,
the
.B \%command_character
-.RB ( \%cmdch )
+.RB \%( cmdch )
capability value of loaded
.I \%term\%info
entries changes to the value of this variable.
.I \%term\%info
entries provide this feature.
.PP
-Because this name is also used in development environments to represent
-the C compiler's name,
+Because this name is also used in development environments to store the
+C compiler's name,
.I \%ncurses
ignores its value if it is not one character in length.
.SS "\fICOLUMNS\fP"
.I \%ncurses
uses the size specified by the
.B \%columns
-.RB ( \%cols )
+.RB \%( cols )
capability of the terminal type's entry in the
.I \%term\%info
database,
and
.I \%LINES
variables may be specified independently.
+.I \%ncurses
+enforces an upper limit of 512 on each when reading the value.
This property is useful to circumvent misfeatures of legacy terminal
type descriptions;
\fI\%xterm\fP(1) descriptions specifying 65 lines were once notorious.
The default value of 1000
(one second)
is adequate for most uses.
-This environment variable overrides it.
+This environment variable overrides it;
+.I \%ncurses
+enforces an upper limit of 30,000
+(30 seconds)
+when reading the value.
.PP
The most common instance where you may wish to change this value
is to work with a remote host over a slow communication channel.
When
.I \%ncurses
is configured to use the GPM interface,
-this variable may list one or more terminal type names
+this variable may list one or more terminal type names,
+delimited by vertical bars
+.RB ( | )
+or colons
+.RB ( : ),
against which the
.I TERM
variable
that can gather color information from them when many colors are
supported.
.PP
-Some extensions are available only if
-.I \%ncurses
-permits modification of \fB\%unctrl\fP(3X)'s behavior;
-see \fB\%use_legacy_coding\fP(3X).
-.I \%ncurses
-is compiled to support them;
-section \*(``ALTERNATE CONFIGURATIONS\*('' describes how.
-.PP
.I \%ncurses
permits modification of \fB\%unctrl\fP(3X)'s behavior;
see \fB\%use_legacy_coding\fP(3X).
but does not finish the story.
A more complete account follows.
.bP
-Starting with 4BSD
-.I curses
-(1980)
-all implementations have provided a
+The first
+.IR curses ","
+in 4BSD,
+provided a
.I \%curses.h
file.
.IP
projects / ncurses.git / blobdiff