.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_color.3x,v 1.85 2023/10/07 21:19:07 tom Exp $
-.TH curs_color 3X 2023-10-07 "ncurses 6.4" "Library calls"
+.\" $Id: curs_color.3x,v 1.100 2024/04/20 21:24:19 tom Exp $
+.TH curs_color 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.ie \n(.g \{\
.ds `` \(lq
.ds '' \(rq
.el .IP \(bu 2
..
.
-.ds n 5
.SH NAME
\fB\%start_color\fP,
\fB\%has_colors\fP,
\fB\%extended_pair_content\fP,
\fB\%reset_color_pairs\fP,
\fB\%COLOR_PAIR\fP,
-\fB\%PAIR_NUMBER\fP \-
+\fB\%PAIR_NUMBER\fP,
+\fB\%COLORS\fP,
+\fB\%COLOR_PAIRS\fP,
+\fB\%COLOR_BLACK\fP,
+\fB\%COLOR_RED\fP,
+\fB\%COLOR_GREEN\fP,
+\fB\%COLOR_YELLOW\fP,
+\fB\%COLOR_BLUE\fP,
+\fB\%COLOR_MAGENTA\fP,
+\fB\%COLOR_CYAN\fP,
+\fB\%COLOR_WHITE\fP \-
manipulate terminal colors with \fIcurses\fR
.SH SYNOPSIS
.nf
\fB#include <curses.h>
.PP
+\fI/* variables */
+\fBint COLOR_PAIRS;
+\fBint COLORS;
+.PP
\fBint start_color(void);
.PP
\fBbool has_colors(void);
\fBint extended_color_content(int \fIcolor\fP, int *\fIr\fP, int *\fIg\fP, int *\fIb\fP);
\fBint extended_pair_content(int \fIpair\fP, int *\fIf\fP, int *\fIb\fP);
.PP
-\fI/* extensions */
+\fI/* extension */
\fBvoid reset_color_pairs(void);
.PP
\fBint COLOR_PAIR(int \fIn\fP);
-\fBPAIR_NUMBER(\fIattrs\fP);
+\fBPAIR_NUMBER(int \fIattr\fP);
.fi
.SH DESCRIPTION
.SS Overview
-\fIcurses\fP supports color attributes on terminals with that capability.
-To use these routines \fB\%start_color\fP must be called, usually right after
-\fB\%initscr\fP.
-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 \fB\%init_pair\fP.
-After it has been initialized, \fB\%COLOR_PAIR\fP(\fIn\fP)
-can be used to convert the pair to a video attribute.
-.PP
-If a terminal is capable of redefining colors, the programmer can use the
-routine \fB\%init_color\fP to change the definition of a color.
-The routines \fB\%has_colors\fP and \fB\%can_change_color\fP
+\fIcurses\fP supports color attributes on terminals with that
+capability.
+Call \fB\%start_color\fP
+(typically right after \fB\%initscr\fP(3X))
+to enable this feature.
+Colors are always used in pairs.
+A
+.I "color pair"
+couples a foreground color for characters with a background color for
+the blank field on which characters are rendered.
+\fB\%init_pair\fP initializes a color pair.
+The macro \fB\%COLOR_PAIR\fP(\fIn\fP) can then convert the pair to a
+video attribute.
+.PP
+If a terminal has the relevant capability,
+\fB\%init_color\fP permits (re)definition of a color.
+\fB\%has_colors\fP and \fB\%can_change_color\fP
return \fBTRUE\fP or \fBFALSE\fP,
-depending on whether the terminal has color capabilities and whether the
+depending on whether the terminal has color capability and whether the
programmer can change the colors.
-The routine \fB\%color_content\fP allows a
-programmer to extract the amounts of red, green, and blue components in an
-initialized color.
-The routine \fB\%pair_content\fP allows a programmer to find
-out how a given color-pair is currently defined.
-.SS Color Rendering
-The \fIcurses\fP library combines these inputs to produce the
-actual foreground and background colors shown on the screen:
+\fB\%color_content\fP permits extraction of the
+red,
+green,
+and blue components of an initialized color.
+\fB\%pair_content\fP permits discovery of a color pair's current
+definition.
+.SS Rendering
+.I curses
+combines the following data to render a character cell.
+Any of them can include color information.
.bP
-per-character video attributes (e.g., via \fB\%waddch\fP),
+.I curses
+character attributes,
+as from \fB\%waddch\fP(3X) or \fB\%wadd_wch\fP(3X)
.bP
-the window attribute (e.g., by \fB\%wattrset\fP), and
+window attributes,
+as from \fB\%wattrset\fP(3X) or \fB\%wattr_set\fP(3X)
.bP
-the background character (e.g., \fB\%wbkgdset\fP).
+window background character attributes,
+as from \fB\%wbkgdset\fP(3X) or \fB\%wbkgrndset\fP(3X)
.PP
-Per-character and window attributes are usually set by a parameter containing
-video attributes including a color pair value.
-Some functions such as \fB\%wattr_set\fP 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 \fB\%wattr_set\fP,
+use a separate color pair number parameter.
.PP
-The background character is a special case: it includes a character value,
+The background character is a special case:
+it includes a character code,
just as if it were passed to \fB\%waddch\fP.
.PP
The \fIcurses\fP library does the actual work of combining these color
is initialized by \fB\%start_color\fP to the maximum number of colors
the terminal can support.
.SS COLOR_PAIRS
-is initialized by \fB\%start_color\fP to the maximum number of color pairs
-the terminal can support.
+is initialized by \fB\%start_color\fP to the maximum number of color
+pairs the terminal can support.
+Often,
+its value is the product \fB\%COLORS\fP \(mu \fB\%COLORS\fP,
+but this is not always true.
+.bP
+A few terminals use the HLS color space
+(see \fB\%start_color\fP below),
+ignoring this rule;
+and
+.bP
+terminals supporting a large number of colors are limited to the number
+of color pairs that a
+.I "signed short"
+value can represent.
.SH FUNCTIONS
.SS start_color
The \fB\%start_color\fP routine requires no arguments.
.bP
It initializes two global variables, \fB\%COLORS\fP and
\fB\%COLOR_PAIRS\fP (respectively defining the maximum number of colors
-and color-pairs the terminal can support).
+and color pairs the terminal can support).
.bP
It initializes the special color pair \fB\%0\fP to the default foreground
and background colors.
along with the terminal's color.
.PP
These limits apply to color values and color pairs.
-Values outside these limits are not legal, and may result in a runtime error:
+Values outside these limits are not valid, and may result in a runtime error:
.bP
\fBCOLORS\fP corresponds to the terminal database's \fB\%max_colors\fP capability,
-(see \fB\%terminfo\fP(\*n)).
+(see \fB\%terminfo\fP(5)).
.bP
color values are expected to be in the range \fB0\fP to \fB\%COLORS\-1\fP,
inclusive (including \fB0\fP and \fB\%COLORS\-1\fP).
.bP
\fB\%COLOR_PAIRS\fP corresponds to
the terminal database's \fB\%max_pairs\fP capability,
-(see \fB\%terminfo\fP(\*n)).
+(see \fB\%terminfo\fP(5)).
.bP
-legal color pair values are in the range \fB1\fP to \fB\%COLOR_PAIRS\-1\fP,
+valid color pair values are in the range \fB1\fP to \fB\%COLOR_PAIRS\-1\fP,
inclusive.
.bP
color pair \fB0\fP is special; it denotes \*(``no color\*(''.
other, it returns \fBFALSE\fP.
This routine facilitates writing terminal-independent programs.
.SS init_pair
-The \fB\%init_pair\fP routine changes the definition of a color-pair.
+The \fB\%init_pair\fP routine changes the definition of a color pair.
It takes three arguments:
-the number of the color-pair to be changed, the foreground
+the number of the color pair to be changed, the foreground
color number, and the background color number.
For portable applications:
.bP
-The first argument must be a legal color pair value.
+The first argument must be a valid color pair value.
If default colors are used (see \fB\%use_default_colors\fP(3X))
the upper limit is adjusted to allow for extra pairs which use
a default color in foreground and/or background.
.bP
-The second and third arguments must be legal color values.
+The second and third arguments must be valid color values.
.PP
-If the color-pair was previously initialized,
-the screen is refreshed and all occurrences of that color-pair
+If the color pair was previously initialized,
+the screen is refreshed and all occurrences of that color pair
are changed to the new definition.
.PP
-As an extension, ncurses allows you to set color pair \fB0\fP via
-the \fB\%assume_default_colors\fP(3X) routine, or to specify the use of
+As an extension,
+\fI\%ncurses\fP allows you to set color pair \fB0\fP via the
+\fB\%assume_default_colors\fP(3X) routine, or to specify the use of
default colors (color number \fB\-1\fP) if you first invoke the
\fB\%use_default_colors\fP(3X) routine.
.SS init_extended_pair
Because \fB\%init_pair\fP uses signed \fBshort\fPs for its parameters,
-that limits color-pairs and color-values
+that limits color pairs and color-values
to 32767 on modern hardware.
The extension \fB\%init_extended_pair\fP uses \fBint\fPs
-for the color-pair and color-value,
+for the color pair and color-value,
allowing a larger number of colors to be supported.
.SS init_color
The \fB\%init_color\fP routine changes the definition of a color.
the number of the color to be changed followed by three RGB values
(for the amounts of red, green, and blue components).
.bP
-The first argument must be a legal color value;
+The first argument must be a valid color value;
default colors are not allowed here.
(See the section \fB\%Colors\fP for the default color index.)
.bP
the information about the amounts of red, green, and blue components in the
given color.
.bP
-The first argument must be a legal color value, i.e.,
+The first argument must be a valid color value, i.e.,
\fB0\fP through \fB\%COLORS\-1\fP, inclusive.
.bP
The values that are stored at the addresses pointed to by the
allowing a larger number of colors to be supported.
.SS pair_content
The \fB\%pair_content\fP routine allows programmers to find out what colors a
-given color-pair consists of.
-It requires three arguments: the color-pair
+given color pair consists of.
+It requires three arguments: the color pair
number, and two addresses of \fBshort\fRs for storing the foreground and the
background color numbers.
.bP
-The first argument must be a legal color value,
+The first argument must be a valid color value,
i.e., in the range \fB1\fP through \fB\%COLOR_PAIRS\-1\fP, inclusive.
.bP
The values that are stored at the addresses pointed
range \fB0\fP through \fB\%COLORS\fP, inclusive.
.SS extended_pair_content
Because \fB\%pair_content\fP uses signed \fBshort\fPs for its parameters,
-that limits color-pair and color-values to 32767 on modern hardware.
+that limits color pair and color-values to 32767 on modern hardware.
The extension \fB\%extended_pair_content\fP uses \fBint\fPs
for the color pair and
for returning the foreground and background colors,
allowing a larger number of colors to be supported.
.SS reset_color_pairs
-The extension \fB\%reset_color_pairs\fP tells ncurses to discard all
-of the color-pair information which was set with \fB\%init_pair\fP.
+The extension \fB\%reset_color_pairs\fP tells \fI\%ncurses\fP to discard
+all of the color pair information which was set with \fB\%init_pair\fP.
It also touches the current- and standard-screens, allowing an application to
switch color palettes rapidly.
-.SS PAIR_NUMBER
-\fB\%PAIR_NUMBER(\fIattrs\fR) extracts the color
-value from its \fIattrs\fP parameter and returns it as a color pair number.
.SS COLOR_PAIR
-Its inverse \fB\%COLOR_PAIR(\fIn\fB)\fR converts a color pair number
-to an attribute.
+\fB\%COLOR_PAIR(\fIn\fB)\fR 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 \fB\%attr_set\fP (which pass the color pair as a separate parameter)
+If you need a color pair larger than that,
+you must use functions such as \fB\%attr_set\fP
+(which pass the color pair as a separate parameter)
rather than the legacy functions such as \fB\%attrset\fP.
+.SS PAIR_NUMBER
+\fB\%PAIR_NUMBER(\fIattr\fR) extracts the color information from its
+\fIattr\fP parameter and returns it as a color pair number;
+it is the inverse operation of \fB\%COLOR_PAIR\fP.
.SH RETURN VALUE
The routines \fB\%can_change_color\fP and \fB\%has_colors\fP return \fBTRUE\fP
or \fBFALSE\fP.
returns an error if the color table cannot be allocated.
.RE
.SH NOTES
-In the \fIncurses\fP implementation, there is a separate color activation flag,
+In the \fI\%ncurses\fP implementation,
+there is a separate color activation flag,
color palette, color pairs table,
and associated \fB\%COLORS\fP and \fB\%COLOR_PAIRS\fP counts
for each screen; the \fB\%start_color\fP function only affects the current
\*(``yellow\*('' background (you get a blinking yellow foreground instead).
.bP
Color RGB values are not settable.
+.SH EXTENSIONS
+The functions marked as extensions were designed for
+\fB\%ncurses\fP(3X),
+and are not found in SVr4
+.IR curses ,
+4.4BSD
+.IR curses ,
+or any other previous curses implementation.
+.SH PORTABILITY
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
+.PP
+This implementation satisfies X/Open Curses's minimum maximums
+for \fB\%COLORS\fP and \fB\%COLOR_PAIRS\fP.
+.PP
+The \fB\%init_pair\fP routine accepts negative values of foreground
+and background color to support the \fB\%use_default_colors\fP(3X) extension,
+but only if that routine has been first invoked.
+.PP
+The assumption that \fB\%COLOR_BLACK\fP is the default
+background color for all terminals can be modified using the
+\fB\%assume_default_colors\fP(3X) extension.
+.PP
+This implementation checks the pointers,
+e.g., for the values returned by
+\fB\%color_content\fP and \fB\%pair_content\fP,
+and will treat those as optional parameters when null.
+.PP
+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 \fBshort\fP 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 \fBshort\fP parameters,
+allowing applications to use larger color- and pair-numbers.
+.PP
+The \fB\%reset_color_pairs\fP function is an extension of
+\fI\%ncurses\fP.
.SH HISTORY
SVr3.2 introduced color support to curses in 1987.
.PP
SVr4 made internal changes,
e.g., moving the storage for the color state
-from \fBSP\fP (the \fBSCREEN\fP structure)
-to \fB\%cur_term\fP (the \fB\%TERMINAL\fP structure),
+from \fBSP\fP (the \fISCREEN\fP structure)
+to \fB\%cur_term\fP (the \fI\%TERMINAL\fP structure),
but provided the same set of library functions.
.PP
SVr4 curses limits the number of color pairs to 64,
.bP
X/Open Curses (1992-present)
added a new structure \fB\%cchar_t\fP to store the character,
-attributes and color-pair values, allowing increased range of color-pairs.
-Both color-pairs and color-values used a signed \fBshort\fP,
+attributes and color pair values, allowing increased range of color pairs.
+Both color pairs and color-values used a signed \fBshort\fP,
limiting values to 15 bits.
.bP
-ncurses (1992-present) uses eight bits for \fB\%A_COLOR\fP in \fB\%chtype\fP values.
+\fI\%ncurses\fP (1992-present) uses eight bits
+for \fB\%A_COLOR\fP in \fB\%chtype\fP values.
.IP
Version 5.3 provided a wide-character interface (2002),
-but left color-pairs as part of the attributes-field.
+but left color pairs as part of the attributes-field.
.IP
Since version 6 (2015),
-ncurses uses a separate \fBint\fP for color-pairs in the \fB\%cchar_t\fP values.
-When those color-pair values fit in 8 bits,
-ncurses allows color-pairs to be manipulated
+ncurses uses a separate \fBint\fP for color pairs in the \fB\%cchar_t\fP values.
+When those color pair values fit in 8 bits,
+ncurses allows color pairs to be manipulated
via the functions using \fB\%chtype\fP values.
.bP
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 \fB\%cchar_t\fP, limiting the number of color-pairs
+Like \fI\%ncurses\fP before version 6,
+the NetBSD color pair information is stored in
+the attributes field of \fB\%cchar_t\fP, limiting the number of color pairs
by the size of the bitfield.
-.SH PORTABILITY
-.SS Extensions
-The functions marked as extensions were designed for \fBncurses\fP(3X),
-and are not found in SVr4 curses, 4.4BSD curses,
-or any other previous version of curses.
-.SS Standards
-This implementation satisfies XSI Curses's minimum maximums
-for \fB\%COLORS\fP and \fB\%COLOR_PAIRS\fP.
-.PP
-The \fB\%init_pair\fP routine accepts negative values of foreground
-and background color to support the \fB\%use_default_colors\fP(3X) extension,
-but only if that routine has been first invoked.
-.PP
-The assumption that \fB\%COLOR_BLACK\fP is the default
-background color for all terminals can be modified using the
-\fB\%assume_default_colors\fP(3X) extension.
-.PP
-This implementation checks the pointers,
-e.g., for the values returned by
-\fB\%color_content\fP and \fB\%pair_content\fP,
-and will treat those as optional parameters when null.
-.PP
-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 \fBshort\fP 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 \fBshort\fP parameters,
-allowing applications to use larger color- and pair-numbers.
-.PP
-The \fB\%reset_color_pairs\fP function is an extension of ncurses.
.SH SEE ALSO
\fB\%curses\fP(3X),
-\fB\%curs_initscr\fP(3X),
\fB\%curs_attr\fP(3X),
+\fB\%curs_initscr\fP(3X),
\fB\%curs_variables\fP(3X),
\fB\%default_colors\fP(3X)
projects / ncurses.git / blobdiff