X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fuser_caps.5;h=43dd000cdc084d9887b1ea0bbe2e1cd018b011c4;hp=f4d0828b2421905782fc9b4e2d77232fb0584cf9;hb=a6eb34d7fec8170a8715f9e53ca2f96452dd30dd;hpb=a20e6eb464be80b9cd8cae7ce925d27fe9c209ed diff --git a/man/user_caps.5 b/man/user_caps.5 index f4d0828b..43dd000c 100644 --- a/man/user_caps.5 +++ b/man/user_caps.5 @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 2017 Free Software Foundation, Inc. * +.\" Copyright 2018-2019,2020 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 * @@ -26,16 +27,16 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: user_caps.5,v 1.1 2017/08/12 21:26:12 tom Exp $ +.\" $Id: user_caps.5,v 1.16 2020/12/19 21:26:11 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 +.ie n .sp .el .sp .5 -.ie \n(.in +4 +.ie n .in +4 .el .in +2 .nf .ft C \" Courier @@ -43,16 +44,17 @@ .de NE .fi .ft R -.in -4 +.ie n .in -4 +.el .in -2 .. .de bP -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. -.ds n 5 .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 @@ -93,6 +95,38 @@ while others were added (out of order) to comply with X/Open Curses. 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. +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: @@ -115,13 +149,14 @@ 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 +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, @@ -161,7 +196,7 @@ 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 @@ -175,9 +210,9 @@ The command \*(``\fBtput clear\fP\*('' does the same thing. RGB \fIboolean\fP, \fInumber\fP \fBor\fP \fIstring\fP, to assert that the -\fBset_a_foreground\fP and +\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. @@ -203,14 +238,20 @@ blue (and green) lose just as in the \fIboolean\fP case. explicitly list the number of bits used for red, green and blue components as a slash-separated list of decimal integers. .RE +.IP +Because there are several RGB encodings in use, +applications which make assumptions about the number of bits per color +are unlikely to work reliably. +As a trivial case, for example, one could define \fBRGB#1\fP +to represent the standard eight ANSI colors, i.e., one bit per color. .TP 3 U8 -\fIboolean\fP, +\fInumber\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 \fBterminfo\fP(5). +\fBNCURSES_NO_UTF8_ACS\fP in \fBncurses\fP(3X). .IP Set this capability to a nonzero value to enable it. .TP 3 @@ -218,6 +259,84 @@ XM \fIstring\fP, override ncurses's built-in string which enables/disables \fBxterm\fP 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 @@ -248,7 +367,7 @@ 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) +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 @@ -290,16 +409,29 @@ 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 .PP -\fBtic\fR(1), -\fBinfocmp\fR(1). +\fB@INFOCMP@\fR(1M), +\fB@TIC@\fR(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). +.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