'\" t
.\"***************************************************************************
-.\" Copyright (c) 1998-2015,2016 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.47 2016/07/23 23:48:49 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
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.na
.hy 0
+.\" ---------------------------------------------------------------------------
.SH NAME
.\" attr_get
\fBattr_get\fR,
\fBwstandout\fR \- \fBcurses\fR character and window attribute control routines
.ad
.hy
+.\" ---------------------------------------------------------------------------
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
\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,
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
-The \fBattr_set\fP and \fBwattr_set\fP functions set the current attributes
+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.
-X/Open specified an additional parameter \fIopts\fP which is unused in
-all implementations.
.PP
-Use \fBattr_get\fP and \fBwattr_get\fP to retrieve attributes for
-the given window.
+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.
.\" ---------------------------------------------------------------------------
.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.
.PP
In these functions,
the color \fIpair\fP argument is a color-pair index
-(as in the first argument of \fIinit_pair\fR, see \fBcurs_color\fR(3X)).
-The \fBopts\fR argument is not
-presently used, but is reserved for the future (leave it \fBNULL\fR).
+(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.
-The parameter \fIopts\fP is reserved for future use;
-applications must supply a null pointer.
.\" ---------------------------------------------------------------------------
.SS Standout
.PP
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
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.
+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 is not
-defined in SVr4 curses.
-The functions taking \fBattr_t\fR arguments are
-not supported under SVr4.
+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".
+\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
-This implementation provides the \fBA_ITALIC\fP attribute for terminals
-which have the \fIenter_italics_mode\fP (sitm) and \fIexit_italics_mode\fP (ritm) capabilities.
-Italics are not mentioned in X/Open Curses.
-Unlike the other video attributes, \fBI_ITALIC\fP is unrelated
-to the \fIset_attributes\fP capabilities.
-This implementation makes the assumption that
-\fIexit_attribute_mode\fP may also reset italics.
-.PP
-XSI Curses added the new entry points, \fBattr_get\fR, \fBattr_on\fR,
+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.
-These are intended to work with
+\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
.TE
.RE
.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
+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,
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
.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
+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),