X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_color.3x;h=9e9b9472dcad7f133a21dfd4929321de5fe57965;hp=9116b773ae310174181ebbc5624787a2387bb786;hb=HEAD;hpb=b1f61d9f3aa244512045a6b02e759825d7049d34 diff --git a/man/curs_color.3x b/man/curs_color.3x index 9116b773..7a5a02f2 100644 --- a/man/curs_color.3x +++ b/man/curs_color.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1998,2000 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 * @@ -26,191 +27,563 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_color.3x,v 1.15 2000/07/08 11:59:51 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 +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +. .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 +\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 \fR -.br -\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 +.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\fR, can be used as a new video attribute. - -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. - -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\%\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: -.TP 5 -- -The value of the first argument -must be between \fB1\fR and \fBCOLOR_PAIRS-1\fR. -.TP 5 -- -The value of the second and -third arguments must be between 0 and \fBCOLORS\fR (the 0 color pair is wired -to white on black and cannot be changed). -.PP -If the color-pair was previously -initialized, the screen is refreshed and all occurrences of that color-pair is -changed to the new definition. - -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. - -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 +.bP +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 valid color values. +.PP +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, +\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. - -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. - -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. - -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). - -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\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. - -.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. - -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. +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\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. +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 \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. +.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 +\fB\%init_color\fP +returns an error if the terminal does not support +this feature, e.g., if the \fB\%initialize_color\fP capability is absent +from the terminal description. +.TP 5 +\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. - -Note that setting an implicit background color via a color pair affects only -character cells that a character write operation explicitly touches. To change +.PP +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). - -Several caveats apply on 386 and 486 machines with VGA-compatible graphics: -.TP 5 -- -COLOR_YELLOW is actually brown. To get yellow, use COLOR_YELLOW combined with -the \fBA_BOLD\fR attribute. -.TP 5 -- -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 +scrolling operations, see \fB\%curs_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\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 Paradise and compatibles) do the wrong thing when you try to set a bright -"yellow" background (you get a blinking yellow foreground instead). -.TP 5 -- +\*(``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 +This implementation satisfies X/Open Curses's minimum maximums +for \fB\%COLORS\fP and \fB\%COLOR_PAIRS\fP. .PP -The \fBinit_pair\fP routine accepts negative values of foreground -and background color to support the \fBuse_default_colors\fP extension, +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 +\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), -\fBdft_fgbg\fR(3X) -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +\fB\%curses\fP(3X), +\fB\%curs_attr\fP(3X), +\fB\%curs_initscr\fP(3X), +\fB\%curs_variables\fP(3X), +\fB\%default_colors\fP(3X)