mirror of
https://github.com/Aigor44/ncursesw-morphos.git
synced 2024-12-27 07:49:06 +08:00
5d8dbcdd94
+ improve wide-character implementation of myADDNSTR() in frm_driver.c,
which was inconsistent with the normal implementation.
+ save/restore cursor position in Undo_Justification(), matching
behavior of Buffer_To_Window() (report by Leon Winter).
+ modify test/knight to provide the "slow" solution for small screens
using "R", noting that Warnsdorf's method is easily done with "a".
+ modify several test-programs which call use_default_colors() to
consistently do this only if "-d" option is given.
+ additional changes to test with non-standard variants of curses:
+ modify a loop limit in firework.c to work around absense of limit
checks in some libraries.
+ fill the last row of a window with "?" in firstlast if waddch does
not return ERR on the lower-right corner.
+ add checks in test/configure for some functions not in 4.3BSD curses.
+ fix a regression in test/configure (cf: 20170826).
308 lines
11 KiB
Groff
308 lines
11 KiB
Groff
.\"***************************************************************************
|
|
.\" Copyright (c) 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: user_caps.5,v 1.2 2017/09/04 19:27:24 tom Exp $
|
|
.TH user_caps 5
|
|
.ie \n(.g .ds `` \(lq
|
|
.el .ds `` ``
|
|
.ie \n(.g .ds '' \(rq
|
|
.el .ds '' ''
|
|
.de NS
|
|
.ie \n(.sp
|
|
.el .sp .5
|
|
.ie \n(.in +4
|
|
.el .in +2
|
|
.nf
|
|
.ft C \" Courier
|
|
..
|
|
.de NE
|
|
.fi
|
|
.ft R
|
|
.in -4
|
|
..
|
|
.de bP
|
|
.IP \(bu 4
|
|
..
|
|
.ds n 5
|
|
.SH NAME
|
|
user_caps \- user-defined terminfo capabilities
|
|
.SH SYNOPSIS
|
|
.B tic -x, infocmp -x
|
|
.SH DESCRIPTION
|
|
.SS Background
|
|
.PP
|
|
Before ncurses 5.0,
|
|
terminfo databases used a \fIfixed repertoire\fP of terminal
|
|
capabilities designed for the SVr2 terminal database in 1984,
|
|
and extended in stages through SVr4 (1989),
|
|
and standardized in the Single Unix Specification beginning in 1995.
|
|
.PP
|
|
Most of the \fIextensions\fP in this fixed repertoire were additions
|
|
to the tables of boolean, numeric and string capabilities.
|
|
Rather than change the meaning of an existing capability, a new name was added.
|
|
The terminfo database uses a binary format; binary compatibility was
|
|
ensured by using a header which gave the number of items in the
|
|
tables for each type of capability.
|
|
The standardization was incomplete:
|
|
.bP
|
|
The \fIbinary format\fP itself is not described
|
|
in the X/Open Curses documentation.
|
|
Only the \fIsource format\fP is described.
|
|
.IP
|
|
Library developers rely upon the SVr4 documentation,
|
|
and reverse-engineering the compiled terminfo files to match the binary format.
|
|
.bP
|
|
Lacking a standard for the binary format, most implementations
|
|
copy the SVr2 binary format, which uses 16-bit signed integers,
|
|
and is limited to 4096-byte entries.
|
|
.IP
|
|
The format cannot represent very large numeric capabilities,
|
|
nor can it represent large numbers of special keyboard definitions.
|
|
.bP
|
|
The tables of capability names differ between implementations.
|
|
.IP
|
|
Although they \fImay\fP provide all of the standard capability names,
|
|
the position in the tables differs because some features were added as needed,
|
|
while others were added (out of order) to comply with X/Open Curses.
|
|
.IP
|
|
While ncurses' repertoire of predefined capabilities is closest to Solaris,
|
|
Solaris's terminfo database has a few differences from
|
|
the list published by X/Open Curses.
|
|
.PP
|
|
During the 1990s, some users were reluctant to use terminfo
|
|
in spite of its performance advantages over termcap:
|
|
.bP
|
|
The fixed repertoire prevented users from adding features
|
|
for unanticipated terminal improvements
|
|
(or required them to reuse existing capabilities as a workaround).
|
|
.bP
|
|
The limitation to 16-bit signed integers was also mentioned.
|
|
Because termcap stores everything as a string,
|
|
it could represent larger numbers.
|
|
.PP
|
|
Although termcap's extensibility was rarely used
|
|
(it was never the \fIspeaker\fP who had actually used the feature),
|
|
the criticism had a point.
|
|
ncurses 5.0 provided a way to detect nonstandard capabilities,
|
|
determine their
|
|
type and optionally store and retrieve them in a way which did not interfere
|
|
with other applications.
|
|
These are referred to as \fIuser-defined capabilities\fP because no
|
|
modifications to the toolset's predefined capability names are needed.
|
|
.PP
|
|
The ncurses utilities \fBtic\fP and \fBinfocmp\fP have a command-line
|
|
option \*(``\-x\*('' to control whether the nonstandard capabilities
|
|
are stored or retrieved. A library function \fBuse_extended_names\fP
|
|
is provided for the same purpose.
|
|
.PP
|
|
When compiling a terminal database, if \*(``\-x\*('' is set,
|
|
\fBtic\fP will store a user-defined capability if the capability name is not
|
|
one of the predefined names.
|
|
.PP
|
|
Because ncurses provides a termcap library interface,
|
|
these user-defined capabilities may be visible to termcap applications:
|
|
.bP
|
|
The termcap interface (like all implementations of termcap)
|
|
requires that the capability names are 2-characters.
|
|
.IP
|
|
When the capability is simple enough for use in a termcap application,
|
|
it is provided as a 2-character name.
|
|
.bP
|
|
There are other
|
|
user-defined capabilities which refer to features not usable in termcap,
|
|
e.g., parameterized strings that use more than two parameters
|
|
or use more than the trivial expression support provided by termcap.
|
|
For these, the terminfo database should have only capability names with
|
|
3 or more characters.
|
|
.bP
|
|
Some terminals can send distinct strings for special keys (cursor-,
|
|
keypad- or function-keys) depending on modifier keys (shift, control, etc.).
|
|
While terminfo and termcap have a set of 60 predefined function-key names,
|
|
to which a series of keys can be assigned,
|
|
that is insufficient for more than a dozen keys multiplied by more than
|
|
a couple of modifier combinations.
|
|
The ncurses database uses a convention based on \fBxterm\fP to
|
|
provide extended special-key names.
|
|
.IP
|
|
Fitting that into termcap's limitation of 2-character names
|
|
would be pointless.
|
|
These extended keys are available only with terminfo.
|
|
.SS Recognized capabilities
|
|
.PP
|
|
The ncurses library uses the user-definable capabilities.
|
|
While the terminfo database may have other extensions,
|
|
ncurses makes explicit checks for these:
|
|
.RS 3
|
|
.TP 3
|
|
AX
|
|
\fIboolean\fP, asserts that the terminal interprets SGR 39 and SGR 49
|
|
by resetting the foreground and background color, respectively, to the default.
|
|
.IP
|
|
This is a feature recognized by the \fBscreen\fP program as well.
|
|
.TP 3
|
|
E3
|
|
\fIstring\fP, tells how to clear the terminal's scrollback buffer.
|
|
When present, the \fBclear\fP(1) program sends this before clearing
|
|
the terminal.
|
|
.IP
|
|
The command \*(``\fBtput clear\fP\*('' does the same thing.
|
|
.TP 3
|
|
RGB
|
|
\fIboolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
|
|
to assert that the
|
|
\fBset_a_foreground\fP and
|
|
\fBset_a_background\fP capabilities correspond to \fIdirect colors\fP,
|
|
using an RGB (red/green/blue) convention.
|
|
This capability allows the \fBcolor_content\fP function to
|
|
return appropriate values without requiring the application
|
|
to initialize colors using \fBinit_color\fP.
|
|
.IP
|
|
The capability type determines the values which ncurses sees:
|
|
.RS 3
|
|
.TP 3
|
|
\fIboolean\fP
|
|
implies that the number of bits for red, green and blue are the same.
|
|
Using the maximum number of colors,
|
|
ncurses adds two, divides that sum by three, and assigns the result
|
|
to red, green and blue in that order.
|
|
.IP
|
|
If the number of bits needed for the number of colors is not a multiple
|
|
of three, the blue (and green) components lose in comparison to red.
|
|
.TP 3
|
|
\fInumber\fP
|
|
tells ncurses what result to add to red, green and blue.
|
|
If ncurses runs out of bits,
|
|
blue (and green) lose just as in the \fIboolean\fP case.
|
|
.TP 3
|
|
\fIstring\fP
|
|
explicitly list the number of bits used for red, green and blue components
|
|
as a slash-separated list of decimal integers.
|
|
.RE
|
|
.TP 3
|
|
U8
|
|
\fIboolean\fP,
|
|
asserts that ncurses must use Unicode values for line-drawing characters,
|
|
and that it should ignore the alternate character set capabilities
|
|
when the locale uses UTF-8 encoding.
|
|
For more information, see the discussion of
|
|
\fBNCURSES_NO_UTF8_ACS\fP in \fBncurses\fP(3X).
|
|
.IP
|
|
Set this capability to a nonzero value to enable it.
|
|
.TP 3
|
|
XM
|
|
\fIstring\fP,
|
|
override ncurses's built-in string which
|
|
enables/disables \fBxterm\fP mouse mode.
|
|
.
|
|
.SS Extended key-definitions
|
|
.PP
|
|
Several terminals provide the ability to send distinct strings for
|
|
combinations of modified special keys.
|
|
There is no standard for what those keys can send.
|
|
.PP
|
|
Since 1999, \fBxterm\fP has supported
|
|
\fIshift\fP, \fIcontrol\fP, \fIalt\fP, and \fImeta\fP modifiers which produce
|
|
distinct special-key strings.
|
|
In a terminal description, ncurses has no special knowledge of the
|
|
modifiers used.
|
|
Applications can use the \fInaming convention\fP established for \fBxterm\fP
|
|
to find these special keys in the terminal description.
|
|
.PP
|
|
Starting with the curses convention that \fIkey names\fP begin with \*(``k\*(''
|
|
and that shifted special keys are an uppercase name,
|
|
ncurses' terminal database defines these names to which a suffix is added:
|
|
.RS 5
|
|
.TS
|
|
tab(/) ;
|
|
l l .
|
|
\fIName\fR/\fIDescription\fR
|
|
_
|
|
kDC/special form of kdch1 (delete character)
|
|
kDN/special form of kcud1 (cursor down)
|
|
kEND/special form of kend (End)
|
|
kHOM/special form of khome (Home)
|
|
kLFT/special form of kcub1 (cursor-left or cursor-back)
|
|
kNXT/special form of knext (Next, or Page-Down)
|
|
kPRV/special form of kprev (Prev, or Page-Up)
|
|
kRIT/special form of kcuf1 (cursor-right, or cursor-forward)
|
|
kUP/special form of kcuu1 (cursor-up)
|
|
.TE
|
|
.RE
|
|
.PP
|
|
These are the suffixes used to denote the modifiers:
|
|
.RS 5
|
|
.TS
|
|
tab(/) ;
|
|
l l .
|
|
\fIValue\fR/\fIDescription\fR
|
|
_
|
|
2/Shift
|
|
3/Alt
|
|
4/Shift + Alt
|
|
5/Control
|
|
6/Shift + Control
|
|
7/Alt + Control
|
|
8/Shift + Alt + Control
|
|
9/Meta
|
|
10/Meta + Shift
|
|
11/Meta + Alt
|
|
12/Meta + Alt + Shift
|
|
13/Meta + Ctrl
|
|
14/Meta + Ctrl + Shift
|
|
15/Meta + Ctrl + Alt
|
|
16/Meta + Ctrl + Alt + Shift
|
|
.TE
|
|
.RE
|
|
.PP
|
|
None of these are predefined; terminal descriptions can refer to \fInames\fP
|
|
which ncurses will allocate at runtime to \fIkey-codes\fP.
|
|
To use these keys in an ncurses program, an application could do this:
|
|
.bP
|
|
using a list of extended key \fInames\fP,
|
|
ask \fBtigetstr\fP(3X) for their values, and
|
|
.bP
|
|
given the list of values,
|
|
ask \fBkey_defined\fP(3X) for the \fIkey-code\fP which
|
|
would be returned for those keys by \fBwgetch\fP(3X).
|
|
.PP
|
|
.SH PORTABILITY
|
|
.PP
|
|
The \*(``\-x\*('' extension feature of \fBtic\fP and \fBinfocmp\fP
|
|
has been adopted in NetBSD curses.
|
|
That implementation stores user-defined capabilities,
|
|
but makes no use of these capabilities itself.
|
|
.SH SEE ALSO
|
|
.PP
|
|
\fBtic\fR(1),
|
|
\fBinfocmp\fR(1).
|
|
.SH AUTHORS
|
|
.PP
|
|
Thomas E. Dickey
|
|
.br
|
|
beginning with ncurses 5.0 (1999)
|