.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_color.3x,v 1.82 2023/09/23 22:24:15 tom Exp $
-.TH curs_color 3X 2023-09-23 "ncurses 6.4" "Library calls"
-.ie \n(.g .ds `` \(lq
-.el .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el .ds '' ''
+.\" $Id: curs_color.3x,v 1.92 2023/11/25 17:36:51 tom Exp $
+.TH curs_color 3X 2023-11-25 "ncurses 6.4" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.ds n 5
+.
.SH NAME
\fB\%start_color\fP,
\fB\%has_colors\fP,
manipulate terminal colors with \fIcurses\fR
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fP
+\fB#include <curses.h>
.PP
-\fBint start_color(void);\fP
+\fBint start_color(void);
.PP
-\fBbool has_colors(void);\fP
-\fBbool can_change_color(void);\fP
+\fBbool has_colors(void);
+\fBbool can_change_color(void);
.PP
-\fBint init_pair(short \fIpair\fB, short \fIf\fB, short \fIb\fB);\fR
-\fBint init_color(short \fIcolor\fB, short \fIr\fB, short \fIg\fB, short \fIb\fB);\fR
-\fI/* extensions */\fP
-\fBint init_extended_pair(int \fIpair\fB, int \fIf\fB, int \fIb\fB);\fR
-\fBint init_extended_color(int \fIcolor\fB, int \fIr\fB, int \fIg\fB, int \fIb\fB);\fR
+\fBint init_pair(short \fIpair\fP, short \fIf\fP, short \fIb\fP);
+\fBint init_color(short \fIcolor\fP, short \fIr\fP, short \fIg\fP, short \fIb\fP);
+\fI/* extensions */
+\fBint init_extended_pair(int \fIpair\fP, int \fIf\fP, int \fIb\fP);
+\fBint init_extended_color(int \fIcolor\fP, int \fIr\fP, int \fIg\fP, int \fIb\fP);
.PP
-\fBint color_content(short \fIcolor\fB, short *\fIr\fB, short *\fIg\fB, short *\fIb\fB);\fR
-\fBint pair_content(short \fIpair\fB, short *\fIf\fB, short *\fIb\fB);\fR
-\fI/* extensions */\fP
-\fBint extended_color_content(int \fIcolor\fB, int *\fIr\fB, int *\fIg\fB, int *\fIb\fB);\fR
-\fBint extended_pair_content(int \fIpair\fB, int *\fIf\fB, int *\fIb\fB);\fR
+\fBint color_content(short \fIcolor\fP, short *\fIr\fP, short *\fIg\fP, short *\fIb\fP);
+\fBint pair_content(short \fIpair\fP, short *\fIf\fP, short *\fIb\fP);
+\fI/* extensions */
+\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 */\fP
-\fBvoid reset_color_pairs(void);\fP
+\fI/* extension */
+\fBvoid reset_color_pairs(void);
.PP
-\fBint COLOR_PAIR(int \fIn\fB);\fR
-\fBPAIR_NUMBER(\fIattrs\fB);\fR
+\fBint COLOR_PAIR(int \fIn\fP);
+\fBPAIR_NUMBER(\fIattrs\fP);
.fi
.SH DESCRIPTION
.SS Overview
It restores the colors on the terminal to the values
they had when the terminal was just turned on.
.bP
-If the terminal supports the \fBinitc\fP (\fB\%initialize_color\fP) capability,
+If the terminal supports the \fBinitc\fP \%(\fBinitialize_color\fP) capability,
\fB\%start_color\fP
initializes its internal table representing the
red, green, and blue components of the color palette.
.IP
The components depend on whether the terminal uses
CGA (aka \*(``ANSI\*('') or
-HLS (i.e., the \fBhls\fP (\fB\%hue_lightness_saturation\fP) capability is set).
+HLS (i.e., the \fBhls\fP \%(\fBhue_lightness_saturation\fP) capability is set).
The table is initialized first for eight basic colors
(black, red, green, yellow, blue, magenta, cyan, and white),
using weights that depend upon the CGA/HLS choice.
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\*(''.
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
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
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
\*(``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 \fBncurses\fP(3X),
+and are not found in SVr4 curses, 4.4BSD curses,
+or any other previous version of curses.
+.SH PORTABILITY
+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 HISTORY
SVr3.2 introduced color support to curses in 1987.
.PP
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.
+ncurses (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.
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