'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2016,2017 Free Software Foundation, Inc. *
+.\" 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_attr.3x,v 1.61 2017/11/18 23:47:37 tom Exp $
+.\" $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
without affecting other attributes.
.\" ---------------------------------------------------------------------------
.SS Legacy window attributes
-Most of the window attribute routines are extensions of older routines
+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 older routines use the same name, omitting an underscore (\fB_\fP).
-
+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.
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
+X/Open does not mark these \*(``restricted\*('', because
.bP
they have well established legacy use, and
.bP
\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
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.
+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
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 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
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,
+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.
+Development of the curses library began in 1991, stopped in 2000.
.bP
Color support was added in 1998.
.bP
.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
+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:
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".
+\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).
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
+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.
.\" ---------------------------------------------------------------------------