1 .\"***************************************************************************
2 .\" Copyright 2018-2022,2023 Thomas E. Dickey *
3 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
28 .\"***************************************************************************
30 .\" $Id: curs_color.3x,v 1.93 2023/12/16 21:07:24 tom Exp $
31 .TH curs_color 3X 2023-12-16 "ncurses 6.4" "Library calls"
51 \fB\%can_change_color\fP,
54 \fB\%init_extended_pair\fP,
55 \fB\%init_extended_color\fP,
56 \fB\%color_content\fP,
58 \fB\%extended_color_content\fP,
59 \fB\%extended_pair_content\fP,
60 \fB\%reset_color_pairs\fP,
70 \fB\%COLOR_MAGENTA\fP,
72 \fB\%COLOR_WHITE\fP \-
73 manipulate terminal colors with \fIcurses\fR
76 \fB#include <curses.h>
78 \fBint start_color(void);
80 \fBbool has_colors(void);
81 \fBbool can_change_color(void);
83 \fBint init_pair(short \fIpair\fP, short \fIf\fP, short \fIb\fP);
84 \fBint init_color(short \fIcolor\fP, short \fIr\fP, short \fIg\fP, short \fIb\fP);
86 \fBint init_extended_pair(int \fIpair\fP, int \fIf\fP, int \fIb\fP);
87 \fBint init_extended_color(int \fIcolor\fP, int \fIr\fP, int \fIg\fP, int \fIb\fP);
89 \fBint color_content(short \fIcolor\fP, short *\fIr\fP, short *\fIg\fP, short *\fIb\fP);
90 \fBint pair_content(short \fIpair\fP, short *\fIf\fP, short *\fIb\fP);
92 \fBint extended_color_content(int \fIcolor\fP, int *\fIr\fP, int *\fIg\fP, int *\fIb\fP);
93 \fBint extended_pair_content(int \fIpair\fP, int *\fIf\fP, int *\fIb\fP);
96 \fBvoid reset_color_pairs(void);
98 \fBint COLOR_PAIR(int \fIn\fP);
99 \fBPAIR_NUMBER(int \fIattr\fP);
103 \fIcurses\fP supports color attributes on terminals with that capability.
104 To use these routines \fB\%start_color\fP must be called, usually right after
106 Colors are always used in pairs (referred to as color pairs).
107 A color pair consists of a foreground color (for characters) and a background
108 color (for the blank field on which the characters are displayed).
109 A programmer initializes a color pair with the routine \fB\%init_pair\fP.
110 After it has been initialized, \fB\%COLOR_PAIR\fP(\fIn\fP)
111 can be used to convert the pair to a video attribute.
113 If a terminal is capable of redefining colors, the programmer can use the
114 routine \fB\%init_color\fP to change the definition of a color.
115 The routines \fB\%has_colors\fP and \fB\%can_change_color\fP
116 return \fBTRUE\fP or \fBFALSE\fP,
117 depending on whether the terminal has color capabilities and whether the
118 programmer can change the colors.
119 The routine \fB\%color_content\fP allows a
120 programmer to extract the amounts of red, green, and blue components in an
122 The routine \fB\%pair_content\fP allows a programmer to find
123 out how a given color pair is currently defined.
125 The \fIcurses\fP library combines these inputs to produce the
126 actual foreground and background colors shown on the screen:
128 per-character video attributes (e.g., via \fB\%waddch\fP),
130 the window attribute (e.g., by \fB\%wattrset\fP), and
132 the background character (e.g., \fB\%wbkgdset\fP).
134 Per-character and window attributes are usually set by a parameter containing
135 video attributes including a color pair value.
136 Some functions such as \fB\%wattr_set\fP use a separate parameter which
137 is the color pair number.
139 The background character is a special case: it includes a character value,
140 just as if it were passed to \fB\%waddch\fP.
142 The \fIcurses\fP library does the actual work of combining these color
143 pairs in an internal function called from \fB\%waddch\fP:
145 If the parameter passed to \fB\%waddch\fP is \fIblank\fP,
146 and it uses the special color pair 0,
149 \fIcurses\fP next checks the window attribute.
151 If the window attribute does not use color pair 0,
152 \fIcurses\fP uses the color pair from the window attribute.
154 Otherwise, \fIcurses\fP uses the background character.
157 If the parameter passed to \fB\%waddch\fP is \fInot blank\fP,
158 or it does not use the special color pair 0,
159 \fIcurses\fP prefers the color pair from the parameter,
161 Otherwise, it tries the window attribute next, and finally the
162 background character.
164 Some \fIcurses\fP functions such as \fB\%wprintw\fP call \fB\%waddch\fP.
165 Those do not combine its parameter with a color pair.
166 Consequently those calls use only the window attribute or
167 the background character.
169 In \fB\%<curses.h>\fP the following macros are defined.
170 These are the standard colors (ISO-6429).
171 \fIcurses\fP also assumes that \fB\%COLOR_BLACK\fP is the default
172 background color for all terminals.
185 Some terminals support more than the eight (8) \*(``ANSI\*('' colors.
186 There are no standard names for those additional colors.
189 is initialized by \fB\%start_color\fP to the maximum number of colors
190 the terminal can support.
192 is initialized by \fB\%start_color\fP to the maximum number of color pairs
193 the terminal can support.
196 The \fB\%start_color\fP routine requires no arguments.
197 It must be called if the programmer wants to use colors, and before any other
198 color manipulation routine is called.
199 It is good practice to call this routine right after \fB\%initscr\fP.
200 \fB\%start_color\fP does this:
202 It initializes two global variables, \fB\%COLORS\fP and
203 \fB\%COLOR_PAIRS\fP (respectively defining the maximum number of colors
204 and color pairs the terminal can support).
206 It initializes the special color pair \fB\%0\fP to the default foreground
207 and background colors.
208 No other color pairs are initialized.
210 It restores the colors on the terminal to the values
211 they had when the terminal was just turned on.
213 If the terminal supports the \fBinitc\fP \%(\fBinitialize_color\fP) capability,
215 initializes its internal table representing the
216 red, green, and blue components of the color palette.
218 The components depend on whether the terminal uses
219 CGA (aka \*(``ANSI\*('') or
220 HLS (i.e., the \fBhls\fP \%(\fBhue_lightness_saturation\fP) capability is set).
221 The table is initialized first for eight basic colors
222 (black, red, green, yellow, blue, magenta, cyan, and white),
223 using weights that depend upon the CGA/HLS choice.
224 For \*(``ANSI\*('' colors the weights are \fB680\fP or \fB0\fP
225 depending on whether the corresponding
226 red, green, or blue component is used or not.
227 That permits using \fB1000\fP to represent bold/bright colors.
228 After the initial eight colors
229 (if the terminal supports more than eight colors)
230 the components are initialized using the same pattern,
231 but with weights of \fB1000\fP.
232 SVr4 uses a similar scheme, but uses \fB1000\fP
233 for the components of the initial eight colors.
235 \fB\%start_color\fP does not attempt to set the terminal's color palette
236 to match its built-in table.
237 An application may use \fB\%init_color\fP to alter the internal table
238 along with the terminal's color.
240 These limits apply to color values and color pairs.
241 Values outside these limits are not valid, and may result in a runtime error:
243 \fBCOLORS\fP corresponds to the terminal database's \fB\%max_colors\fP capability,
244 (see \fB\%terminfo\fP(5)).
246 color values are expected to be in the range \fB0\fP to \fB\%COLORS\-1\fP,
247 inclusive (including \fB0\fP and \fB\%COLORS\-1\fP).
249 a special color value \fB\-1\fP is used in certain extended functions
250 to denote the \fIdefault color\fP (see \fB\%use_default_colors\fP(3X)).
252 \fB\%COLOR_PAIRS\fP corresponds to
253 the terminal database's \fB\%max_pairs\fP capability,
254 (see \fB\%terminfo\fP(5)).
256 valid color pair values are in the range \fB1\fP to \fB\%COLOR_PAIRS\-1\fP,
259 color pair \fB0\fP is special; it denotes \*(``no color\*(''.
261 Color pair \fB0\fP is assumed to be white on black,
262 but is actually whatever the terminal implements before color is initialized.
263 It cannot be modified by the application.
265 The \fB\%has_colors\fP routine requires no arguments.
266 It returns \fBTRUE\fP if
267 the terminal can manipulate colors; otherwise, it returns \fBFALSE\fP.
268 This routine facilitates writing terminal-independent programs.
269 For example, a programmer can use it to decide
270 whether to use color or some other video attribute.
272 The \fB\%can_change_color\fP routine requires no arguments.
273 It returns \fBTRUE\fP if the terminal supports colors
274 and can change their definitions;
275 other, it returns \fBFALSE\fP.
276 This routine facilitates writing terminal-independent programs.
278 The \fB\%init_pair\fP routine changes the definition of a color pair.
279 It takes three arguments:
280 the number of the color pair to be changed, the foreground
281 color number, and the background color number.
282 For portable applications:
284 The first argument must be a valid color pair value.
285 If default colors are used (see \fB\%use_default_colors\fP(3X))
286 the upper limit is adjusted to allow for extra pairs which use
287 a default color in foreground and/or background.
289 The second and third arguments must be valid color values.
291 If the color pair was previously initialized,
292 the screen is refreshed and all occurrences of that color pair
293 are changed to the new definition.
296 \fI\%ncurses\fP allows you to set color pair \fB0\fP via the
297 \fB\%assume_default_colors\fP(3X) routine, or to specify the use of
298 default colors (color number \fB\-1\fP) if you first invoke the
299 \fB\%use_default_colors\fP(3X) routine.
300 .SS init_extended_pair
301 Because \fB\%init_pair\fP uses signed \fBshort\fPs for its parameters,
302 that limits color pairs and color-values
303 to 32767 on modern hardware.
304 The extension \fB\%init_extended_pair\fP uses \fBint\fPs
305 for the color pair and color-value,
306 allowing a larger number of colors to be supported.
308 The \fB\%init_color\fP routine changes the definition of a color.
309 It takes four arguments:
310 the number of the color to be changed followed by three RGB values
311 (for the amounts of red, green, and blue components).
313 The first argument must be a valid color value;
314 default colors are not allowed here.
315 (See the section \fB\%Colors\fP for the default color index.)
317 Each of the last three arguments
318 must be a value in the range \fB0\fP through \fB1000\fP.
320 When \fB\%init_color\fP is used, all
321 occurrences of that color on the screen immediately change to the new
323 .SS init_extended_color
324 Because \fB\%init_color\fP uses signed \fBshort\fPs for its parameters,
325 that limits color-values and their red, green, and blue components
326 to 32767 on modern hardware.
327 The extension \fB\%init_extended_color\fP uses \fBint\fPs
328 for the color value and
329 for setting the red, green, and blue components,
330 allowing a larger number of colors to be supported.
332 The \fB\%color_content\fP routine gives programmers a way to find the intensity
333 of the red, green, and blue (RGB) components in a color.
334 It requires four arguments: the color number, and three addresses
335 of \fBshort\fRs for storing
336 the information about the amounts of red, green, and blue components in the
339 The first argument must be a valid color value, i.e.,
340 \fB0\fP through \fB\%COLORS\-1\fP, inclusive.
342 The values that are stored at the addresses pointed to by the
343 last three arguments are in the range
344 \fB0\fP (no component) through \fB1000\fP
345 (maximum amount of component), inclusive.
346 .SS extended_color_content
347 Because \fB\%color_content\fP uses signed \fBshort\fPs for its parameters,
348 that limits color-values and their red, green, and blue components
349 to 32767 on modern hardware.
350 The extension \fB\%extended_color_content\fP uses \fBint\fPs
351 for the color value and
352 for returning the red, green, and blue components,
353 allowing a larger number of colors to be supported.
355 The \fB\%pair_content\fP routine allows programmers to find out what colors a
356 given color pair consists of.
357 It requires three arguments: the color pair
358 number, and two addresses of \fBshort\fRs for storing the foreground and the
359 background color numbers.
361 The first argument must be a valid color value,
362 i.e., in the range \fB1\fP through \fB\%COLOR_PAIRS\-1\fP, inclusive.
364 The values that are stored at the addresses pointed
365 to by the second and third arguments are in the
366 range \fB0\fP through \fB\%COLORS\fP, inclusive.
367 .SS extended_pair_content
368 Because \fB\%pair_content\fP uses signed \fBshort\fPs for its parameters,
369 that limits color pair and color-values to 32767 on modern hardware.
370 The extension \fB\%extended_pair_content\fP uses \fBint\fPs
371 for the color pair and
372 for returning the foreground and background colors,
373 allowing a larger number of colors to be supported.
374 .SS reset_color_pairs
375 The extension \fB\%reset_color_pairs\fP tells \fI\%ncurses\fP to discard
376 all of the color pair information which was set with \fB\%init_pair\fP.
377 It also touches the current- and standard-screens, allowing an application to
378 switch color palettes rapidly.
380 \fB\%COLOR_PAIR(\fIn\fB)\fR converts a color pair number to an
382 Attributes can hold color pairs in the range 0 to 255.
383 If you need a color pair larger than that,
384 you must use functions such as \fB\%attr_set\fP
385 (which pass the color pair as a separate parameter)
386 rather than the legacy functions such as \fB\%attrset\fP.
388 \fB\%PAIR_NUMBER(\fIattr\fR) extracts the color information from its
389 \fIattr\fP parameter and returns it as a color pair number;
390 it is the inverse operation of \fB\%COLOR_PAIR\fP.
392 The routines \fB\%can_change_color\fP and \fB\%has_colors\fP return \fBTRUE\fP
395 All other routines return the integer \fBERR\fP upon failure and an \fBOK\fP
396 (SVr4 specifies only \*(``an integer value
397 other than \fBERR\fP\*('') upon successful completion.
399 X/Open defines no error conditions.
400 SVr4 does document some error conditions which apply in general:
402 This implementation will return \fBERR\fP on attempts to
403 use color values outside the range \fB0\fP to \fB\%COLORS\fP\-1
404 (except for the default colors extension),
405 or use color pairs outside the range \fB0\fP to \fB\%COLOR_PAIRS\-1\fP.
407 Color values used in \fB\%init_color\fP must be
408 in the range \fB0\fP to \fB1000\fP.
410 An error is returned from all functions
411 if the terminal has not been initialized.
413 An error is returned from secondary functions such as \fB\%init_pair\fP
414 if \fB\%start_color\fP was not called.
416 SVr4 does much the same, except that
417 it returns \fBERR\fP from \fB\%pair_content\fP if the pair was not initialized
418 using \fB\%init_pairs\fP
420 it returns \fBERR\fP from \fB\%color_content\fP
421 if the terminal does not support changing colors.
423 This implementation does not return \fBERR\fP for either case.
425 Specific functions make additional checks:
429 returns an error if the terminal does not support
430 this feature, e.g., if the \fB\%initialize_color\fP capability is absent
431 from the terminal description.
434 returns an error if the color table cannot be allocated.
437 In the \fI\%ncurses\fP implementation,
438 there is a separate color activation flag,
439 color palette, color pairs table,
440 and associated \fB\%COLORS\fP and \fB\%COLOR_PAIRS\fP counts
441 for each screen; the \fB\%start_color\fP function only affects the current
443 The SVr4/XSI interface is not really designed with this in mind, and
444 historical implementations may use a single shared color palette.
446 Setting an implicit background color via a color pair affects only
447 character cells that a character write operation explicitly touches.
449 the background color used when parts of a window are blanked by erasing or
450 scrolling operations, see \fB\%curs_bkgd\fP(3X).
452 Several caveats apply on older x86 machines
453 (e.g., i386, i486) with VGA-compatible graphics:
455 COLOR_YELLOW is actually brown.
456 To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fP attribute.
458 The A_BLINK attribute should in theory cause the background to go bright.
459 This often fails to work, and even some cards for which it mostly works
461 Paradise and compatibles) do the wrong thing when you try to set a bright
462 \*(``yellow\*('' background (you get a blinking yellow foreground instead).
464 Color RGB values are not settable.
466 The functions marked as extensions were designed for
468 and are not found in SVr4 curses, 4.4BSD curses,
469 or any other previous version of curses.
471 This implementation satisfies XSI Curses's minimum maximums
472 for \fB\%COLORS\fP and \fB\%COLOR_PAIRS\fP.
474 The \fB\%init_pair\fP routine accepts negative values of foreground
475 and background color to support the \fB\%use_default_colors\fP(3X) extension,
476 but only if that routine has been first invoked.
478 The assumption that \fB\%COLOR_BLACK\fP is the default
479 background color for all terminals can be modified using the
480 \fB\%assume_default_colors\fP(3X) extension.
482 This implementation checks the pointers,
483 e.g., for the values returned by
484 \fB\%color_content\fP and \fB\%pair_content\fP,
485 and will treat those as optional parameters when null.
487 X/Open Curses does not specify a limit for the number of colors and
488 color pairs which a terminal can support.
489 However, in its use of \fBshort\fP for the parameters,
490 it carries over SVr4's implementation detail for the compiled
491 terminfo database, which uses signed 16-bit numbers.
492 This implementation provides extended versions of those functions
493 which use \fBshort\fP parameters,
494 allowing applications to use larger color- and pair-numbers.
496 The \fB\%reset_color_pairs\fP function is an extension of
499 SVr3.2 introduced color support to curses in 1987.
501 SVr4 made internal changes,
502 e.g., moving the storage for the color state
503 from \fBSP\fP (the \fBSCREEN\fP structure)
504 to \fB\%cur_term\fP (the \fB\%TERMINAL\fP structure),
505 but provided the same set of library functions.
507 SVr4 curses limits the number of color pairs to 64,
508 reserving color pair zero (0) as the terminal's initial uncolored state.
509 This limit arises because the color pair information is a bitfield
510 in the \fB\%chtype\fP data type (denoted by \fB\%A_COLOR\fP).
512 Other implementations of curses had different limits:
514 PCCurses (1987-1990) provided for only eight (8) colors.
516 PDCurses (1992-present) inherited the 8-color limitation from PCCurses,
517 but changed this to 256 in version 2.5 (2001),
518 along with changing \fB\%chtype\fP from 16-bits to 32-bits.
520 X/Open Curses (1992-present)
521 added a new structure \fB\%cchar_t\fP to store the character,
522 attributes and color pair values, allowing increased range of color pairs.
523 Both color pairs and color-values used a signed \fBshort\fP,
524 limiting values to 15 bits.
526 \fI\%ncurses\fP (1992-present) uses eight bits
527 for \fB\%A_COLOR\fP in \fB\%chtype\fP values.
529 Version 5.3 provided a wide-character interface (2002),
530 but left color pairs as part of the attributes-field.
532 Since version 6 (2015),
533 ncurses uses a separate \fBint\fP for color pairs in the \fB\%cchar_t\fP values.
534 When those color pair values fit in 8 bits,
535 ncurses allows color pairs to be manipulated
536 via the functions using \fB\%chtype\fP values.
538 NetBSD curses used 6 bits from
539 2000 (when colors were first supported) until 2004.
540 At that point, NetBSD changed to use 10 bits.
541 As of 2021, that size is unchanged.
542 Like \fI\%ncurses\fP before version 6,
543 the NetBSD color pair information is stored in
544 the attributes field of \fB\%cchar_t\fP, limiting the number of color pairs
545 by the size of the bitfield.
548 \fB\%curs_attr\fP(3X),
549 \fB\%curs_initscr\fP(3X),
550 \fB\%curs_variables\fP(3X),
551 \fB\%default_colors\fP(3X)
projects / ncurses.git / blob