- 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
@@ -128,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.
@@ -157,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.
@@ -182,7 +194,7 @@
routine right after initscr. start_color does this:
o It initializes two global variables, COLORS and COLOR_PAIRS
- (respectively defining the maximum number of colors and color-pairs
+ (respectively defining the maximum number of colors and color pairs
the terminal can support).
o It initializes the special color pair 0 to the default foreground
@@ -213,7 +225,7 @@
alter the internal table along with the terminal's color.
These limits apply to color values and color pairs. Values outside
- these limits are not legal, and may result in a runtime error:
+ these limits are not valid, and may result in a runtime error:
oCOLORS corresponds to the terminal database's max_colors
capability, (see terminfo(5)).
@@ -227,7 +239,7 @@
oCOLOR_PAIRS corresponds to the terminal database's max_pairs
capability, (see terminfo(5)).
- o legal color pair values are in the range 1 to COLOR_PAIRS-1,
+ o valid color pair values are in the range 1 to COLOR_PAIRS-1,
inclusive.
o color pair 0 is special; it denotes "no color".
@@ -253,23 +265,23 @@
- The init_pair routine changes the definition of a color-pair. It takes
- three arguments: the number of the color-pair to be changed, the
+ The init_pair routine changes the definition of a color pair. It takes
+ three arguments: the number of the color pair to be changed, the
foreground color number, and the background color number. For portable
applications:
- o The first argument must be a legal color pair value. If default
+ o The first argument must be a valid color pair value. If default
colors are used (see use_default_colors(3x)) the upper limit is
adjusted to allow for extra pairs which use a default color in
foreground and/or background.
- o The second and third arguments must be legal color values.
+ o The second and third arguments must be valid color values.
- If the color-pair was previously initialized, the screen is refreshed
- and all occurrences of that color-pair are changed to the new
+ If the color pair was previously initialized, the screen is refreshed
+ and all occurrences of that color pair are changed to the new
definition.
- As an extension, ncurses allows you to set color pair 0 via the
+ As an extension, ncurses allows you to set color pair 0 via the
assume_default_colors(3x) routine, or to specify the use of default
colors (color number -1) if you first invoke the use_default_colors(3x)
routine.
@@ -277,8 +289,8 @@
Because init_pair uses signed shorts for its parameters, that limits
- color-pairs and color-values to 32767 on modern hardware. The
- extension init_extended_pair uses ints for the color-pair and color-
+ color pairs and color-values to 32767 on modern hardware. The
+ extension init_extended_pair uses ints for the color pair and color-
value, allowing a larger number of colors to be supported.
@@ -287,7 +299,7 @@
four arguments: the number of the color to be changed followed by three
RGB values (for the amounts of red, green, and blue components).
- o The first argument must be a legal color value; default colors are
+ o The first argument must be a valid color value; default colors are
not allowed here. (See the section Colors for the default color
index.)
@@ -313,7 +325,7 @@
storing the information about the amounts of red, green, and blue
components in the given color.
- o The first argument must be a legal color value, i.e., 0 through
+ o The first argument must be a valid color value, i.e., 0 through
COLORS-1, inclusive.
o The values that are stored at the addresses pointed to by the last
@@ -331,11 +343,11 @@
The pair_content routine allows programmers to find out what colors a
- given color-pair consists of. It requires three arguments: the color-
+ given color pair consists of. It requires three arguments: the color
pair number, and two addresses of shorts for storing the foreground and
the background color numbers.
- o The first argument must be a legal color value, i.e., in the range
+ o The first argument must be a valid color value, i.e., in the range
1 through COLOR_PAIRS-1, inclusive.
o The values that are stored at the addresses pointed to by the
@@ -345,58 +357,59 @@
Because pair_content uses signed shorts for its parameters, that limits
- color-pair and color-values to 32767 on modern hardware. The extension
+ color pair and color-values to 32767 on modern hardware. The extension
extended_pair_content uses ints for the color pair and for returning
the foreground and background colors, allowing a larger number of
colors to be supported.
- The extension reset_color_pairs tells ncurses to discard all of the
- color-pair information which was set with init_pair. It also touches
+ The extension reset_color_pairs tells ncurses to discard all of the
+ color pair information which was set with init_pair. It also touches
the current- and standard-screens, allowing an application to switch
color palettes rapidly.
-
+ COLOR_PAIR(n) converts a color pair number to an attribute. Attributes
+ can hold color pairs in the range 0 to 255. If you need a color pair
+ larger than that, you must use functions such as attr_set (which pass
+ the color pair as a separate parameter) rather than the legacy
+ functions such as attrset.
-
- Its inverse COLOR_PAIR(n) converts a color pair number to an attribute.
- Attributes can hold color pairs in the range 0 to 255. If you need a
- color pair larger than that, you must use functions such as attr_set
- (which pass the color pair as a separate parameter) rather than the
- legacy functions such as attrset.
+
+ PAIR_NUMBER(attr) extracts the color information from its attr
+ parameter and returns it as a color pair number; it is the inverse
+ operation of COLOR_PAIR.
The routines can_change_color and has_colors return TRUE or FALSE.
- All other routines return the integer ERR upon failure and an OK (SVr4
- specifies only "an integer value other than ERR") upon successful
+ All other routines return the integer ERR upon failure and an OK (SVr4
+ specifies only "an integer value other than ERR") upon successful
completion.
- X/Open defines no error conditions. SVr4 does document some error
+ X/Open defines no error conditions. SVr4 does document some error
conditions which apply in general:
o This implementation will return ERR on attempts to use color values
- outside the range 0 to COLORS-1 (except for the default colors
- extension), or use color pairs outside the range 0 to
+ outside the range 0 to COLORS-1 (except for the default colors
+ extension), or use color pairs outside the range 0 to
COLOR_PAIRS-1.
Color values used in init_color must be in the range 0 to 1000.
- An error is returned from all functions if the terminal has not
+ An error is returned from all functions if the terminal has not
been initialized.
- An error is returned from secondary functions such as init_pair if
+ An error is returned from secondary functions such as init_pair if
start_color was not called.
- o SVr4 does much the same, except that it returns ERR from
- pair_content if the pair was not initialized using init_pairs and
- it returns ERR from color_content if the terminal does not support
+ o SVr4 does much the same, except that it returns ERR from
+ pair_content if the pair was not initialized using init_pairs and
+ it returns ERR from color_content if the terminal does not support
changing colors.
This implementation does not return ERR for either case.
@@ -405,7 +418,7 @@
init_color
returns an error if the terminal does not support this feature,
- e.g., if the initialize_color capability is absent from the
+ e.g., if the initialize_color capability is absent from the
terminal description.
start_color
@@ -413,88 +426,45 @@
- In the ncurses implementation, there is a separate color activation
- flag, color palette, color pairs table, and associated COLORS and
- COLOR_PAIRS counts for each screen; the start_color function only
- affects the current screen. The SVr4/XSI interface is not really
- designed with this in mind, and historical implementations may use a
+ In the ncurses implementation, there is a separate color activation
+ flag, color palette, color pairs table, and associated COLORS and
+ COLOR_PAIRS counts for each screen; the start_color function only
+ affects the current screen. The SVr4/XSI interface is not really
+ designed with this in mind, and historical implementations may use a
single shared color palette.
- Setting an implicit background color via a color pair affects only
- character cells that a character write operation explicitly touches.
- To change the background color used when parts of a window are blanked
+ Setting an implicit background color via a color pair affects only
+ character cells that a character write operation explicitly touches.
+ To change the background color used when parts of a window are blanked
by erasing or scrolling operations, see curs_bkgd(3x).
- Several caveats apply on older x86 machines (e.g., i386, i486) with
+ Several caveats apply on older x86 machines (e.g., i386, i486) with
VGA-compatible graphics:
- o COLOR_YELLOW is actually brown. To get yellow, use COLOR_YELLOW
+ o COLOR_YELLOW is actually brown. To get yellow, use COLOR_YELLOW
combined with the A_BOLD attribute.
- o The A_BLINK attribute should in theory cause the background to go
+ o The A_BLINK attribute should in theory cause the background to go
bright. This often fails to work, and even some cards for which it
- mostly works (such as the Paradise and compatibles) do the wrong
- thing when you try to set a bright "yellow" background (you get a
+ mostly works (such as the Paradise and compatibles) do the wrong
+ thing when you try to set a bright "yellow" background (you get a
blinking yellow foreground instead).
o Color RGB values are not settable.
-
- 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
- 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
- data type (denoted by A_COLOR).
-
- Other implementations of curses had different limits:
-
- o PCCurses (1987-1990) provided for only eight (8) colors.
-
- o PDCurses (1992-present) inherited the 8-color limitation from
- PCCurses, but changed this to 256 in version 2.5 (2001), along with
- changing chtype from 16-bits to 32-bits.
-
- 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
- signed short, limiting values to 15 bits.
-
- o ncurses (1992-present) uses eight bits for A_COLOR in chtype
- values.
-
- 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
- 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
- the size of the bitfield.
+
+ The functions marked as extensions were designed for ncurses(3x), and
+ are not found in SVr4 curses, 4.4BSD curses, or any other previous
+ curses implementation.
- 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.
-
-
-
- This implementation satisfies XSI Curses's minimum maximums for COLORS
- and COLOR_PAIRS.
+ 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
@@ -516,16 +486,60 @@
short parameters, allowing applications to use larger color- and pair-
numbers.
- The reset_color_pairs function is an extension of ncurses.
+ The reset_color_pairs function is an extension of ncurses.
+
+
+
+ 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
+ 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
+ data type (denoted by A_COLOR).
+
+ Other implementations of curses had different limits:
+
+ o PCCurses (1987-1990) provided for only eight (8) colors.
+
+ o PDCurses (1992-present) inherited the 8-color limitation from
+ PCCurses, but changed this to 256 in version 2.5 (2001), along with
+ changing chtype from 16-bits to 32-bits.
+
+ 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
+ signed short, limiting values to 15 bits.
+
+ oncurses (1992-present) uses eight bits for A_COLOR in chtype
+ values.
+
+ 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
+ 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
+ the size of the bitfield.