'\" t
.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: user_caps.5,v 1.43 2023/12/23 16:08:25 tom Exp $
-.TH user_caps 5 2023-12-23 "ncurses 6.4" "File formats"
+.\" $Id: user_caps.5,v 1.51 2024/06/08 21:01:53 tom Exp $
+.TH user_caps 5 2024-06-08 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "File formats"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
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.
+and standardized in X/Open Curses starting in 1995.
+.\" That date is a surmise based on the capability list appearing in
+.\" Issue 4, Version 2 (1996). That list is not in man page format in
+.\" the standard, so lacks a "HISTORY" section. However, `tigetstr()`
+.\" and `tputs()` are identified in the same document as new to Issue 4,
+.\" so GBR conjectures that the list came in at the same time.
.PP
Most of the \fIextensions\fP in this fixed repertoire were additions
-to the tables of boolean, numeric and string capabilities.
+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
.RS 3
.TP 3
AX
-\fIboolean\fP, asserts that the terminal interprets SGR 39 and SGR 49
+\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.
The command \*(``\fBtput clear\fP\*('' does the same thing.
.TP 3
NQ
-\fIboolean\fP,
+\fIBoolean\fP,
used to suppress a consistency check in @TIC@ for the \fI\%ncurses\fP
capabilities
in user6 through user9 (u6, u7, u8 and u9)
and its device attributes.
.TP 3
RGB
-\fIboolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
+\fIBoolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
used to assert that the
\fBset_a_foreground\fP and
\fBset_a_background\fP capabilities correspond to \fIdirect colors\fP,
The capability type determines the values which \fI\%ncurses\fP sees:
.RS 3
.TP 3
-\fIboolean\fP
+\fIBoolean\fP
implies that the number of bits for red, green and blue are the same.
Using the maximum number of colors,
\fI\%ncurses\fP adds two,
\fInumber\fP
tells \fI\%ncurses\fP what result to add to red, green and blue.
If \fI\%ncurses\fP runs out of bits,
-blue (and green) lose just as in the \fIboolean\fP case.
+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
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,
-\fI\%ncurses\fP' terminal database defines these names to which a suffix
-is added:
+Starting with the
+.I curses
+convention that capability codes describing the input generated by a
+terminal's key caps begin with \*(``k\*('',
+and that shifted special keys use uppercase letters in their names,
+.IR \%ncurses 's
+terminal database defines the following names and codes to which a
+suffix is added.
.PP
.RS 5
.TS
-tab(/) ;
-l l .
-\fBName\fP/\fBDescription\fP
+Lb Lb
+Lb Lx.
+Code Description
_
-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)
+kDC shifted kdch1 (delete character)
+.\" kDC is a standard capability; see X/Open Curses Issue 7, p. 345.
+kDN shifted kcud1 (cursor down)
+kEND shifted kend (end)
+kHOM shifted khome (home)
+kLFT shifted kcub1 (cursor back)
+kNXT shifted knext (next)
+kPRV shifted kprev (previous)
+kRIT shifted kcuf1 (cursor forward)
+kUP shifted kcuu1 (cursor up)
.TE
.RE
.PP
+Keycap nomenclature on the Unix systems for which
+.I curses
+was developed differs from today's ubiquitous descendants of the IBM
+PC/AT keyboard layout.
+In the foregoing,
+interpret \*(``backward\*('' as \*(``left\*('',
+\*(``forward\*('' as \*(``right\*('',
+\*(``next\*('' as \*(``page down\*('',
+and
+\*(``prev(ious)\*('' as \*(``page up\*(''.
+.PP
These are the suffixes used to denote the modifiers:
.PP
.RS 5
projects / ncurses.git / blobdiff