curs_attr(3x) Library calls curs_attr(3x)
@@ -120,112 +105,109 @@
of the window. See curs_bkgd(3x) for functions which modify the
attributes used for erasing and clearing.
- Routines which do not have a WINDOW* parameter apply to stdscr. For
- example, attr_set is the stdscr variant of wattr_set.
-
-
There are two sets of functions:
- o functions for manipulating the window attributes and color:
+ o functions for manipulating the window attributes and color:
wattr_set and wattr_get.
- o functions for manipulating only the window attributes (not color):
+ o functions for manipulating only the window attributes (not color):
wattr_on and wattr_off.
- The wattr_set function sets the current attributes of the given window
+ The wattr_set function sets the current attributes of the given window
to attrs, with color specified by pair.
Use wattr_get to retrieve attributes for the given window.
- Use attr_on and wattr_on to turn on window attributes, i.e., values
+ Use attr_on and wattr_on to turn on window attributes, i.e., values
OR'd together in attr, without affecting other attributes. Use
attr_off and wattr_off to turn off window attributes, again values OR'd
together in attr, without affecting other attributes.
-
+ The X/Open window attribute routines which set or get, turn on or off
are extensions of older routines which assume that color pairs are OR'd
- into the attribute parameter. These newer routines use similar names,
+ into the attribute parameter. These newer routines use similar names,
because X/Open simply added an underscore (_) for the newer names.
The int datatype used in the legacy routines is treated as if it is the
- same size as chtype (used by addch(3x)). It holds the common video
- attributes (such as bold, reverse), as well as a few bits for color.
- Those bits correspond to the A_COLOR symbol. The COLOR_PAIR macro
- provides a value which can be OR'd into the attribute parameter. For
- example, as long as that value fits into the A_COLOR mask, then these
+ same size as chtype (used by addch(3x)). It holds the common video
+ attributes (such as bold, reverse), as well as a few bits for color.
+ Those bits correspond to the A_COLOR symbol. The COLOR_PAIR macro
+ provides a value which can be OR'd into the attribute parameter. For
+ example, as long as that value fits into the A_COLOR mask, then these
calls produce similar results:
attrset(A_BOLD | COLOR_PAIR(pair));
attr_set(A_BOLD, pair, NULL);
However, if the value does not fit, then the COLOR_PAIR macro uses only
- the bits that fit. For example, because in ncurses A_COLOR has eight
+ the bits that fit. For example, because in ncursesA_COLOR has eight
(8) bits, then COLOR_PAIR(259) is 4 (i.e., 259 is 4 more than the limit
255).
- The PAIR_NUMBER macro extracts a pair number from an int (or chtype).
- For example, the input and output values in these statements would be
+ The PAIR_NUMBER macro extracts a pair number from an int (or chtype).
+ For example, the input and output values in these statements would be
the same:
int value = A_BOLD | COLOR_PAIR(input);
int output = PAIR_NUMBER(value);
- The attrset routine is a legacy feature predating SVr4 curses but kept
- in X/Open Curses for the same reason that SVr4 curses kept it:
+ The attrset routine is a legacy feature predating SVr4 curses but kept
+ in X/Open Curses for the same reason that SVr4 curses kept it:
compatibility.
- The remaining attr* functions operate exactly like the corresponding
- attr_* functions, except that they take arguments of type int rather
+ The remaining attr* functions operate exactly like the corresponding
+ attr_* functions, except that they take arguments of type int rather
than attr_t.
- There is no corresponding attrget function as such in X/Open Curses,
- although ncurses provides getattrs (see curs_legacy(3x)).
+ There is no corresponding attrget function as such in X/Open Curses,
+ although ncurses provides getattrs (see curs_legacy(3x)).
-
The routine chgat changes the attributes of a given number of
- characters starting at the current cursor location of stdscr. It does
+ characters starting at the current cursor location of stdscr. 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 wchgat
- function generalizes this to any window; the mvwchgat function does a
+ of -1 or greater than the remaining window width means to change
+ attributes all the way to the end of the current line. The wchgat
+ function generalizes this to any window; the mvwchgat function does a
cursor move before acting.
- In these functions, the color pair argument is a color-pair index (as
+ In these functions, the color pair argument is a color pair index (as
in the first argument of init_pair, see curs_color(3x)).
-
The routine color_set sets the current color of the given window to the
- foreground/background combination described by the color pair
+ foreground/background combination described by the color pair
parameter.
- The routine standout is the same as attron(A_STANDOUT). The routine
- standend is the same as attrset(A_NORMAL) or attrset(0), that is, it
+ The routine standout is the same as attron(A_STANDOUT). The routine
+ standend is the same as attrset(A_NORMAL) or attrset(0), that is, it
turns off all attributes.
X/Open does not mark these "restricted", because
o they have well established legacy use, and
- o there is no ambiguity about the way the attributes might be
+ o there is no ambiguity about the way the attributes might be
combined with a color pair.
The following video attributes, defined in <curses.h>, can be passed to
- the routines attron, attroff, and attrset, or OR'd with the characters
+ the routines attron, attroff, and attrset, or OR'd with the characters
passed to addch (see curs_addch(3x)).
NameDescription
-----------------------------------------------------------------
A_NORMAL Normal display (no highlight)
- A_STANDOUT Best highlighting mode of the terminal.
+ A_STANDOUT Best highlighting mode of the terminal
A_UNDERLINE Underlining
A_REVERSE Reverse video
A_BLINK Blinking
@@ -238,11 +220,11 @@
A_CHARTEXT Bit-mask to extract a character
A_COLOR Bit-mask to extract a color (legacy routines)
- These video attributes are supported by attr_on and related functions
+ These video attributes are supported by attr_on and related functions
(which also support the attributes recognized by attron, etc.):
NameDescription
- -----------------------------------------
+ -----------------------------------------------------------------
WA_HORIZONTAL Horizontal highlight
WA_LEFT Left highlight
WA_LOW Low highlight
@@ -250,9 +232,9 @@
WA_TOP Top highlight
WA_VERTICAL Vertical highlight
- 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
+ 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 1.
@@ -265,13 +247,13 @@
o returns an error if the window pointer is null.
- o returns an error if the color pair parameter for wcolor_set is
+ o returns an error if the color pair parameter for wcolor_set is
outside the range 0..COLOR_PAIRS-1.
- o does not return an error if either of the parameters of wattr_get
- used for retrieving attribute or color-pair values is NULL.
+ o does not return an error if either of the parameters of wattr_get
+ used for retrieving attribute or color pair values is NULL.
- Functions with a "mv" prefix first perform a cursor movement using
+ Functions with a "mv" prefix first perform a cursor movement using
wmove, and return an error if the position is outside the window, or if
the window pointer is null.
@@ -279,58 +261,58 @@
These functions may be macros:
- attroff, wattroff, attron, wattron, attrset, wattrset, standend
+ attroff, wattroff, attron, wattron, attrset, wattrset, standend
and standout.
- Color pair values can only be OR'd with attributes if the pair number
+ Color pair values can only be OR'd with attributes if the pair number
is less than 256. The alternate functions such as color_set 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
+ 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.
This implementation provides the A_ITALIC attribute for terminals which
- have the enter_italics_mode (sitm) and exit_italics_mode (ritm)
- capabilities. Italics are not mentioned in X/Open Curses. Unlike the
- other video attributes, A_ITALIC is unrelated to the set_attributes
- capabilities. This implementation makes the assumption that
+ have the enter_italics_mode (sitm) and exit_italics_mode (ritm)
+ capabilities. Italics are not mentioned in X/Open Curses. Unlike the
+ other video attributes, A_ITALIC is unrelated to the set_attributes
+ capabilities. This implementation makes the assumption that
exit_attribute_mode may also reset italics.
- Each of the functions added by XSI Curses has a parameter opts, which
- X/Open Curses still (after more than twenty years) documents as
+ Each of the functions added by XSI Curses has a parameter opts, which
+ X/Open Curses still (after more than twenty years) documents as
reserved for future use, saying that it should be NULL. This
- implementation uses that parameter in ABI 6 for the functions which
- have a color-pair parameter to support extendedcolorpairs:
+ implementation uses that parameter in ABI 6 for the functions which
+ have a color pair parameter to support extendedcolorpairs:
o For functions which modify the color, e.g., wattr_set and wattr_on,
- if opts is set it is treated as a pointer to int, and used to set
+ if opts is set it is treated as a pointer to int, and used to set
the color pair instead of the shortpair parameter.
o For functions which retrieve the color, e.g., wattr_get, if opts is
- set it is treated as a pointer to int, and used to retrieve the
- color pair as an int value, in addition to retrieving it via the
+ set it is treated as a pointer to int, and used to retrieve the
+ color pair as an int value, in addition to retrieving it via the
standard pointer to short parameter.
- o For functions which turn attributes off, e.g., wattr_off, the opts
+ o For functions which turn attributes off, e.g., wattr_off, the opts
parameter is ignored except except to check that it is NULL.
These functions are described in the XSI Curses standard, Issue 4. The
- standard defined the dedicated type for highlights, attr_t, which was
+ standard defined the dedicated type for highlights, attr_t, which was
not defined in SVr4 curses. The functions taking attr_t arguments were
not supported under SVr4.
Very old versions of this library did not force an update of the screen
- when changing the attributes. Use touchwin to force the screen to
+ when changing the attributes. Use touchwin to force the screen to
match the updated attributes.
- The XSI Curses standard states that whether the traditional functions
- attron/attroff/attrset can manipulate attributes other than A_BLINK,
- A_BOLD, A_DIM, A_REVERSE, A_STANDOUT, or A_UNDERLINE is "unspecified".
- Under this implementation as well as SVr4 curses, these functions
- correctly manipulate all other highlights (specifically, A_ALTCHARSET,
+ The XSI Curses standard states that whether the traditional functions
+ attron/attroff/attrset can manipulate attributes other than A_BLINK,
+ A_BOLD, A_DIM, A_REVERSE, A_STANDOUT, or A_UNDERLINE is "unspecified".
+ Under this implementation as well as SVr4 curses, these functions
+ correctly manipulate all other highlights (specifically, A_ALTCHARSET,
A_PROTECT, and A_INVIS).
XSI Curses added these entry points:
@@ -338,133 +320,135 @@
attr_get, attr_on, attr_off, attr_set, wattr_on, wattr_off,
wattr_get, wattr_set
- The new functions are intended to work with a new series of highlight
+ The new functions are intended to work with a new series of highlight
macros prefixed with WA_. The older macros have direct counterparts in
the newer set of names:
NameDescription
- ------------------------------------------------------------
+ -----------------------------------------------------------------
WA_NORMAL Normal display (no highlight)
- WA_STANDOUT Best highlighting mode of the terminal.
+ WA_STANDOUT Best highlighting mode of the terminal
WA_UNDERLINE Underlining
WA_REVERSE Reverse video
WA_BLINK Blinking
WA_DIM Half bright
WA_BOLD Extra bright or bold
+
WA_ALTCHARSET Alternate character set
- XSI curses does not assign values to these symbols, nor does it state
+ 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.:
- o The XSI curses standard specifies that each pair of corresponding
- A_ and WA_-using functions operates on the same current-highlight
+ o The XSI curses standard specifies that each pair of corresponding
+ A_ and WA_-using functions operates on the same current-highlight
information.
- o However, in some implementations, those symbols have unrelated
+ o However, in some implementations, those symbols have unrelated
values.
For example, the Solaris xpg4 (X/Open) curses declares attr_t to be
- an unsigned short integer (16-bits), while chtype is a unsigned
+ an unsigned short integer (16-bits), while chtype is a unsigned
integer (32-bits). The WA_ symbols in this case are different from
- the A_ symbols because they are used for a smaller datatype which
+ the A_ symbols because they are used for a smaller datatype which
does not represent A_CHARTEXT or A_COLOR.
In this implementation (as in many others), the values happen to be
- the same because it simplifies copying information between chtype
+ the same because it simplifies copying information between chtype
and cchar_t variables.
- o Because ncurses's attr_t can hold a color pair (in the A_COLOR
- field), a call to wattr_on, wattr_off, or wattr_set may alter the
- window's color. If the color pair information in the attribute
+ o Because ncurses's attr_t can hold a color pair (in the A_COLOR
+ field), a call to wattr_on, wattr_off, or wattr_set may alter the
+ window's color. If the color pair information in the attribute
parameter is zero, no change is made to the window's color.
This is consistent with SVr4 curses; X/Open Curses does not specify
this.
The XSI standard extended conformance level adds new highlights
- A_HORIZONTAL, A_LEFT, A_LOW, A_RIGHT, A_TOP, A_VERTICAL (and
- corresponding WA_ macros for each). As of August 2013, no known
+ A_HORIZONTAL, A_LEFT, A_LOW, A_RIGHT, A_TOP, A_VERTICAL (and
+ corresponding WA_ macros for each). As of August 2013, no known
terminal provides these highlights (i.e., via the sgr1 capability).
- 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, attrset and attr_set
- are similar. SVr4 curses provided the basic features for manipulating
- video attributes. However, earlier versions of curses provided a part
+ 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, attrset and attr_set
+ are similar. SVr4 curses provided the basic features for manipulating
+ video attributes. However, earlier versions of curses provided a part
of these features.
- As seen in 2.8BSD, curses assumed 7-bit characters, using the eighth
- bit of a byte to represent the standout feature (often implemented as
- bold and/or reverse video). The BSD curses library provided functions
- standout and standend which were carried along into X/Open Curses due
+ As seen in 2.8BSD, curses assumed 7-bit characters, using the eighth
+ bit of a byte to represent the standout feature (often implemented as
+ bold and/or reverse video). The BSD curses library provided functions
+ standout and standend which were carried along into X/Open Curses due
to their pervasive use in legacy applications.
- 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 A_ symbols for use by applications to manipulate the other
+ 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 A_ symbols for use by applications to manipulate the other
attributes. There are few useful references for the chronology.
- Goodheart's book UNIXCursesExplained (1991) describes SVr3 (1987),
+ Goodheart's book UNIXCursesExplained (1991) describes SVr3 (1987),
commenting on several functions:
- o the attron, attroff, attrset functions (and most of the functions
+ o the attron, attroff, attrset functions (and most of the functions
found in SVr4 but not in BSD curses) were introduced by System V,
- o the alternate character set feature with A_ALTCHARSET was added in
+ o the alternate character set feature with A_ALTCHARSET was added in
SVr2 and improved in SVr3 (by adding acs_map[]),
- ostart_color and related color-functions were introduced by System
+ ostart_color and related color-functions were introduced by System
V.3.2,
o pads, soft-keys were added in SVr3, and
Goodheart did not mention the background character or the cchar_t type.
Those are respectively SVr4 and X/Open features. He did mention the A_
- constants, but did not indicate their values. Those were not the same
+ constants, but did not indicate their values. Those were not the same
in different systems, even for those marked as System V.
- Different Unix systems used different sizes for the bit-fields in
- chtype for characters and colors, and took into account the different
+ Different Unix systems used different sizes for the bit-fields in
+ chtype for characters and colors, and took into account the different
integer sizes (32-bit versus 64-bit).
- This table showing the number of bits for A_COLOR and A_CHARTEXT 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
+ This table showing the number of bits for A_COLOR and A_CHARTEXT 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.
- YearSystemArchColorCharNotes
- ----------------------------------------------------------------
- 1992 Solaris 5.2 32 6 17 SVr4 curses
- 1992 HP-UX 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 chtype
+ Bits
+ YearSystemArchColorCharNotes
+ ------------------------------------------------------------------------
+ 1992 Solaris 5.2 32 6 17 SVr4 curses
+ 1992 HP-UX 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 chtype
Notes:
Regarding HP-UX,
- o HP-UX 10.20 (1996) added support for 64-bit PA-RISC processors
+ o HP-UX 10.20 (1996) added support for 64-bit PA-RISC processors
in 1996.
- o HP-UX 10.30 (1997) marked "curses_colr" obsolete. That version
+ o HP-UX 10.30 (1997) marked "curses_colr" obsolete. That version
of curses was dropped with HP-UX 11.30 in 2006.
Regarding OSF/1 (and Tru64),
- o These used 64-bit hardware. Like ncurses, the OSF/1 curses
+ o These used 64-bit hardware. Like ncurses, the OSF/1 curses
interface is not customized for 32-bit and 64-bit versions.
o Unlike other systems which evolved from AT&T code, OSF/1
@@ -478,30 +462,30 @@
Sun's copyright began in 1996.
o Sun updated the X/Open curses interface after 64-bit support was
- introduced in 1997, but did not modify the SVr4 curses
+ introduced in 1997, but did not modify the SVr4 curses
interface.
Regarding U/Win,
- o Development of the curses library began in 1991, stopped in
+ o Development of the curses library began in 1991, stopped in
2000.
o Color support was added in 1998.
o The library uses only chtype (no cchar_t).
- Once X/Open curses was adopted in the mid-1990s, the constraint of a
+ Once X/Open curses was adopted in the mid-1990s, the constraint of a
32-bit interface with many colors and wide-characters for chtype became
- a moot point. The cchar_t structure (whose size and members are not
+ a moot point. The cchar_t structure (whose size and members are not
specified in X/Open Curses) could be extended as needed.
Other interfaces are rarely used now:
- o BSD curses was improved slightly in 1993/1994 using Keith Bostic's
- modification to make the library 8-bit clean for nvi(1). He moved
+ o BSD curses was improved slightly in 1993/1994 using Keith Bostic's
+ modification to make the library 8-bit clean for nvi(1). He moved
standout attribute to a structure member.
- The resulting 4.4BSD curses was replaced by ncurses over the next
+ The resulting 4.4BSD curses was replaced by ncurses over the next
ten years.
o U/Win is rarely used now.
@@ -513,7 +497,7 @@
-ncurses 6.4 2023-11-25 curs_attr(3x)
+ncurses 6.4 2024-03-02 curs_attr(3x)