e18651243e
While I didn't plan another upgrade, This version incorporate fixes from kevans@ so let's upgrade to it
606 lines
22 KiB
Plaintext
606 lines
22 KiB
Plaintext
'\" t
|
|
.\"***************************************************************************
|
|
.\" Copyright 2018-2019,2020 Thomas E. Dickey *
|
|
.\" Copyright 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.66 2020/02/02 23:34:34 tom Exp $
|
|
.TH curs_attr 3X ""
|
|
.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
|
|
..
|
|
.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
|
|
The X/Open window attribute routines which \fIset\fP or \fIget\fP,
|
|
turn \fIon\fP or \fIoff\fP
|
|
are extensions of older routines
|
|
which assume that color pairs are OR'd into the attribute parameter.
|
|
These newer routines use similar names, because
|
|
X/Open simply added an underscore (\fB_\fP) for the newer names.
|
|
.PP
|
|
The \fBint\fP datatype used in the legacy routines is treated as if
|
|
it is the same size as \fBchtype\fP (used by \fBaddch\fP(3X)).
|
|
It holds the common video attributes (such as bold, reverse),
|
|
as well as a few bits for color.
|
|
Those bits correspond to the \fBA_COLOR\fP symbol.
|
|
The \fBCOLOR_PAIR\fP macro provides a value which can be OR'd into
|
|
the attribute parameter.
|
|
For example,
|
|
as long as that value fits into the \fBA_COLOR\fP mask,
|
|
then these calls produce similar results:
|
|
.NS
|
|
attrset(A_BOLD | COLOR_PAIR(\fIpair\fP));
|
|
attr_set(A_BOLD, \fIpair\fP, NULL);
|
|
.NE
|
|
.PP
|
|
However, if the value does not fit, then the \fBCOLOR_PAIR\fP macro
|
|
uses only the bits that fit.
|
|
For example, because in ncurses \fBA_COLOR\fP has eight (8) bits,
|
|
then \fBCOLOR_PAIR(\fP\fI259\fP\fB)\fP is 4
|
|
(i.e., 259 is 4 more than the limit 255).
|
|
.PP
|
|
The \fBPAIR_NUMBER\fP macro extracts a pair number from an \fBint\fP
|
|
(or \fBchtype\fP).
|
|
For example, the \fIinput\fP and \fIoutput\fP values in these statements
|
|
would be the same:
|
|
.NS
|
|
int value = A_BOLD | COLOR_PAIR(\fIinput\fP);
|
|
int \fIoutput\fP = PAIR_NUMBER(value);
|
|
.NE
|
|
.PP
|
|
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
|
|
\fBA_COLOR\fR Bit-mask to extract a color (legacy routines)
|
|
.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 HISTORY
|
|
X/Open Curses is largely based on SVr4 curses,
|
|
adding support for \*(``wide-characters\*('' (not specific to Unicode).
|
|
Some of the X/Open differences from SVr4 curses address the way
|
|
video attributes can be applied to wide-characters.
|
|
But aside from that, \fBattrset\fP and \fBattr_set\fP are similar.
|
|
SVr4 curses provided the basic features for manipulating video attributes.
|
|
However, earlier versions of curses provided a part of these features.
|
|
.PP
|
|
As seen in 2.8BSD, curses assumed 7-bit characters,
|
|
using the eighth bit of a byte to represent the \fIstandout\fP
|
|
feature (often implemented as bold and/or reverse video).
|
|
The BSD curses library provided functions \fBstandout\fP and \fBstandend\fP
|
|
which were carried along into X/Open Curses due to their pervasive use
|
|
in legacy applications.
|
|
.PP
|
|
Some terminals in the 1980s could support a variety of video attributes,
|
|
although the BSD curses library could do nothing with those.
|
|
System V (1983) provided an improved curses library.
|
|
It defined the \fBA_\fP symbols for use by applications to manipulate the
|
|
other attributes.
|
|
There are few useful references for the chronology.
|
|
.PP
|
|
Goodheart's book
|
|
\fIUNIX Curses Explained\fP (1991) describes SVr3 (1987),
|
|
commenting on several functions:
|
|
.bP
|
|
the \fBattron\fP, \fBattroff\fP, \fBattrset\fP functions
|
|
(and most of the functions found in SVr4 but not in BSD curses) were
|
|
introduced by System V,
|
|
.bP
|
|
the alternate character set feature with \fBA_ALTCHARSET\fP was
|
|
added in SVr2 and improved in SVr3 (by adding \fBacs_map[]\fP),
|
|
.bP
|
|
\fBstart_color\fP and related color-functions were introduced by System V.3.2,
|
|
.bP
|
|
pads, soft-keys were added in SVr3, and
|
|
.PP
|
|
Goodheart did not mention the background character or the \fBcchar_t\fP type.
|
|
Those are respectively SVr4 and X/Open features.
|
|
He did mention the \fBA_\fP constants, but did not indicate their values.
|
|
Those were not the same in different systems,
|
|
even for those marked as System V.
|
|
.PP
|
|
Different Unix systems used different sizes for the bit-fields in \fBchtype\fP
|
|
for \fIcharacters\fP and \fIcolors\fP, and took into account the different
|
|
integer sizes (32-bit versus 64-bit).
|
|
.PP
|
|
This table showing the number of bits for \fBA_COLOR\fP
|
|
and \fBA_CHARTEXT\fP
|
|
was gleaned from the curses header files for
|
|
various operating systems and architectures.
|
|
The inferred architecture and notes reflect
|
|
the format and size of the defined constants
|
|
as well as clues such as the alternate character set implementation.
|
|
A 32-bit library can be used on a 64-bit system,
|
|
but not necessarily the reverse.
|
|
.RS
|
|
.TS
|
|
l l l l l l
|
|
_ _ _ _ _ _
|
|
l l l l l l .
|
|
\fIYear\fR \fISystem\fR \fIArch\fP \fIColor\fR \fIChar\fR \fINotes\fR
|
|
1992 Solaris 5.2 32 6 17 SVr4 curses
|
|
1992 HPUX 9 32 no 8 SVr2 curses
|
|
1992 AIX 3.2 32 no 23 SVr2 curses
|
|
1994 OSF/1 r3 32 no 23 SVr2 curses
|
|
1995 HP-UX 10.00 32 6 16 SVr3 \*(``curses_colr\*(''
|
|
1995 HP-UX 10.00 32 6 8 SVr4, X/Open curses
|
|
1995 Solaris 5.4 32/64 7 16 X/Open curses
|
|
1996 AIX 4.2 32 7 16 X/Open curses
|
|
1996 OSF/1 r4 32 6 16 X/Open curses
|
|
1997 HP-UX 11.00 32 6 8 X/Open curses
|
|
2000 U/Win 32/64 7/31 16 uses \fBchtype\fP
|
|
.TE
|
|
.RE
|
|
.PP
|
|
Notes:
|
|
.RS 3
|
|
.PP
|
|
Regarding HP-UX,
|
|
.bP
|
|
HP-UX 10.20 (1996) added support for 64-bit PA-RISC processors in 1996.
|
|
.bP
|
|
HP-UX 10.30 (1997) marked \*(``curses_colr\*('' obsolete.
|
|
That version of curses was dropped with HP-UX 11.30 in 2006.
|
|
.PP
|
|
Regarding OSF/1 (and Tru64),
|
|
.bP
|
|
These used 64-bit hardware.
|
|
Like ncurses, the OSF/1 curses interface is not customized for 32-bit
|
|
and 64-bit versions.
|
|
.bP
|
|
Unlike other systems which evolved from AT&T code,
|
|
OSF/1 provided a new implementation for X/Open curses.
|
|
.PP
|
|
Regarding Solaris,
|
|
.bP
|
|
The initial release of Solaris was in 1992.
|
|
.bP
|
|
The \fIxpg4\fP (X/Open) curses was developed by MKS from 1990 to 1995.
|
|
Sun's copyright began in 1996.
|
|
.bP
|
|
Sun updated the X/Open curses interface
|
|
after 64-bit support was introduced in 1997,
|
|
but did not modify the SVr4 curses interface.
|
|
.PP
|
|
Regarding U/Win,
|
|
.bP
|
|
Development of the curses library began in 1991, stopped in 2000.
|
|
.bP
|
|
Color support was added in 1998.
|
|
.bP
|
|
The library uses only \fBchtype\fP (no \fBcchar_t\fP).
|
|
.RE
|
|
.PP
|
|
Once X/Open curses was adopted in the mid-1990s, the constraint of
|
|
a 32-bit interface with many colors and wide-characters for \fBchtype\fP
|
|
became a moot point.
|
|
The \fBcchar_t\fP structure (whose size and
|
|
members are not specified in X/Open Curses) could be extended as needed.
|
|
.PP
|
|
Other interfaces are rarely used now:
|
|
.bP
|
|
BSD curses was improved slightly in 1993/1994 using Keith Bostic's
|
|
modification to make the library 8-bit clean for \fBnvi\fP.
|
|
He moved \fIstandout\fP attribute to a structure member.
|
|
.IP
|
|
The resulting 4.4BSD curses was replaced by ncurses over the next ten years.
|
|
.bP
|
|
U/Win is rarely used now.
|
|
.\" ---------------------------------------------------------------------------
|
|
.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
|
|
XSI curses does not assign values to these symbols,
|
|
nor does it state whether or not they are related to the
|
|
similarly-named A_NORMAL, etc.:
|
|
.bP
|
|
The XSI curses standard specifies that each pair of corresponding \fBA_\fR
|
|
and \fBWA_\fR-using functions operates on the same current-highlight
|
|
information.
|
|
.bP
|
|
However, in some implementations, those symbols have unrelated values.
|
|
.IP
|
|
For example, the Solaris \fIxpg4\fP (X/Open) curses declares
|
|
\fBattr_t\fP to be an unsigned short integer (16-bits),
|
|
while \fBchtype\fP is a unsigned integer (32-bits).
|
|
The \fBWA_\fP symbols in this case are different from the \fBA_\fP symbols
|
|
because they are used for a smaller datatype which does not
|
|
represent \fBA_CHARTEXT\fP or \fBA_COLOR\fP.
|
|
.IP
|
|
In this implementation (as in many others), the values happen to be
|
|
the same because it simplifies copying information between
|
|
\fBchtype\fP and \fBcchar_t\fP variables.
|
|
.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)
|