X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_color.3x;h=7a5a02f27de39a69cc34d015fe3e7cbbe1d33273;hp=5a9bfd5c0c79ab30fcea8959303c5cea08a2c046;hb=HEAD;hpb=7e062bb2764a87d98073a90ee65a234a2679f9c1 diff --git a/man/curs_color.3x b/man/curs_color.3x index 5a9bfd5c..7a5a02f2 100644 --- a/man/curs_color.3x +++ b/man/curs_color.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" 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 * @@ -27,17 +27,24 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_color.3x,v 1.84 2023/09/30 20:13:18 tom Exp $ -.TH curs_color 3X 2023-09-30 "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.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 .. -.ds n 5 +. .SH NAME \fB\%start_color\fP, \fB\%has_colors\fP, @@ -52,74 +59,100 @@ \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 \fP +\fB#include .PP -\fBint start_color(void);\fP +\fI/* variables */ +\fBint COLOR_PAIRS; +\fBint COLORS; .PP -\fBbool has_colors(void);\fP -\fBbool can_change_color(void);\fP +\fBint start_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 +\fBbool has_colors(void); +\fBbool can_change_color(void); .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 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 -\fI/* extensions */\fP -\fBvoid reset_color_pairs(void);\fP +\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 -\fBint COLOR_PAIR(int \fIn\fB);\fR -\fBPAIR_NUMBER(\fIattrs\fB);\fR +\fI/* extension */ +\fBvoid reset_color_pairs(void); +.PP +\fBint COLOR_PAIR(int \fIn\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 @@ -172,8 +205,21 @@ There are no standard names for those additional 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. +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. @@ -184,7 +230,7 @@ It is good practice to call this routine right after \fB\%initscr\fP. .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. @@ -221,10 +267,10 @@ 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 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). @@ -234,9 +280,9 @@ 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(\*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\*(''. @@ -258,33 +304,34 @@ 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. +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. @@ -292,7 +339,7 @@ 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; +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 @@ -318,7 +365,7 @@ of \fBshort\fRs for storing 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 @@ -335,12 +382,12 @@ 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 +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 @@ -348,26 +395,28 @@ 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. +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. @@ -414,7 +463,8 @@ from the terminal description. 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 @@ -441,13 +491,55 @@ Paradise and compatibles) do the wrong thing when you try to set a bright \*(``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, @@ -465,64 +557,33 @@ 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, +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)