.\"***************************************************************************
-.\" Copyright (c) 1998-2017,2018 Free Software Foundation, Inc. *
+.\" Copyright 2018-2021,2022 Thomas E. Dickey *
+.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_color.3x,v 1.55 2018/07/28 22:15:59 tom Exp $
+.\" $Id: curs_color.3x,v 1.68 2022/02/12 20:06:41 tom Exp $
.TH curs_color 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.na
.hy 0
.SH NAME
-\fBstart_color\fR,
-\fBhas_colors\fR,
-\fBcan_change_color\fR,
-\fBinit_pair\fR,
-\fBinit_color\fR,
-\fBcolor_content\fR,
-\fBpair_content\fR,
-\fBreset_color_pairs\fR,
-\fBCOLOR_PAIR\fR,
-\fBPAIR_NUMBER\fR \- \fBcurses\fR color manipulation routines
+\fBstart_color\fP,
+\fBhas_colors\fP,
+\fBcan_change_color\fP,
+\fBinit_pair\fP,
+\fBinit_color\fP,
+\fBinit_extended_pair\fP,
+\fBinit_extended_color\fP,
+\fBcolor_content\fP,
+\fBpair_content\fP,
+\fBextended_color_content\fP,
+\fBextended_pair_content\fP,
+\fBreset_color_pairs\fP,
+\fBCOLOR_PAIR\fP,
+\fBPAIR_NUMBER\fP \- \fBcurses\fP color manipulation routines
.ad
.hy
.SH SYNOPSIS
-\fB#include <curses.h>\fR
+\fB#include <curses.h>\fP
.sp
-\fBint start_color(void);\fR
+\fBint start_color(void);\fP
.sp
-\fBbool has_colors(void);\fR
+\fBbool has_colors(void);\fP
.br
-\fBbool can_change_color(void);\fR
+\fBbool can_change_color(void);\fP
.sp
-\fBint init_pair(short pair, short f, short b);\fR
+\fBint init_pair(short \fIpair\fB, short \fIf\fB, short \fIb\fB);\fR
.br
-\fBint init_color(short color, short r, short g, short b);\fR
+\fBint init_color(short \fIcolor\fB, short \fIr\fB, short \fIg\fB, short \fIb\fB);\fR
.br
/* extensions */
.br
-\fBint init_extended_pair(int pair, int f, int b);\fR
+\fBint init_extended_pair(int \fIpair\fB, int \fIf\fB, int \fIb\fB);\fR
.br
-\fBint init_extended_color(int color, int r, int g, int b);\fR
+\fBint init_extended_color(int \fIcolor\fB, int \fIr\fB, int \fIg\fB, int \fIb\fB);\fR
.sp
-\fBint color_content(short color, short *r, short *g, short *b);\fR
+\fBint color_content(short \fIcolor\fB, short *\fIr\fB, short *\fIg\fB, short *\fIb\fB);\fR
.br
-\fBint pair_content(short pair, short *f, short *b);\fR
+\fBint pair_content(short \fIpair\fB, short *\fIf\fB, short *\fIb\fB);\fR
.br
/* extensions */
.br
-\fBint extended_color_content(int color, int *r, int *g, int *b);\fR
+\fBint extended_color_content(int \fIcolor\fB, int *\fIr\fB, int *\fIg\fB, int *\fIb\fB);\fR
.br
-\fBint extended_pair_content(int pair, int *f, int *b);\fR
+\fBint extended_pair_content(int \fIpair\fB, int *\fIf\fB, int *\fIb\fB);\fR
.sp
/* extensions */
.br
-\fBvoid reset_color_pairs(void);\fR
+\fBvoid reset_color_pairs(void);\fP
.sp
-\fBint COLOR_PAIR(int n);\fR
+\fBint COLOR_PAIR(int \fIn\fB);\fR
.br
-\fBPAIR_NUMBER(\fR\fIattrs\fR\fB);\fP
+\fBPAIR_NUMBER(\fIattrs\fB);\fR
.br
.SH DESCRIPTION
.SS Overview
-\fBcurses\fR supports color attributes on terminals with that capability.
-To use these routines \fBstart_color\fR must be called, usually right after
-\fBinitscr\fR.
+\fBcurses\fP supports color attributes on terminals with that capability.
+To use these routines \fBstart_color\fP must be called, usually right after
+\fBinitscr\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 \fBinit_pair\fR.
-After it has been initialized, \fBCOLOR_PAIR\fR(\fIn\fR)
+A programmer initializes a color-pair with the routine \fBinit_pair\fP.
+After it has been initialized, \fBCOLOR_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 \fBinit_color\fR to change the definition of a color.
-The routines \fBhas_colors\fR and \fBcan_change_color\fR
-return \fBTRUE\fR or \fBFALSE\fR,
+routine \fBinit_color\fP to change the definition of a color.
+The routines \fBhas_colors\fP and \fBcan_change_color\fP
+return \fBTRUE\fP or \fBFALSE\fP,
depending on whether the terminal has color capabilities and whether the
programmer can change the colors.
-The routine \fBcolor_content\fR allows a
+The routine \fBcolor_content\fP allows a
programmer to extract the amounts of red, green, and blue components in an
initialized color.
-The routine \fBpair_content\fR allows a programmer to find
+The routine \fBpair_content\fP allows a programmer to find
out how a given color-pair is currently defined.
.SS Color Rendering
The \fBcurses\fP library combines these inputs to produce the
the background character.
.SH CONSTANTS
.PP
-In \fB<curses.h>\fR the following macros are defined.
+In \fB<curses.h>\fP the following macros are defined.
These are the standard colors (ISO-6429).
-\fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
+\fBcurses\fP also assumes that \fBCOLOR_BLACK\fP is the default
background color for all terminals.
.PP
.nf
- \fBCOLOR_BLACK\fR
- \fBCOLOR_RED\fR
- \fBCOLOR_GREEN\fR
- \fBCOLOR_YELLOW\fR
- \fBCOLOR_BLUE\fR
- \fBCOLOR_MAGENTA\fR
- \fBCOLOR_CYAN\fR
- \fBCOLOR_WHITE\fR
+ \fBCOLOR_BLACK\fP
+ \fBCOLOR_RED\fP
+ \fBCOLOR_GREEN\fP
+ \fBCOLOR_YELLOW\fP
+ \fBCOLOR_BLUE\fP
+ \fBCOLOR_MAGENTA\fP
+ \fBCOLOR_CYAN\fP
+ \fBCOLOR_WHITE\fP
.fi
.PP
Some terminals support more than the eight (8) \*(``ANSI\*('' colors.
the terminal can support.
.SH FUNCTIONS
.SS start_color
-The \fBstart_color\fR routine requires no arguments.
+The \fBstart_color\fP routine requires no arguments.
It must be called if the programmer wants to use colors, and before any other
color manipulation routine is called.
-It is good practice to call this routine right after \fBinitscr\fR.
-\fBstart_color\fR does this:
+It is good practice to call this routine right after \fBinitscr\fP.
+\fBstart_color\fP does this:
.bP
-It initializes two global variables, \fBCOLORS\fR and
-\fBCOLOR_PAIRS\fR (respectively defining the maximum number of colors
+It initializes two global variables, \fBCOLORS\fP and
+\fBCOLOR_PAIRS\fP (respectively defining the maximum number of colors
and color-pairs the terminal can support).
.bP
It initializes the special color pair \fB0\fP to the default foreground
If the terminal supports the \fBinitc\fP (\fBinitialize_color\fP) capability,
\fBstart_color\fP
initializes its internal table representing the
-red, green and blue components of the color palette.
+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 (\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),
-and after that (if the terminal supports more than eight colors)
-the components are initialized to \fB1000\fP.
+using weights that depend upon the CGA/HLS choice.
+For \*(``ANSI\*('' colors the weights are \fB680\fP or \fB0\fP
+depending on whether the corresponding
+red, green, or blue component is used or not.
+That permits using \fB1000\fP to represent bold/bright colors.
+After the initial eight colors
+(if the terminal supports more than eight colors)
+the components are initialized using the same pattern,
+but with weights of \fB1000\fP.
+SVr4 uses a similar scheme, but uses \fB1000\fP
+for the components of the initial eight colors.
.IP
\fBstart_color\fP does not attempt to set the terminal's color palette
to match its built-in table.
These limits apply to color values and color pairs.
Values outside these limits are not legal, and may result in a runtime error:
.bP
-\fBCOLORS\fP corresponds to the terminal database's \fBmax_colors\fR capability,
-(see \fBterminfo\fR(\*n)).
+\fBCOLORS\fP corresponds to the terminal database's \fBmax_colors\fP capability,
+(see \fBterminfo\fP(\*n)).
.bP
color values are expected to be in the range \fB0\fP to \fBCOLORS\-1\fP,
inclusive (including \fB0\fP and \fBCOLORS\-1\fP).
.bP
a special color value \fB\-1\fP is used in certain extended functions
-to denote the \fIdefault color\fP (see \fBuse_default_colors\fP).
+to denote the \fIdefault color\fP (see \fBuse_default_colors\fP(3X)).
.bP
\fBCOLOR_PAIRS\fP corresponds to
the terminal database's \fBmax_pairs\fP capability,
-(see \fBterminfo\fR(\*n)).
+(see \fBterminfo\fP(\*n)).
.bP
legal color pair values are in the range \fB1\fP to \fBCOLOR_PAIRS\-1\fP,
inclusive.
It cannot be modified by the application.
.SS has_colors
.PP
-The \fBhas_colors\fR routine requires no arguments.
-It returns \fBTRUE\fR if
-the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR.
+The \fBhas_colors\fP routine requires no arguments.
+It returns \fBTRUE\fP if
+the terminal can manipulate colors; otherwise, it returns \fBFALSE\fP.
This routine facilitates writing terminal-independent programs.
For example, a programmer can use it to decide
whether to use color or some other video attribute.
.SS can_change_color
.PP
-The \fBcan_change_color\fR routine requires no arguments.
-It returns \fBTRUE\fR if the terminal supports colors
+The \fBcan_change_color\fP routine requires no arguments.
+It returns \fBTRUE\fP if the terminal supports colors
and can change their definitions;
-other, it returns \fBFALSE\fR.
+other, it returns \fBFALSE\fP.
This routine facilitates writing terminal-independent programs.
.SS init_pair
.PP
-The \fBinit_pair\fR routine changes the definition of a color-pair.
+The \fBinit_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
color number, and the background color number.
For portable applications:
.bP
The first argument must be a legal color pair value.
-If default colors are used (see \fBuse_default_colors\fP)
+If default colors are used (see \fBuse_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
are changed to the new definition.
.PP
As an extension, ncurses allows you to set color pair \fB0\fP via
-the \fBassume_default_colors\fR(3X) routine, or to specify the use of
-default colors (color number \fB\-1\fR) if you first invoke the
-\fBuse_default_colors\fR(3X) routine.
+the \fBassume_default_colors\fP(3X) routine, or to specify the use of
+default colors (color number \fB\-1\fP) if you first invoke the
+\fBuse_default_colors\fP(3X) routine.
+.SS init_extended_pair
.PP
-The extension \fBreset_color_pairs\fP tells ncurses to discard all
-of the color-pair information which was set with \fBinit_pair\fP.
-It also touches the current- and standard-screens, allowing an application to
-switch color palettes rapidly.
+Because \fBinit_pair\fP uses signed \fBshort\fPs for its parameters,
+that limits color-pairs and color-values
+to 32767 on modern hardware.
+The extension \fBinit_extended_pair\fP uses \fBint\fPs
+for the color-pair and color-value,
+allowing a larger number of colors to be supported.
.SS init_color
.PP
-The \fBinit_color\fR routine changes the definition of a color.
+The \fBinit_color\fP routine changes the definition of a color.
It takes four arguments:
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;
default colors are not allowed here.
-(See the section \fBColors\fR for the default color index.)
+(See the section \fBColors\fP for the default color index.)
.bP
Each of the last three arguments
must be a value in the range \fB0\fP through \fB1000\fP.
.PP
-When \fBinit_color\fR is used, all
+When \fBinit_color\fP is used, all
occurrences of that color on the screen immediately change to the new
definition.
+.SS init_extended_color
+.PP
+Because \fBinit_color\fP uses signed \fBshort\fPs for its parameters,
+that limits color-values and their red, green, and blue components
+to 32767 on modern hardware.
+The extension \fBinit_extended_color\fP uses \fBint\fPs
+for the color value and
+for setting the red, green, and blue components,
+allowing a larger number of colors to be supported.
.SS color_content
.PP
-The \fBcolor_content\fR routine gives programmers a way to find the intensity
+The \fBcolor_content\fP routine gives programmers a way to find the intensity
of the red, green, and blue (RGB) components in a color.
It requires four arguments: the color number, and three addresses
of \fBshort\fRs for storing
last three arguments are in the range
\fB0\fP (no component) through \fB1000\fP
(maximum amount of component), inclusive.
+.SS extended_color_content
+.PP
+Because \fBcolor_content\fP uses signed \fBshort\fPs for its parameters,
+that limits color-values and their red, green, and blue components
+to 32767 on modern hardware.
+The extension \fBextended_color_content\fP uses \fBint\fPs
+for the color value and
+for returning the red, green, and blue components,
+allowing a larger number of colors to be supported.
.SS pair_content
.PP
-The \fBpair_content\fR routine allows programmers to find out what colors a
+The \fBpair_content\fP routine allows programmers to find out what colors a
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,
-i.e., in the range \fB1\fP through \fBCOLOR_PAIRS\-1\fR, inclusive.
+i.e., in the range \fB1\fP through \fBCOLOR_PAIRS\-1\fP, inclusive.
.bP
The values that are stored at the addresses pointed
to by the second and third arguments are in the
-range \fB0\fP through \fBCOLORS\fR, inclusive.
+range \fB0\fP through \fBCOLORS\fP, inclusive.
+.SS extended_pair_content
+.PP
+Because \fBpair_content\fP uses signed \fBshort\fPs for its parameters,
+that limits color-pair and color-values to 32767 on modern hardware.
+The extension \fBextended_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
+.PP
+The extension \fBreset_color_pairs\fP tells ncurses to discard all
+of the color-pair information which was set with \fBinit_pair\fP.
+It also touches the current- and standard-screens, allowing an application to
+switch color palettes rapidly.
.SS PAIR_NUMBER
.PP
-\fBPAIR_NUMBER(\fR\fIattrs\fR) extracts the color
+\fBPAIR_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 \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR converts a color pair number
+Its inverse \fBCOLOR_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 \fBattr_set\fP (which pass the color pair as a separate parameter)
rather than the legacy functions such as \fBattrset\fP.
.SH RETURN VALUE
-The routines \fBcan_change_color\fR and \fBhas_colors\fR return \fBTRUE\fR
-or \fBFALSE\fR.
+The routines \fBcan_change_color\fP and \fBhas_colors\fP return \fBTRUE\fP
+or \fBFALSE\fP.
.PP
-All other routines return the integer \fBERR\fR upon failure and an \fBOK\fR
+All other routines return the integer \fBERR\fP upon failure and an \fBOK\fP
(SVr4 specifies only \*(``an integer value
-other than \fBERR\fR\*('') upon successful completion.
+other than \fBERR\fP\*('') upon successful completion.
.PP
X/Open defines no error conditions.
-This implementation will return \fBERR\fR on attempts to
+SVr4 does document some error conditions which apply in general:
+.bP
+This implementation will return \fBERR\fP on attempts to
use color values outside the range \fB0\fP to \fBCOLORS\fP\-1
(except for the default colors extension),
or use color pairs outside the range \fB0\fP to \fBCOLOR_PAIRS\-1\fP.
+.IP
Color values used in \fBinit_color\fP must be
in the range \fB0\fP to \fB1000\fP.
+.IP
An error is returned from all functions
if the terminal has not been initialized.
+.IP
An error is returned from secondary functions such as \fBinit_pair\fP
if \fBstart_color\fP was not called.
+.bP
+SVr4 does much the same, except that
+it returns \fBERR\fP from \fBpair_content\fP if the pair was not initialized
+using \fBinit_pairs\fP
+and
+it returns \fBERR\fP from \fBcolor_content\fP
+if the terminal does not support changing colors.
+.IP
+This implementation does not return \fBERR\fP for either case.
+.PP
+Specific functions make additional checks:
.RS 3
.TP 5
\fBinit_color\fP
returns an error if the color table cannot be allocated.
.RE
.SH NOTES
-In the \fBncurses\fR implementation, there is a separate color activation flag,
+In the \fBncurses\fP implementation, there is a separate color activation flag,
color palette, color pairs table,
and associated \fBCOLORS\fP and \fBCOLOR_PAIRS\fP counts
-for each screen; the \fBstart_color\fR function only affects the current
+for each screen; the \fBstart_color\fP 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.
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 \fBcurs_bkgd\fR(3X).
+scrolling operations, see \fBcurs_bkgd\fP(3X).
.PP
Several caveats apply on older x86 machines
(e.g., i386, i486) with VGA-compatible graphics:
.bP
COLOR_YELLOW is actually brown.
-To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fR attribute.
+To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fP attribute.
.bP
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
\*(``yellow\*('' background (you get a blinking yellow foreground instead).
.bP
Color RGB values are not settable.
+.SH HISTORY
+.PP
+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 \fBcur_term\fP (the \fBTERMINAL\fP structure),
+but provided the same set of library functions.
+.PP
+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 \fBchtype\fP data type (denoted by \fBA_COLOR\fP).
+.PP
+Other implementations of curses had different limits:
+.bP
+PCCurses (1987-1990) provided for only eight (8) colors.
+.bP
+PDCurses (1992-present) inherited the 8-color limitation from PCCurses,
+but changed this to 256 in version 2.5 (2001),
+along with changing \fBchtype\fP from 16-bits to 32-bits.
+.bP
+X/Open Curses (1992-present)
+added a new structure \fBcchar_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,
+limiting values to 15 bits.
+.bP
+ncurses (1992-present) uses eight bits for \fBA_COLOR\fP in \fBchtype\fP values.
+.IP
+Version 5.3 provided a wide-character interface (2002),
+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 \fBcchar_t\fP values.
+When those color-pair values fit in 8 bits,
+ncurses allows color-pairs to be manipulated
+via the functions using \fBchtype\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 \fBcchar_t\fP, limiting the number of color-pairs
+by the size of the bitfield.
.SH PORTABILITY
This implementation satisfies XSI Curses's minimum maximums
-for \fBCOLORS\fR and \fBCOLOR_PAIRS\fR.
+for \fBCOLORS\fP and \fBCOLOR_PAIRS\fP.
.PP
The \fBinit_pair\fP routine accepts negative values of foreground
-and background color to support the \fBuse_default_colors\fR(3X) extension,
+and background color to support the \fBuse_default_colors\fP(3X) extension,
but only if that routine has been first invoked.
.PP
-The assumption that \fBCOLOR_BLACK\fR is the default
+The assumption that \fBCOLOR_BLACK\fP is the default
background color for all terminals can be modified using the
-\fBassume_default_colors\fR(3X) extension.
+\fBassume_default_colors\fP(3X) extension.
.PP
This implementation checks the pointers,
e.g., for the values returned by
.PP
The \fBreset_color_pairs\fP function is an extension of ncurses.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_initscr\fR(3X),
-\fBcurs_attr\fR(3X),
-\fBcurs_variables\fR(3X),
-\fBdefault_colors\fR(3X)
+\fBcurses\fP(3X),
+\fBcurs_initscr\fP(3X),
+\fBcurs_attr\fP(3X),
+\fBcurs_variables\fP(3X),
+\fBdefault_colors\fP(3X)
projects / ncurses.git / blobdiff