+'\" t
.\"***************************************************************************
-.\" Copyright (c) 2017,2018 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: user_caps.5,v 1.7 2018/02/17 19:07:01 tom Exp $
-.TH user_caps 5
+.\" $Id: user_caps.5,v 1.32 2023/09/09 21:25:30 tom Exp $
+.TH user_caps 5 2023-09-09 "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
-.in -4
-..
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
.SH NAME
user_caps \- user-defined terminfo capabilities
.SH SYNOPSIS
-.B tic -x, infocmp -x
+.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,
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.
+For example, ncurses can be configured with tables which match the
+terminal databases for AIX, HP-UX or OSF/1,
+rather than the default Solaris-like configuration.
+.bP
+In SVr4 curses and ncurses,
+the terminal database is defined at compile-time using a text file
+which lists the different terminal capabilities.
+.IP
+In principle, the text-file can be extended,
+but doing this requires recompiling and reinstalling the library.
+The text-file used in ncurses for terminal capabilities includes
+details for various systems past the documented X/Open Curses features.
+For example, ncurses supports these capabilities in each configuration:
+.RS 8
+.TP 5
+memory_lock
+(meml)
+lock memory above cursor
+.TP 5
+memory_unlock
+(memu)
+unlock memory
+.TP 5
+box_chars_1
+(box1)
+box characters primary set
+.RE
+.IP
+The memory lock/unlock capabilities were included because they were used
+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
During the 1990s, some users were reluctant to use terminfo
in spite of its performance advantages over termcap:
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
+The ncurses utilities \fB@TIC@\fP and \fB@INFOCMP@\fP have a command-line
option \*(``\-x\*('' to control whether the nonstandard capabilities
-are stored or retrieved. A library function \fBuse_extended_names\fP
+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
+\fB@TIC@\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,
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:
.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.
+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
.IP
The command \*(``\fBtput clear\fP\*('' does the same thing.
.TP 3
+NQ
+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
-\fBset_a_foreground\fP and
+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.
+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.
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
+mouse, handles the characters sent back by the terminal to tell it what
+was done with the mouse.
+.IP
+The mouse protocol is enabled when
+the \fImask\fP passed in the \fBmousemask\fP function is nonzero.
+By default, ncurses handles the responses for the X11 xterm mouse protocol.
+It also knows about the \fISGR 1006\fP xterm mouse protocol,
+but must to be told to look for this specifically.
+It will not be able to guess which mode is used,
+because the responses are enough alike that only confusion would result.
+.IP
+The \fBXM\fP capability has a single parameter.
+If nonzero, the mouse protocol should be enabled.
+If zero, the mouse protocol should be disabled.
+ncurses inspects this capability if it is present,
+to see whether the 1006 protocol is used.
+If so, it expects the responses to use the \fISGR 1006\fP xterm mouse protocol.
+.IP
+The xterm mouse protocol is used by other terminal emulators.
+The terminal database uses building-blocks for the various xterm mouse
+protocols which can be used in customized terminal descriptions.
+.IP
+The terminal database building blocks for this mouse
+feature also have an experimental capability \fIxm\fP.
+The \*(``xm\*('' capability describes the mouse response.
+Currently there is no interpreter which would use this
+information to make the mouse support completely data-driven.
+.IP
+\fIxm\fP shows the format of the mouse responses.
+In this experimental capability, the parameters are
+.RS 5
+.TP 5
+.I p1
+y-ordinate
+.TP 5
+.I p2
+x-ordinate
+.TP 5
+.I p3
+button
+.TP 5
+.I p4
+state, e.g., pressed or released
+.TP 5
+.I p5
+y-ordinate starting region
+.TP 5
+.I p6
+x-ordinate starting region
+.TP 5
+.I p7
+y-ordinate ending region
+.TP 5
+.I p8
+x-ordinate ending region
+.RE
+.IP
+Here are examples from the terminal database for the most commonly used
+xterm mouse protocols:
+.IP
+.nf
+ xterm+x11mouse|X11 xterm mouse protocol,
+ kmous=\\E[M, XM=\\E[?1000%?%p1%{1}%=%th%el%;,
+ xm=\\E[M
+ %?%p4%t%p3%e%{3}%;%'\ '%+%c
+ %p2%'!'%+%c
+ %p1%'!'%+%c,
+
+ xterm+sm+1006|xterm SGR-mouse,
+ kmous=\\E[<, XM=\\E[?1006;1000%?%p1%{1}%=%th%el%;,
+ xm=\\E[<%i%p3%d;
+ %p1%d;
+ %p2%d;
+ %?%p4%tM%em%;,
+.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)
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)
+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:
+.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 \fBtic\fP and \fBinfocmp\fP
+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 SEE ALSO
+\fB@INFOCMP@\fP(1M),
+\fB@TIC@\fP(1M).
.PP
-\fBtic\fR(1),
-\fBinfocmp\fR(1).
-.SH AUTHORS
+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\fP(1) or \fBtmux\fP(1).
.PP
+.I "XTerm Control Sequences"
+provides further information on the \fBxterm\fP(1) features
+which are used in these extended capabilities.
+.\"
+.SH AUTHORS
Thomas E. Dickey
.br
beginning with ncurses 5.0 (1999)