mirror of
https://github.com/Aigor44/ncursesw-morphos.git
synced 2024-12-27 07:49:06 +08:00
3eda6f30a8
+ minor fixes for vt100+4bsd, e.g., delay in sgr for consistency -TD
+ add smso for env230, to match sgr -TD
+ remove p7/protect from sgr in fbterm -TD
+ drop setf/setb from fbterm; setaf/setab are enough -TD
+ make xterm-pcolor sgr consistent with other capabilities -TD
+ add rmxx/smxx ECMA-48 strikeout extension to tmux and xterm-basic
(discussion with Nicholas Marriott)
+ add test-programs sp_tinfo and extended_color
+ modify no-leaks code for lib_cur_term.c to account for the tgetent()
cache.
+ modify setupterm() to save original tty-modes so that erasechar()
works as expected. Also modify _nc_setupscreen() to avoid redundant
calls to get original tty-modes.
+ modify set_curterm() to update ttytype[] data used by longname().
+ modify wattr_set() and wattr_get() to return ERR if win-parameter is
null, as documented.
+ improve cast used for null-pointer checks in header macros, to
reduce compiler warnings.
+ modify several functions, using the reserved "opts" parameter to pass
color- and pair-values larger than 16-bits:
+ getcchar(), setcchar(), slk_attr_set(), vid_puts(), wattr_get(),
wattr_set(), wchgat(), wcolor_set().
+ Other functions call these with the corresponding altered behavior,
including chgat(), mvchgat(), mvwchgat(), slk_color_on(),
slk_color_off(), vid_attr().
+ add new functions for manipulating color- and pair-values larger
than 16-bits. These are extended_color_content(),
extended_pair_content(), extended_slk_color(), init_extended_color(),
init_extended_pair(), and the corresponding sp-funcs.
394 lines
15 KiB
Plaintext
394 lines
15 KiB
Plaintext
'\" t
|
|
.\"***************************************************************************
|
|
.\" Copyright (c) 1998-2016,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: curs_attr.3x,v 1.53 2017/03/28 23:31:39 tom Exp $
|
|
.TH curs_attr 3X ""
|
|
.de bP
|
|
.IP \(bu 4
|
|
..
|
|
.na
|
|
.hy 0
|
|
.SH NAME
|
|
.\" attr_get
|
|
\fBattr_get\fR,
|
|
\fBwattr_get\fR,
|
|
\fBattr_set\fR,
|
|
\fBwattr_set\fR,
|
|
.\" .br
|
|
\fBattr_off\fR,
|
|
\fBwattr_off\fR,
|
|
\fBattr_on\fR,
|
|
\fBwattr_on\fR,
|
|
.\" .br
|
|
\fBattroff\fR,
|
|
\fBwattroff\fR,
|
|
\fBattron\fR,
|
|
\fBwattron\fR,
|
|
\fBattrset\fR,
|
|
\fBwattrset\fR,
|
|
.\" .br
|
|
\fBchgat\fR,
|
|
\fBwchgat\fR,
|
|
\fBmvchgat\fR,
|
|
\fBmvwchgat\fR,
|
|
.\" .br
|
|
\fBcolor_set\fR,
|
|
\fBwcolor_set\fR,
|
|
.\" .br
|
|
\fBstandend\fR,
|
|
\fBwstandend\fR,
|
|
\fBstandout\fR,
|
|
\fBwstandout\fR \- \fBcurses\fR character and window attribute control routines
|
|
.ad
|
|
.hy
|
|
.SH SYNOPSIS
|
|
\fB#include <curses.h>\fR
|
|
.sp
|
|
\fBint attr_get(attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR
|
|
.br
|
|
\fBint wattr_get(WINDOW *\fP\fIwin\fP\fB, attr_t *\fP\fIattrs\fP\fB, short *\fP\fIpair\fP\fB,\fR \fBvoid *\fP\fIopts\fP\fB);\fR
|
|
.br
|
|
\fBint attr_set(attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR
|
|
.br
|
|
\fBint wattr_set(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, short \fP\fIpair\fP\fB, void *\fP\fIopts\fP\fB);\fR
|
|
.sp
|
|
\fBint attr_off(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
|
|
.br
|
|
\fBint wattr_off(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
|
|
.br
|
|
\fBint attr_on(attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
|
|
.br
|
|
\fBint wattr_on(WINDOW *\fP\fIwin\fP\fB, attr_t \fP\fIattrs\fP\fB, void *\fP\fIopts\fP\fB);\fR
|
|
.sp
|
|
\fBint attroff(int \fP\fIattrs);\fR
|
|
.br
|
|
\fBint wattroff(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
|
|
.br
|
|
\fBint attron(int \fP\fIattrs\fP\fB);\fR
|
|
.br
|
|
\fBint wattron(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
|
|
.br
|
|
\fBint attrset(int \fP\fIattrs\fP\fB);\fR
|
|
.br
|
|
\fBint wattrset(WINDOW *\fP\fIwin\fP\fB, int \fP\fIattrs\fP\fB);\fR
|
|
.sp
|
|
\fBint chgat(int \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB, short \fP\fIpair\fP\fB,\fR \fBconst void *\fP\fIopts\fP\fB);\fR
|
|
.br
|
|
\fBint wchgat(WINDOW *\fP\fIwin\fP\fB,\fP
|
|
\fBint \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fR \fBshort \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fR
|
|
.br
|
|
\fBint mvchgat(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB,\fP
|
|
\fBint \fP\fIn\fP\fB, attr_t \fP\fIattr\fP\fB,\fR \fBshort \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fR
|
|
.br
|
|
\fBint mvwchgat(WINDOW *\fP\fIwin, int \fP\fIy, int \fP\fIx\fP\fB,\fP
|
|
\fBint \fP\fIn,\fR \fBattr_t \fP\fIattr\fP\fB, short \fP\fIpair\fP\fB, const void *\fP\fIopts\fP\fB);\fR
|
|
.sp
|
|
\fBint color_set(short \fP\fIpair\fP\fB, void* \fP\fIopts\fP\fB);\fR
|
|
.br
|
|
\fBint wcolor_set(WINDOW *\fP\fIwin\fP\fB, short \fP\fIpair\fP\fB,\fR \fBvoid* \fP\fIopts);\fR
|
|
.sp
|
|
\fBint standend(void);\fR
|
|
.br
|
|
\fBint wstandend(WINDOW *\fP\fIwin\fP\fB);\fR
|
|
.br
|
|
\fBint standout(void);\fR
|
|
.br
|
|
\fBint wstandout(WINDOW *\fP\fIwin\fP\fB);\fR
|
|
.SH DESCRIPTION
|
|
.PP
|
|
These routines manipulate the current attributes of the named window,
|
|
which then apply to all characters that are written into
|
|
the window with \fBwaddch\fR, \fBwaddstr\fR and \fBwprintw\fR.
|
|
Attributes are
|
|
a property of the character, and move with the character through any scrolling
|
|
and insert/delete line/character operations.
|
|
To the extent possible, they are
|
|
displayed as appropriate modifications to the graphic rendition of characters
|
|
put on the screen.
|
|
.PP
|
|
These routines do not affect the attributes used
|
|
when erasing portions of the window.
|
|
See \fBcurs_bkgd\fR(3X) for functions which modify the attributes used for
|
|
erasing and clearing.
|
|
.PP
|
|
Routines which do not have a \fBWINDOW*\fP parameter apply to \fBstdscr\fP.
|
|
For example,
|
|
\fBattr_set\fP is the \fBstdscr\fP variant of \fBwattr_set\fP.
|
|
.\" ---------------------------------------------------------------------------
|
|
.SS Window attributes
|
|
.PP
|
|
There are two sets of functions:
|
|
.bP
|
|
functions for manipulating the window attributes and color:
|
|
\fBwattr_set\fP and \fBwattr_get\fP.
|
|
.bP
|
|
functions for manipulating only the window attributes (not color):
|
|
\fBwattr_on\fP and \fBwattr_off\fP.
|
|
.PP
|
|
The \fBwattr_set\fP function sets the current attributes
|
|
of the given window to \fIattrs\fP, with color specified by \fIpair\fP.
|
|
.PP
|
|
Use \fBwattr_get\fP to retrieve attributes for the given window.
|
|
.PP
|
|
Use \fBattr_on\fP and \fBwattr_on\fP to turn on window attributes, i.e.,
|
|
values OR'd together in \fIattr\fP,
|
|
without affecting other attributes.
|
|
Use \fBattr_off\fP and \fBwattr_off\fP to turn off window attributes,
|
|
again values OR'd together in \fIattr\fP,
|
|
without affecting other attributes.
|
|
.\" ---------------------------------------------------------------------------
|
|
.SS Legacy window attributes
|
|
Most of the window attribute routines are extensions of older routines
|
|
which assume that color pairs are OR'd into the attribute parameter.
|
|
These older routines use the same name, omitting an underscore (\fB_\fP).
|
|
|
|
The \fBattrset\fP routine is a legacy feature predating SVr4 curses
|
|
but kept in X/Open Curses for the same reason that SVr4 curses kept it:
|
|
compatibility.
|
|
.PP
|
|
The remaining \fBattr\fR* functions operate exactly like the corresponding
|
|
\fBattr_\fR* functions, except that they take arguments of type \fBint\fR
|
|
rather than \fBattr_t\fR.
|
|
.PP
|
|
There is no corresponding \fBattrget\fP function as such in X/Open Curses,
|
|
although ncurses provides \fBgetattrs\fP (see curs_legacy(3X)).
|
|
.\" ---------------------------------------------------------------------------
|
|
.SS Change character rendition
|
|
.PP
|
|
The routine \fBchgat\fR changes the attributes of a given number of characters
|
|
starting at the current cursor location of \fBstdscr\fR.
|
|
It does not update
|
|
the cursor and does not perform wrapping.
|
|
A character count of \-1 or greater
|
|
than the remaining window width means to change attributes all the way to the
|
|
end of the current line.
|
|
The \fBwchgat\fR function generalizes this to any window;
|
|
the \fBmvwchgat\fR function does a cursor move before acting.
|
|
.PP
|
|
In these functions,
|
|
the color \fIpair\fP argument is a color-pair index
|
|
(as in the first argument of \fBinit_pair\fR, see \fBcurs_color\fR(3X)).
|
|
.\" ---------------------------------------------------------------------------
|
|
.SS Change window color
|
|
The routine \fBcolor_set\fR sets the current color of the given window to the
|
|
foreground/background combination described by the color \fIpair\fP parameter.
|
|
.\" ---------------------------------------------------------------------------
|
|
.SS Standout
|
|
.PP
|
|
The routine \fBstandout\fR is
|
|
the same as \fBattron(A_STANDOUT)\fR.
|
|
The routine \fBstandend\fR is the same
|
|
as \fBattrset(A_NORMAL)\fR or \fBattrset(0)\fR, that is, it turns off all
|
|
attributes.
|
|
.PP
|
|
X/Open does not mark these "restricted", because
|
|
.bP
|
|
they have well established legacy use, and
|
|
.bP
|
|
there is no ambiguity about the way the attributes
|
|
might be combined with a color pair.
|
|
.\" ---------------------------------------------------------------------------
|
|
.SH VIDEO ATTRIBUTES
|
|
The following video attributes, defined in \fB<curses.h>\fR, can be passed to
|
|
the routines \fBattron\fR, \fBattroff\fR, and \fBattrset\fR, or OR'd with the
|
|
characters passed to \fBaddch\fR (see \fBcurs_addch\fR(3X)).
|
|
.PP
|
|
.RS
|
|
.TS
|
|
l l
|
|
_ _ _
|
|
l l .
|
|
\fIName\fR \fIDescription\fR
|
|
\fBA_NORMAL\fR Normal display (no highlight)
|
|
\fBA_STANDOUT\fR Best highlighting mode of the terminal.
|
|
\fBA_UNDERLINE\fR Underlining
|
|
\fBA_REVERSE\fR Reverse video
|
|
\fBA_BLINK\fR Blinking
|
|
\fBA_DIM\fR Half bright
|
|
\fBA_BOLD\fR Extra bright or bold
|
|
\fBA_PROTECT\fR Protected mode
|
|
\fBA_INVIS\fR Invisible or blank mode
|
|
\fBA_ALTCHARSET\fR Alternate character set
|
|
\fBA_ITALIC\fR Italics (non-X/Open extension)
|
|
\fBA_CHARTEXT\fR Bit-mask to extract a character
|
|
.TE
|
|
.RE
|
|
.PP
|
|
These video attributes are supported by \fBattr_on\fP and related functions
|
|
(which also support the attributes recognized by \fBattron\fP, etc.):
|
|
.RS
|
|
.TS
|
|
l l
|
|
_ _ _
|
|
l l .
|
|
\fIName\fR \fIDescription\fR
|
|
\fBWA_HORIZONTAL\fR Horizontal highlight
|
|
\fBWA_LEFT\fR Left highlight
|
|
\fBWA_LOW\fR Low highlight
|
|
\fBWA_RIGHT\fR Right highlight
|
|
\fBWA_TOP\fR Top highlight
|
|
\fBWA_VERTICAL\fR Vertical highlight
|
|
.TE
|
|
.RE
|
|
.PP
|
|
The return values of many of these routines are not meaningful (they are
|
|
implemented as macro-expanded assignments and simply return their argument).
|
|
The SVr4 manual page claims (falsely) that these routines always return \fB1\fR.
|
|
.SH NOTES
|
|
These functions may be macros:
|
|
.sp
|
|
.RS
|
|
\fBattroff\fR, \fBwattroff\fR, \fBattron\fR, \fBwattron\fR,
|
|
\fBattrset\fR, \fBwattrset\fR, \fBstandend\fR and \fBstandout\fR.
|
|
.RE
|
|
.PP
|
|
Color pair values can only be OR'd with attributes if the pair
|
|
number is less than 256.
|
|
The alternate functions such as \fBcolor_set\fP can pass a color pair
|
|
value directly.
|
|
However, ncurses ABI 4 and 5 simply OR this value within the alternate functions.
|
|
You must use ncurses ABI 6 to support more than 256 color pairs.
|
|
.SH EXTENSIONS
|
|
.PP
|
|
This implementation provides the \fBA_ITALIC\fP attribute for terminals
|
|
which have the \fBenter_italics_mode\fP (\fBsitm\fP)
|
|
and \fBexit_italics_mode\fP (\fBritm\fP) capabilities.
|
|
Italics are not mentioned in X/Open Curses.
|
|
Unlike the other video attributes, \fBA_ITALIC\fP is unrelated
|
|
to the \fBset_attributes\fP capabilities.
|
|
This implementation makes the assumption that
|
|
\fBexit_attribute_mode\fP may also reset italics.
|
|
.PP
|
|
Each of the functions added by XSI Curses has a parameter \fIopts\fP,
|
|
which X/Open Curses still (after more than twenty years) documents
|
|
as reserved for future use, saying that it should be \fBNULL\fP.
|
|
This implementation uses that parameter in ABI 6 for the functions which
|
|
have a color-pair parameter to support \fIextended color pairs\fP:
|
|
.bP
|
|
For functions which modify the color, e.g.,
|
|
\fBwattr_set\fP,
|
|
if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
|
|
and used to set the color pair instead of the \fBshort\fP \fIpair\fP parameter.
|
|
.bP
|
|
For functions which retrieve the color, e.g.,
|
|
\fBwattr_get\fP,
|
|
if \fIopts\fP is set it is treated as a pointer to \fBint\fP,
|
|
and used to retrieve the color pair as an \fBint\fP value,
|
|
in addition
|
|
retrieving it via the standard pointer to \fBshort\fP parameter.
|
|
.PP
|
|
The remaining functions which have \fIopts\fP,
|
|
but do not manipulate color,
|
|
e.g., \fBwattr_on\fP and \fBwattr_off\fP
|
|
are not used by this implementation except to check that they are \fBNULL\fP.
|
|
.SH PORTABILITY
|
|
These functions are supported in the XSI Curses standard, Issue 4.
|
|
The standard defined the dedicated type for highlights,
|
|
\fBattr_t\fR, which was not defined in SVr4 curses.
|
|
The functions taking \fBattr_t\fR arguments were not supported under SVr4.
|
|
.PP
|
|
Very old versions of this library did not force an update of the screen
|
|
when changing the attributes.
|
|
Use \fBtouchwin\fR to force the screen to match the updated attributes.
|
|
.PP
|
|
The XSI Curses standard states that whether the traditional functions
|
|
\fBattron\fR/\fBattroff\fR/\fBattrset\fR can manipulate attributes other than
|
|
\fBA_BLINK\fR, \fBA_BOLD\fR, \fBA_DIM\fR, \fBA_REVERSE\fR, \fBA_STANDOUT\fR, or
|
|
\fBA_UNDERLINE\fR is "unspecified".
|
|
Under this implementation as well as
|
|
SVr4 curses, these functions correctly manipulate all other highlights
|
|
(specifically, \fBA_ALTCHARSET\fR, \fBA_PROTECT\fR, and \fBA_INVIS\fR).
|
|
.PP
|
|
XSI Curses added these entry points:
|
|
.sp
|
|
.RS
|
|
\fBattr_get\fR, \fBattr_on\fR,
|
|
\fBattr_off\fR, \fBattr_set\fR, \fBwattr_on\fR, \fBwattr_off\fR,
|
|
\fBwattr_get\fR, \fBwattr_set\fR
|
|
.RE
|
|
.PP
|
|
The new functions are intended to work with
|
|
a new series of highlight macros prefixed with \fBWA_\fR.
|
|
The older macros have direct counterparts in the newer set of names:
|
|
.PP
|
|
.RS
|
|
.ne 9
|
|
.TS
|
|
l l
|
|
_ _ _
|
|
l l .
|
|
\fIName\fR \fIDescription\fR
|
|
\fBWA_NORMAL\fR Normal display (no highlight)
|
|
\fBWA_STANDOUT\fR Best highlighting mode of the terminal.
|
|
\fBWA_UNDERLINE\fR Underlining
|
|
\fBWA_REVERSE\fR Reverse video
|
|
\fBWA_BLINK\fR Blinking
|
|
\fBWA_DIM\fR Half bright
|
|
\fBWA_BOLD\fR Extra bright or bold
|
|
\fBWA_ALTCHARSET\fR Alternate character set
|
|
.TE
|
|
.RE
|
|
.PP
|
|
The XSI curses standard specifies that each pair of corresponding \fBA_\fR
|
|
and \fBWA_\fR-using functions operates on the same current-highlight
|
|
information.
|
|
.PP
|
|
The XSI standard extended conformance level adds new highlights
|
|
\fBA_HORIZONTAL\fR, \fBA_LEFT\fR, \fBA_LOW\fR, \fBA_RIGHT\fR, \fBA_TOP\fR,
|
|
\fBA_VERTICAL\fR (and corresponding \fBWA_\fR macros for each).
|
|
As of August 2013,
|
|
no known terminal provides these highlights
|
|
(i.e., via the \fBsgr1\fP capability).
|
|
.SH RETURN VALUE
|
|
All routines return the integer \fBOK\fR on success, or \fBERR\fP on failure.
|
|
.PP
|
|
X/Open does not define any error conditions.
|
|
.PP
|
|
This implementation
|
|
.bP
|
|
returns an error if the window pointer is null.
|
|
.bP
|
|
returns an error if the color pair parameter
|
|
for \fBwcolor_set\fP is outside the range 0..COLOR_PAIRS\-1.
|
|
.bP
|
|
does not return an error if either of the parameters of \fBwattr_get\fP
|
|
used for retrieving attribute or color-pair values is \fBNULL\fP.
|
|
.PP
|
|
Functions with a "mv" prefix first perform a cursor movement using
|
|
\fBwmove\fP, and return an error if the position is outside the window,
|
|
or if the window pointer is null.
|
|
.SH SEE ALSO
|
|
.na
|
|
\fBcurses\fR(3X),
|
|
\fBcurs_addch\fR(3X),
|
|
\fBcurs_addstr\fR(3X),
|
|
\fBcurs_bkgd\fR(3X),
|
|
\fBcurs_printw\fR(3X),
|
|
\fBcurs_variables\fR(3X)
|