- curses supports color attributes on terminals with that capability. To
- use these routines start_color must be called, usually right after
- initscr. Colors are always used in pairs (referred to as color pairs).
- A color pair consists of a foreground color (for characters) and a
- background color (for the blank field on which the characters are
- displayed). A programmer initializes a color pair with the routine
- init_pair. After it has been initialized, COLOR_PAIR(n) can be used to
- convert the pair to a video attribute.
-
- If a terminal is capable of redefining colors, the programmer can use
- the routine init_color to change the definition of a color. The
- routines has_colors and can_change_color return TRUE or FALSE,
- depending on whether the terminal has color capabilities and whether
- the programmer can change the colors. The routine color_content allows
- a programmer to extract the amounts of red, green, and blue components
- in an initialized color. The routine pair_content allows a programmer
- to find out how a given color pair is currently defined.
+ curses supports color attributes on terminals with that capability.
+ Call start_color (typically right after initscr(3x)) to enable this
+ feature. Colors are always used in pairs. A colorpair couples a
+ foreground color for characters with a background color for the blank
+ field on which characters are rendered. init_pair initializes a color
+ pair. The macro COLOR_PAIR(n) can then convert the pair to a video
+ attribute.
+
+ If a terminal has the relevant capability, init_color permits
+ (re)definition of a color. has_colors and can_change_color return TRUE
+ or FALSE, depending on whether the terminal has color capability and
+ whether the programmer can change the colors. color_content permits
+ extraction of the red, green, and blue components of an initialized
+ color. pair_content permits discovery of a color pair's current
+ definition.
-
+ curses combines the following data to render a character cell. Any of
+ them can include color information.
- o per-character video attributes (e.g., via waddch),
+ ocurses character attributes, as from waddch(3x) or wadd_wch(3x)
- o the window attribute (e.g., by wattrset), and
+ o window attributes, as from wattrset(3x) or wattr_set(3x)
- o the background character (e.g., wbkgdset).
+ o window background character attributes, as from wbkgdset(3x) or
+ wbkgrndset(3x)
- Per-character and window attributes are usually set by a parameter
- containing video attributes including a color pair value. Some
- functions such as wattr_set use a separate parameter which is the color
- pair number.
+ Per-character and window attributes are usually set through a function
+ parameter containing attributes including a color pair value. Some
+ functions, such as wattr_set, use a separate color pair number
+ parameter.
- The background character is a special case: it includes a character
- value, just as if it were passed to waddch.
+ The background character is a special case: it includes a character
+ code, just as if it were passed to waddch.
- The curses library does the actual work of combining these color pairs
+ The curses library does the actual work of combining these color pairs
in an internal function called from waddch:
o If the parameter passed to waddch is blank, and it uses the special
@@ -130,18 +133,18 @@
ocurses next checks the window attribute.
- o If the window attribute does not use color pair 0, curses uses
+ o If the window attribute does not use color pair 0, curses uses
the color pair from the window attribute.
o Otherwise, curses uses the background character.
- o If the parameter passed to waddch is notblank, or it does not use
- the special color pair 0, curses prefers the color pair from the
- parameter, if it is nonzero. Otherwise, it tries the window
+ o If the parameter passed to waddch is notblank, or it does not use
+ the special color pair 0, curses prefers the color pair from the
+ parameter, if it is nonzero. Otherwise, it tries the window
attribute next, and finally the background character.
- Some curses functions such as wprintw call waddch. Those do not
- combine its parameter with a color pair. Consequently those calls use
+ Some curses functions such as wprintw call waddch. Those do not
+ combine its parameter with a color pair. Consequently those calls use
only the window attribute or the background character.
@@ -159,20 +162,27 @@
COLOR_CYANCOLOR_WHITE
- Some terminals support more than the eight (8) "ANSI" colors. There
+ Some terminals support more than the eight (8) "ANSI" colors. There
are no standard names for those additional colors.
- is initialized by start_color to the maximum number of colors the
+ is initialized by start_color to the maximum number of colors the
terminal can support.
- is initialized by start_color to the maximum number of color pairs the
- terminal can support.
+ is initialized by start_color to the maximum number of color pairs the
+ terminal can support. Often, its value is the product COLORS x COLORS,
+ but this is not always true.
+
+ o A few terminals use the HLS color space (see start_color below),
+ ignoring this rule; and
+
+ o terminals supporting a large number of colors are limited to the
+ number of color pairs that a signedshort value can represent.
The functions marked as extensions were designed for ncurses(3x), and
- are not found in SVr4 curses, 4.4BSD curses, or any other previous
- version of curses.
+ are not found in SVr4 curses, 4.4BSD curses, or any other previous
+ curses implementation.
- This implementation satisfies XSI Curses's minimum maximums for COLORS
- and COLOR_PAIRS.
+ Applications employing ncurses extensions should condition their use on
+ the visibility of the NCURSES_VERSION preprocessor macro.
+
+ This implementation satisfies X/Open Curses's minimum maximums for
+ COLORS and COLOR_PAIRS.
The init_pair routine accepts negative values of foreground and
- background color to support the use_default_colors(3x) extension, but
+ background color to support the use_default_colors(3x) extension, but
only if that routine has been first invoked.
The assumption that COLOR_BLACK is the default background color for all
- terminals can be modified using the assume_default_colors(3x)
+ terminals can be modified using the assume_default_colors(3x)
extension.
- This implementation checks the pointers, e.g., for the values returned
- by color_content and pair_content, and will treat those as optional
+ This implementation checks the pointers, e.g., for the values returned
+ by color_content and pair_content, and will treat those as optional
parameters when null.
- X/Open Curses does not specify a limit for the number of colors and
+ X/Open Curses does not specify a limit for the number of colors and
color pairs which a terminal can support. However, in its use of short
- for the parameters, it carries over SVr4's implementation detail for
+ for the parameters, it carries over SVr4's implementation detail for
the compiled terminfo database, which uses signed 16-bit numbers. This
- implementation provides extended versions of those functions which use
- short parameters, allowing applications to use larger color- and pair-
+ implementation provides extended versions of those functions which use
+ short parameters, allowing applications to use larger color- and pair-
numbers.
The reset_color_pairs function is an extension of ncurses.
@@ -479,13 +492,13 @@
SVr3.2 introduced color support to curses in 1987.
- SVr4 made internal changes, e.g., moving the storage for the color
- state from SP (the SCREEN structure) to cur_term (the TERMINAL
+ SVr4 made internal changes, e.g., moving the storage for the color
+ state from SP (the SCREEN structure) to cur_term (the TERMINAL
structure), but provided the same set of library functions.
- SVr4 curses limits the number of color pairs to 64, reserving color
- pair zero (0) as the terminal's initial uncolored state. This limit
- arises because the color pair information is a bitfield in the chtype
+ SVr4 curses limits the number of color pairs to 64, reserving color
+ pair zero (0) as the terminal's initial uncolored state. This limit
+ arises because the color pair information is a bitfield in the chtype
data type (denoted by A_COLOR).
Other implementations of curses had different limits:
@@ -498,35 +511,35 @@
o X/Open Curses (1992-present) added a new structure cchar_t to store
the character, attributes and color pair values, allowing increased
- range of color pairs. Both color pairs and color-values used a
+ range of color pairs. Both color pairs and color-values used a
signed short, limiting values to 15 bits.
- oncurses (1992-present) uses eight bits for A_COLOR in chtype
+ oncurses (1992-present) uses eight bits for A_COLOR in chtype
values.
- Version 5.3 provided a wide-character interface (2002), but left
+ Version 5.3 provided a wide-character interface (2002), but left
color pairs as part of the attributes-field.
Since version 6 (2015), ncurses uses a separate int for color pairs
in the cchar_t values. When those color pair values fit in 8 bits,
- ncurses allows color pairs to be manipulated via the functions
+ ncurses allows color pairs to be manipulated via the functions
using chtype values.
- o NetBSD curses used 6 bits from 2000 (when colors were first
- supported) until 2004. At that point, NetBSD changed to use 10
- bits. As of 2021, that size is unchanged. Like ncurses before
- version 6, the NetBSD color pair information is stored in the
- attributes field of cchar_t, limiting the number of color pairs by
+ o NetBSD curses used 6 bits from 2000 (when colors were first
+ supported) until 2004. At that point, NetBSD changed to use 10
+ bits. As of 2021, that size is unchanged. Like ncurses before
+ version 6, the NetBSD color pair information is stored in the
+ attributes field of cchar_t, limiting the number of color pairs by
the size of the bitfield.