+'\" t
.\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey *
+.\" Copyright 2018-2022,2023 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.17 2021/06/17 21:30:22 tom Exp $
-.TH user_caps 5
+.\" $Id: user_caps.5,v 1.40 2023/09/30 23:47:46 tom Exp $
+.TH user_caps 5 2023-09-30 "ncurses 6.4" "File formats"
.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
-.ie n .in -4
-.el .in -2
-..
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
.SH NAME
-user_caps \- user-defined terminfo capabilities
+user_caps \-
+user-defined \fIterminfo\fR capability format
.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,
.RE
.IP
The memory lock/unlock capabilities were included because they were used
-in the X11R6 terminal description for \fBxterm\fP.
+in the X11R6 terminal description for \fBxterm\fP(1).
The \fIbox1\fP capability is used in @TIC@ to help with terminal descriptions
written for AIX.
.PP
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
+The ncurses database uses a convention based on \fBxterm\fP(1) 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:
.IP
The command \*(``\fBtput clear\fP\*('' does the same thing.
.TP 3
+NQ
+\fIboolean\fP,
+used to suppress a consistency check in @TIC@ for the ncurses capabilities
+in user6 through user9 (u6, u7, u8 and u9)
+which tell how to query the terminal's cursor position
+and its device attributes.
+.TP 3
RGB
\fIboolean\fP, \fInumber\fP \fBor\fP \fIstring\fP,
-to assert that the
+used 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.
XM
\fIstring\fP,
override ncurses's built-in string which
-enables/disables \fBxterm\fP mouse mode.
+enables/disables \fBxterm\fP(1) mouse mode.
.IP
ncurses sends a character sequence to the terminal to initialize mouse mode,
and when the user clicks the mouse buttons or (in certain modes) moves the
.fi
.
.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
+Since 1999, \fBxterm\fP(1) 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
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:
+.PP
.RS 5
.TS
tab(/) ;
l l .
-\fIName\fR/\fIDescription\fR
+\fBName\fP/\fBDescription\fP
_
kDC/special form of kdch1 (delete character)
kDN/special form of kcud1 (cursor down)
.RE
.PP
These are the suffixes used to denote the modifiers:
+.PP
.RS 5
.TS
tab(/) ;
l l .
-\fIValue\fR/\fIDescription\fR
+\fBValue\fP/\fBDescription\fP
_
2/Shift
3/Alt
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 \fB@TIC@\fP and \fB@INFOCMP@\fP
has been adopted in NetBSD curses.
That implementation stores user-defined capabilities,
but makes no use of these capabilities itself.
.\"
+.SH AUTHORS
+Thomas E. Dickey
+.br
+beginning with ncurses 5.0 (1999)
+.\"
.SH SEE ALSO
-.PP
-\fB@INFOCMP@\fR(1M),
-\fB@TIC@\fR(1M).
+\fB\%@INFOCMP@\fP(1M),
+\fB\%@TIC@\fP(1M)
.PP
The terminal database section
.I "NCURSES USER-DEFINABLE CAPABILITIES"
summarizes commonly-used user-defined capabilities
which are used in the terminal descriptions.
-Some of those features are mentioned in \fBscreen\fR(1) or \fBtmux\fR(1).
+Some of those features are mentioned in \fB\%screen\fP(1) or
+\fBtmux\fP(1).
.PP
.I "XTerm Control Sequences"
-provides further information on the \fBxterm\fP features
-which are used in these extended capabilities.
-.\"
-.SH AUTHORS
-.PP
-Thomas E. Dickey
-.br
-beginning with ncurses 5.0 (1999)
+provides further information on the \fB\%xterm\fP(1) features
+that are used in these extended capabilities.
projects / ncurses.git / blobdiff