.\"***************************************************************************
-.\" Copyright 2018-2021,2022 Thomas E. Dickey *
+.\" Copyright 2018-2022,2023 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: terminfo.tail,v 1.113 2022/12/10 19:51:10 tom Exp $
+.\" $Id: terminfo.tail,v 1.116 2023/07/01 15:33:13 tom Exp $
.ps +1
.SS User-Defined Capabilities
.
string
capabilities, which give a sequence which can be used to perform particular
terminal operations.
-.PP
.SS Types of Capabilities
-.PP
All capabilities have names.
For instance, the fact that
ANSI-standard terminals have
in the example above.
.br
.ne 5
-.PP
.SS Fetching Compiled Descriptions
-.PP
The \fBncurses\fP library searches for terminal descriptions in several places.
It uses only the first description found.
The library has a compiled-in list of places to search
the system terminfo directory, \fI\*d\fP (the compiled-in default).
.RE
.SS Preparing Descriptions
-.PP
We now outline how to prepare descriptions of terminals.
The most effective way to prepare a terminal description is by imitating
the description of a similar terminal in
key several times quickly.
If the terminal messes up, more padding is usually needed.
A similar test can be used for insert character.
-.PP
.SS Basic Capabilities
-.PP
The number of columns on each line for the terminal is given by the
\fBcols\fP numeric capability.
If the terminal is a \s-1CRT\s0, then the
.\".in +2
.ft R
.fi
-.PP
.SS Parameterized Strings
-.PP
Cursor addressing and other strings requiring parameters
in the terminal are described by a
parameterized string capability,
e.g., in the \fBsgr\fP string.
.PP
The \fB%\fP encodings have the following meanings:
-.PP
.TP 5
\fB%%\fP
outputs \*(``%\*(''
variables in the same manner as SVr4.
.RS
.bP
-Unlike other implementations, ncurses zeros dynamic variables
+Unlike other implementations, ncurses zeros dynamic variables
before the first \fB%g\fP or \fB%P\fP operator.
.bP
Like SVr2,
in place of the two previous values) and outputs that value as a character.
Then the same is done for the second parameter.
More complex arithmetic is possible using the stack.
-.PP
.SS Cursor Motions
-.PP
If the terminal has a fast way to home the cursor
(to very upper left corner of screen) then this can be given as
\fBhome\fP; similarly a fast way of getting to the lower left-hand corner
If the \fBsmcup\fP sequence will not restore the screen after an
\fBrmcup\fP sequence is output (to the state prior to outputting
\fBrmcup\fP), specify \fBnrrmc\fP.
-.PP
.SS Margins
SVr4 (and X/Open Curses)
list several string capabilities for setting margins.
parameterized capabilities for setting the top, bottom, left, right margins
given the number of rows or columns.
.RE
-.RE
.PP
In practice, the categorization into \*(``terminal\*('' and \*(``printer\*(''
is not suitable:
both arguments must be given.
.PP
Conversely, when only one capability in the pair is set:
-.bP
+.bP
If only one of \fBsmglp\fP and \fBsmgrp\fP is set,
then it is used with two arguments,
the column number of the left and right margins, in that order.
Applications such as \fBtabs\fP(1) rely upon this to reset all margins.
.\"
.SS Area Clears
-.PP
If the terminal can clear from the current position to the end of the
line, leaving the cursor where it is, this should be given as \fBel\fP.
If the terminal can clear from the beginning of the line to the current
if a true
.B ed
is not available.)
-.PP
.\"
.SS Insert/delete line and vertical motions
-.PP
If the terminal can open a new blank line before the line where the cursor
is, this should be given as \fBil1\fP; this is done only from the first
position of a line.
These indicate
that deleting a line or scrolling may bring non-blank lines up from below
or that scrolling back with \fBri\fP may bring down non-blank lines.
-.PP
.SS Insert/Delete Character
-.PP
There are two basic kinds of intelligent terminals with respect to
insert/delete character which can be described using
.I terminfo.
can be given as
.B ech
with one parameter.
-.PP
.SS "Highlighting, Underlining, and Visible Bells"
-.PP
If your terminal has one or more kinds of display attributes,
these can be represented in a number of different ways.
You should choose one display form as
specify the capability \fBos\fP.
If overstrikes are erasable with a blank,
then this should be indicated by giving \fBeo\fP.
-.PP
.SS Keypad and Function Keys
-.PP
If the terminal has a keypad that transmits codes when the keys are pressed,
this information can be given.
Note that it is not possible to handle
give them in \fBsmln\fP and \fBrmln\fP.
\fBsmln\fP is normally output after one or more pln
sequences to make sure that the change becomes visible.
-.PP
.SS Tabs and Initialization
-.PP
A few capabilities are used only for tabs:
.bP
If the terminal has hardware tabs, the command to advance to the next
only when the \fBit\fP (\fBinit_tabs\fP) capability
is set to a value other than \fIeight\fP.
.SS Delays and Padding
-.PP
Many older and slower terminals do not support either XON/XOFF or DTR
handshaking, including hard copy terminals and some very archaic CRTs
(including, for example, DEC VT100s).
Only the first character of the
.B pad
string is used.
-.PP
.SS Status Lines
Some terminals have an extra \*(``status line\*('' which is not normally used by
software (and thus not counted in the terminal's \fBlines\fP capability).
.PP
The \fBncurses\fP implementation does not yet use any of these capabilities.
They are documented here in case they ever become important.
-.PP
.SS Line Graphics
-.PP
Many terminals have alternate character sets useful for forms-drawing.
Terminfo and \fBcurses\fP have built-in support
for most of the drawing characters
as the corresponding graphic.
Then read off the VT100/your terminal
character pairs right to left in sequence; these become the ACSC string.
-.PP
.SS Color Handling
-.PP
The curses library functions \fBinit_pair\fP and \fBinit_color\fP
manipulate the \fIcolor pairs\fP and \fIcolor values\fP discussed in this
section
.PP
SVr4 curses does nothing with \fBncv\fP, ncurses recognizes it and optimizes
the output in favor of colors.
-.PP
.SS Miscellaneous
If the terminal requires other than a null (zero) character as a pad, then this
can be given as pad.
is transparently passed to the printer while an
.B mc5p
is in effect.
-.PP
.SS Glitches and Braindamage
-.PP
Hazeltine terminals, which do not allow \*(``~\*('' characters to be displayed should
indicate \fBhz\fP.
.PP
.PP
Other specific terminal problems may be corrected by adding more
capabilities of the form \fBx\fP\fIx\fP.
-.PP
.SS Pitfalls of Long Entries
-.PP
Long terminfo entries are unlikely to be a problem; to date, no entry has even
approached terminfo's 4096-byte string-table maximum.
Unfortunately, the termcap
SVr1, and have added extension capabilities to the string table that (in the
binary format) collide with System V and XSI Curses extensions.
.SH EXTENSIONS
-.PP
Searching for terminal descriptions in
\fB$HOME/.terminfo\fP and TERMINFO_DIRS
is not supported by older implementations.
X/Open Curses does not mention italics.
Portable applications must assume that numeric capabilities are
signed 16-bit values.
-This includes the \fIno_color_video\fP (ncv) capability.
-The 32768 mask value used for italics with ncv can be confused with
-an absent or cancelled ncv.
+This includes the \fIno_color_video\fP (\fBncv\fP) capability.
+The 32768 mask value used for italics with \fBncv\fP can be confused with
+an absent or cancelled \fBncv\fP.
If italics should work with colors,
-then the ncv value must be specified, even if it is zero.
+then the \fBncv\fP value must be specified, even if it is zero.
.PP
Different commercial ports of terminfo and curses support different subsets of
the XSI Curses standard and (in some cases) different extension sets.
projects / ncurses.git / blobdiff