.\"***************************************************************************
-.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc. *
+.\" 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 *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_color.3x,v 1.34 2010/12/04 18:36:44 tom Exp $
-.TH curs_color 3X ""
+.\" $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 \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
-.na
-.hy 0
+.
.SH NAME
-\fBstart_color\fR,
-\fBinit_pair\fR,
-\fBinit_color\fR,
-\fBhas_colors\fR,
-\fBcan_change_color\fR,
-\fBcolor_content\fR,
-\fBpair_content\fR,
-\fBCOLOR_PAIR\fR \- \fBcurses\fR color manipulation routines
-.ad
-.hy
+\fB\%start_color\fP,
+\fB\%has_colors\fP,
+\fB\%can_change_color\fP,
+\fB\%init_pair\fP,
+\fB\%init_color\fP,
+\fB\%init_extended_pair\fP,
+\fB\%init_extended_color\fP,
+\fB\%color_content\fP,
+\fB\%pair_content\fP,
+\fB\%extended_color_content\fP,
+\fB\%extended_pair_content\fP,
+\fB\%reset_color_pairs\fP,
+\fB\%COLOR_PAIR\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
-\fB# include <curses.h>\fR
-.sp
-\fBint start_color(void);\fR
-.br
-\fBint init_pair(short pair, short f, short b);\fR
-.br
-\fBint init_color(short color, short r, short g, short b);\fR
-.br
-\fBbool has_colors(void);\fR
-.br
-\fBbool can_change_color(void);\fR
-.br
-\fBint color_content(short color, short *r, short *g, short *b);\fR
-.br
-\fBint pair_content(short pair, short *f, short *b);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fI/* variables */
+\fBint COLOR_PAIRS;
+\fBint COLORS;
+.PP
+\fBint start_color(void);
+.PP
+\fBbool has_colors(void);
+\fBbool can_change_color(void);
+.PP
+\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\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/* extension */
+\fBvoid reset_color_pairs(void);
+.PP
+\fBint COLOR_PAIR(int \fIn\fP);
+\fBPAIR_NUMBER(int \fIattr\fP);
+.fi
.SH DESCRIPTION
.SS Overview
-\fBcurses\fR support color attributes on terminals with that capability. To
-use these routines \fBstart_color\fR must be called, usually right after
-\fBinitscr\fR. 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 macro defined in
-\fB<curses.h>\fR, can be used as a new 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,
-depending on whether the terminal has color capabilities and whether the
-programmer can change the colors. The routine \fBcolor_content\fR 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
-out how a given color-pair is currently defined.
-.SS Routine Descriptions
-The \fBstart_color\fR 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 initializes
-eight basic colors (black, red, green, yellow, blue, magenta, cyan,
-and white), and two global variables, \fBCOLORS\fR and
-\fBCOLOR_PAIRS\fR (respectively defining the maximum number of colors
-and color-pairs the terminal can support). It also restores the
-colors on the terminal to the values they had when the terminal was
-just turned on.
-.PP
-The \fBinit_pair\fR routine changes the definition of a color-pair. It takes
-three arguments: the number of the color-pair to be changed, the foreground
+\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 capability and whether the
+programmer can change the colors.
+\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
+.I curses
+character attributes,
+as from \fB\%waddch\fP(3X) or \fB\%wadd_wch\fP(3X)
+.bP
+window attributes,
+as from \fB\%wattrset\fP(3X) or \fB\%wattr_set\fP(3X)
+.bP
+window background character attributes,
+as from \fB\%wbkgdset\fP(3X) or \fB\%wbkgrndset\fP(3X)
+.PP
+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 code,
+just as if it were passed to \fB\%waddch\fP.
+.PP
+The \fIcurses\fP library does the actual work of combining these color
+pairs in an internal function called from \fB\%waddch\fP:
+.bP
+If the parameter passed to \fB\%waddch\fP is \fIblank\fP,
+and it uses the special color pair 0,
+.RS
+.bP
+\fIcurses\fP next checks the window attribute.
+.bP
+If the window attribute does not use color pair 0,
+\fIcurses\fP uses the color pair from the window attribute.
+.bP
+Otherwise, \fIcurses\fP uses the background character.
+.RE
+.bP
+If the parameter passed to \fB\%waddch\fP is \fInot blank\fP,
+or it does not use the special color pair 0,
+\fIcurses\fP prefers the color pair from the parameter,
+if it is nonzero.
+Otherwise, it tries the window attribute next, and finally the
+background character.
+.PP
+Some \fIcurses\fP functions such as \fB\%wprintw\fP call \fB\%waddch\fP.
+Those do not combine its parameter with a color pair.
+Consequently those calls use only the window attribute or
+the background character.
+.SH CONSTANTS
+In \fB\%<curses.h>\fP the following macros are defined.
+These are the standard colors (ISO-6429).
+\fIcurses\fP also assumes that \fB\%COLOR_BLACK\fP is the default
+background color for all terminals.
+.PP
+.nf
+ \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.
+There are no standard names for those additional colors.
+.SH VARIABLES
+.SS COLORS
+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.
+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.
+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 \fB\%initscr\fP.
+\fB\%start_color\fP does this:
+.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).
+.bP
+It initializes the special color pair \fB\%0\fP to the default foreground
+and background colors.
+No other color pairs are initialized.
+.bP
+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 \%(\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 \%(\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.
+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
+\fB\%start_color\fP does not attempt to set the terminal's color palette
+to match its built-in table.
+An application may use \fB\%init_color\fP to alter the internal table
+along with the terminal's color.
+.PP
+These limits apply to color values and color pairs.
+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(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
+a special color value \fB\-1\fP is used in certain extended functions
+to denote the \fIdefault color\fP (see \fB\%use_default_colors\fP(3X)).
+.bP
+\fB\%COLOR_PAIRS\fP corresponds to
+the terminal database's \fB\%max_pairs\fP capability,
+(see \fB\%terminfo\fP(5)).
+.bP
+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\*(''.
+.IP
+Color pair \fB0\fP is assumed to be white on black,
+but is actually whatever the terminal implements before color is initialized.
+It cannot be modified by the application.
+.SS has_colors
+The \fB\%has_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
+The \fB\%can_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\fP.
+This routine facilitates writing terminal-independent programs.
+.SS init_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
color number, and the background color number.
For portable applications:
.bP
-The value of the first argument
-must be between \fB1\fR and \fBCOLOR_PAIRS\-1\fR,
-except that if default colors are used (see \fBuse_default_colors\fP)
+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 value of the second and
-third arguments must be between 0 and \fBCOLORS\fR.
-Color pair 0 is assumed to be white on black,
-but is actually whatever the terminal implements before color is initialized.
-It cannot be modified by the application.
+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 0 via
-the \fBassume_default_colors\fR routine, or to specify the use of
-default colors (color number \fB\-1\fR) if you first invoke the
-\fBuse_default_colors\fR routine.
-.PP
-The \fBinit_color\fR 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). The value of the first
-argument must be between \fB0\fR and \fBCOLORS\fR. (See the section
-\fBColors\fR for the default color index.) Each of the last three arguments
-must be a value between 0 and 1000. When \fBinit_color\fR is used, all
+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
+to 32767 on modern hardware.
+The extension \fB\%init_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
+The \fB\%init_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 valid color value;
+default colors are not allowed here.
+(See the section \fB\%Colors\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 \fB\%init_color\fP is used, all
occurrences of that color on the screen immediately change to the new
definition.
-.PP
-The \fBhas_colors\fR routine requires no arguments. It returns \fBTRUE\fR if
-the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR. 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.
-.PP
-The \fBcan_change_color\fR routine requires no arguments. It returns
-\fBTRUE\fR if the terminal supports colors and can change their definitions;
-other, it returns \fBFALSE\fR. This routine facilitates writing
-terminal-independent programs.
-.PP
-The \fBcolor_content\fR 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
+.SS init_extended_color
+Because \fB\%init_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 \fB\%init_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
+The \fB\%color_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
the information about the amounts of red, green, and blue components in the
-given color. The value of the first argument must be between 0 and
-\fBCOLORS\fR. The values that are stored at the addresses pointed to by the
-last three arguments are between 0 (no component) and 1000 (maximum amount of
-component).
-.PP
-The \fBpair_content\fR routine allows programmers to find out what colors a
-given color-pair consists of. It requires three arguments: the color-pair
+given color.
+.bP
+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
+last three arguments are in the range
+\fB0\fP (no component) through \fB1000\fP
+(maximum amount of component), inclusive.
+.SS extended_color_content
+Because \fB\%color_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 \fB\%extended_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
+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
number, and two addresses of \fBshort\fRs for storing the foreground and the
-background color numbers. The value of the first argument must be between 1
-and \fBCOLOR_PAIRS\-1\fR. The values that are stored at the addresses pointed
-to by the second and third arguments are between 0 and \fBCOLORS\fR.
-.SS Colors
-In \fB<curses.h>\fR the following macros are defined. These are the default
-colors. \fBcurses\fR also assumes that \fBCOLOR_BLACK\fR 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
-.fi
+background color numbers.
+.bP
+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
+to by the second and third arguments are in the
+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.
+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 \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 COLOR_PAIR
+\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)
+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 \fBcan_change_color()\fR and \fBhas_colors()\fR return \fBTRUE\fR
-or \fBFALSE\fR.
+The routines \fB\%can_change_color\fP and \fB\%has_colors\fP return \fBTRUE\fP
+or \fBFALSE\fP.
.PP
-All other routines return the integer \fBERR\fR upon failure and an \fBOK\fR
-(SVr4 specifies only "an integer value other than \fBERR\fR") upon successful
-completion.
+All other routines return the integer \fBERR\fP upon failure and an \fBOK\fP
+(SVr4 specifies only \*(``an integer value
+other than \fBERR\fP\*('') upon successful completion.
.PP
X/Open defines no error conditions.
-This implementation will return \fBERR\fR on attempts to
-use color values outside the range 0 to COLORS\-1
+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 \fB\%COLORS\fP\-1
(except for the default colors extension),
-or use color pairs outside the range 0 to COLOR_PAIR\-1.
-Color values used in \fBinit_color\fP must be in the range 0 to 1000.
+or use color pairs outside the range \fB0\fP to \fB\%COLOR_PAIRS\-1\fP.
+.IP
+Color values used in \fB\%init_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.
-An error is returned from secondary functions such as \fBinit_pair\fP
-if \fBstart_color\fP was not called.
+.IP
+An error is returned from secondary functions such as \fB\%init_pair\fP
+if \fB\%start_color\fP was not called.
+.bP
+SVr4 does much the same, except that
+it returns \fBERR\fP from \fB\%pair_content\fP if the pair was not initialized
+using \fB\%init_pairs\fP
+and
+it returns \fBERR\fP from \fB\%color_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
+\fB\%init_color\fP
returns an error if the terminal does not support
-this feature, e.g., if the \fIinitialize_color\fP capability is absent
+this feature, e.g., if the \fB\%initialize_color\fP capability is absent
from the terminal description.
.TP 5
-\fBstart_color\fP
+\fB\%start_color\fP
returns an error if the color table cannot be allocated.
.RE
.SH NOTES
-In the \fIncurses\fR implementation, there is a separate color activation flag,
-color palette, color pairs table, and associated COLORS and COLOR_PAIRS counts
-for each screen; the \fBstart_color\fR function only affects the current
-screen. The SVr4/XSI interface is not really designed with this in mind, and
+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
+screen.
+The SVr4/XSI interface is not really designed with this in mind, and
historical implementations may use a single shared color palette.
.PP
-Note that setting an implicit background color via a color pair affects only
-character cells that a character write operation explicitly touches. To change
+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 \fBcurs_bkgd\fR(3X).
+scrolling operations, see \fB\%curs_bkgd\fP(3X).
.PP
-Several caveats apply on 386 and 486 machines with VGA-compatible graphics:
+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.
+COLOR_YELLOW is actually brown.
+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 (such as the
+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 blinking yellow foreground instead).
+\*(``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
-This implementation satisfies XSI Curses's minimum maximums
-for \fBCOLORS\fR and \fBCOLOR_PAIRS\fR.
+Applications employing
+.I \%ncurses
+extensions should condition their use on the visibility of the
+.B \%NCURSES_VERSION
+preprocessor macro.
.PP
-The \fBinit_pair\fP routine accepts negative values of foreground
-and background color to support the \fBuse_default_colors\fP extension,
+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 \fBCOLOR_BLACK\fR is the default
+The assumption that \fB\%COLOR_BLACK\fP is the default
background color for all terminals can be modified using the
-\fBassume_default_colors\fP extension.
+\fB\%assume_default_colors\fP(3X) extension.
.PP
This implementation checks the pointers,
e.g., for the values returned by
-\fBcolor_content\fP and \fBpair_content\fP,
+\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 \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,
+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 \fB\%chtype\fP data type (denoted by \fB\%A_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 \fB\%chtype\fP from 16-bits to 32-bits.
+.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,
+limiting values to 15 bits.
+.bP
+\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.
+.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
+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 \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 SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_initscr\fR(3X),
-\fBcurs_attr\fR(3X),
-\fBcurs_variables\fR(3X),
-\fBdefault_colors\fR(3X)
+\fB\%curses\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