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.73 2023/07/01 14:23:04 tom Exp $
31 .TH curs_color 3X 2023-07-01 "ncurses 6.4" "Library calls"
46 \fBcan_change_color\fP,
49 \fBinit_extended_pair\fP,
50 \fBinit_extended_color\fP,
53 \fBextended_color_content\fP,
54 \fBextended_pair_content\fP,
55 \fBreset_color_pairs\fP,
57 \fBPAIR_NUMBER\fP \- \fBcurses\fP color manipulation routines
61 \fB#include <curses.h>\fP
63 \fBint start_color(void);\fP
65 \fBbool has_colors(void);\fP
67 \fBbool can_change_color(void);\fP
69 \fBint init_pair(short \fIpair\fB, short \fIf\fB, short \fIb\fB);\fR
71 \fBint init_color(short \fIcolor\fB, short \fIr\fB, short \fIg\fB, short \fIb\fB);\fR
75 \fBint init_extended_pair(int \fIpair\fB, int \fIf\fB, int \fIb\fB);\fR
77 \fBint init_extended_color(int \fIcolor\fB, int \fIr\fB, int \fIg\fB, int \fIb\fB);\fR
79 \fBint color_content(short \fIcolor\fB, short *\fIr\fB, short *\fIg\fB, short *\fIb\fB);\fR
81 \fBint pair_content(short \fIpair\fB, short *\fIf\fB, short *\fIb\fB);\fR
85 \fBint extended_color_content(int \fIcolor\fB, int *\fIr\fB, int *\fIg\fB, int *\fIb\fB);\fR
87 \fBint extended_pair_content(int \fIpair\fB, int *\fIf\fB, int *\fIb\fB);\fR
91 \fBvoid reset_color_pairs(void);\fP
93 \fBint COLOR_PAIR(int \fIn\fB);\fR
95 \fBPAIR_NUMBER(\fIattrs\fB);\fR
98 \fBcurses\fP supports color attributes on terminals with that capability.
99 To use these routines \fBstart_color\fP must be called, usually right after
101 Colors are always used in pairs (referred to as color-pairs).
102 A color-pair consists of a foreground color (for characters) and a background
103 color (for the blank field on which the characters are displayed).
104 A programmer initializes a color-pair with the routine \fBinit_pair\fP.
105 After it has been initialized, \fBCOLOR_PAIR\fP(\fIn\fP)
106 can be used to convert the pair to a video attribute.
108 If a terminal is capable of redefining colors, the programmer can use the
109 routine \fBinit_color\fP to change the definition of a color.
110 The routines \fBhas_colors\fP and \fBcan_change_color\fP
111 return \fBTRUE\fP or \fBFALSE\fP,
112 depending on whether the terminal has color capabilities and whether the
113 programmer can change the colors.
114 The routine \fBcolor_content\fP allows a
115 programmer to extract the amounts of red, green, and blue components in an
117 The routine \fBpair_content\fP allows a programmer to find
118 out how a given color-pair is currently defined.
120 The \fBcurses\fP library combines these inputs to produce the
121 actual foreground and background colors shown on the screen:
123 per-character video attributes (e.g., via \fBwaddch\fP),
125 the window attribute (e.g., by \fBwattrset\fP), and
127 the background character (e.g., \fBwbkgdset\fP).
129 Per-character and window attributes are usually set by a parameter containing
130 video attributes including a color pair value.
131 Some functions such as \fBwattr_set\fP use a separate parameter which
132 is the color pair number.
134 The background character is a special case: it includes a character value,
135 just as if it were passed to \fBwaddch\fP.
137 The \fBcurses\fP library does the actual work of combining these color
138 pairs in an internal function called from \fBwaddch\fP:
140 If the parameter passed to \fBwaddch\fP is \fIblank\fP,
141 and it uses the special color pair 0,
144 \fBcurses\fP next checks the window attribute.
146 If the window attribute does not use color pair 0,
147 \fBcurses\fP uses the color pair from the window attribute.
149 Otherwise, \fBcurses\fP uses the background character.
152 If the parameter passed to \fBwaddch\fP is \fInot blank\fP,
153 or it does not use the special color pair 0,
154 \fBcurses\fP prefers the color pair from the parameter,
156 Otherwise, it tries the window attribute next, and finally the
157 background character.
159 Some \fBcurses\fP functions such as \fBwprintw\fP call \fBwaddch\fP.
160 Those do not combine its parameter with a color pair.
161 Consequently those calls use only the window attribute or
162 the background character.
164 In \fB<curses.h>\fP the following macros are defined.
165 These are the standard colors (ISO-6429).
166 \fBcurses\fP also assumes that \fBCOLOR_BLACK\fP is the default
167 background color for all terminals.
180 Some terminals support more than the eight (8) \*(``ANSI\*('' colors.
181 There are no standard names for those additional colors.
184 is initialized by \fBstart_color\fP to the maximum number of colors
185 the terminal can support.
187 is initialized by \fBstart_color\fP to the maximum number of color pairs
188 the terminal can support.
191 The \fBstart_color\fP routine requires no arguments.
192 It must be called if the programmer wants to use colors, and before any other
193 color manipulation routine is called.
194 It is good practice to call this routine right after \fBinitscr\fP.
195 \fBstart_color\fP does this:
197 It initializes two global variables, \fBCOLORS\fP and
198 \fBCOLOR_PAIRS\fP (respectively defining the maximum number of colors
199 and color-pairs the terminal can support).
201 It initializes the special color pair \fB0\fP to the default foreground
202 and background colors.
203 No other color pairs are initialized.
205 It restores the colors on the terminal to the values
206 they had when the terminal was just turned on.
208 If the terminal supports the \fBinitc\fP (\fBinitialize_color\fP) capability,
210 initializes its internal table representing the
211 red, green, and blue components of the color palette.
213 The components depend on whether the terminal uses
214 CGA (aka \*(``ANSI\*('') or
215 HLS (i.e., the \fBhls\fP (\fBhue_lightness_saturation\fP) capability is set).
216 The table is initialized first for eight basic colors
217 (black, red, green, yellow, blue, magenta, cyan, and white),
218 using weights that depend upon the CGA/HLS choice.
219 For \*(``ANSI\*('' colors the weights are \fB680\fP or \fB0\fP
220 depending on whether the corresponding
221 red, green, or blue component is used or not.
222 That permits using \fB1000\fP to represent bold/bright colors.
223 After the initial eight colors
224 (if the terminal supports more than eight colors)
225 the components are initialized using the same pattern,
226 but with weights of \fB1000\fP.
227 SVr4 uses a similar scheme, but uses \fB1000\fP
228 for the components of the initial eight colors.
230 \fBstart_color\fP does not attempt to set the terminal's color palette
231 to match its built-in table.
232 An application may use \fBinit_color\fP to alter the internal table
233 along with the terminal's color.
235 These limits apply to color values and color pairs.
236 Values outside these limits are not legal, and may result in a runtime error:
238 \fBCOLORS\fP corresponds to the terminal database's \fBmax_colors\fP capability,
239 (see \fBterminfo\fP(\*n)).
241 color values are expected to be in the range \fB0\fP to \fBCOLORS\-1\fP,
242 inclusive (including \fB0\fP and \fBCOLORS\-1\fP).
244 a special color value \fB\-1\fP is used in certain extended functions
245 to denote the \fIdefault color\fP (see \fBuse_default_colors\fP(3X)).
247 \fBCOLOR_PAIRS\fP corresponds to
248 the terminal database's \fBmax_pairs\fP capability,
249 (see \fBterminfo\fP(\*n)).
251 legal color pair values are in the range \fB1\fP to \fBCOLOR_PAIRS\-1\fP,
254 color pair \fB0\fP is special; it denotes \*(``no color\*(''.
256 Color pair \fB0\fP is assumed to be white on black,
257 but is actually whatever the terminal implements before color is initialized.
258 It cannot be modified by the application.
260 The \fBhas_colors\fP routine requires no arguments.
261 It returns \fBTRUE\fP if
262 the terminal can manipulate colors; otherwise, it returns \fBFALSE\fP.
263 This routine facilitates writing terminal-independent programs.
264 For example, a programmer can use it to decide
265 whether to use color or some other video attribute.
267 The \fBcan_change_color\fP routine requires no arguments.
268 It returns \fBTRUE\fP if the terminal supports colors
269 and can change their definitions;
270 other, it returns \fBFALSE\fP.
271 This routine facilitates writing terminal-independent programs.
273 The \fBinit_pair\fP routine changes the definition of a color-pair.
274 It takes three arguments:
275 the number of the color-pair to be changed, the foreground
276 color number, and the background color number.
277 For portable applications:
279 The first argument must be a legal color pair value.
280 If default colors are used (see \fBuse_default_colors\fP(3X))
281 the upper limit is adjusted to allow for extra pairs which use
282 a default color in foreground and/or background.
284 The second and third arguments must be legal color values.
286 If the color-pair was previously initialized,
287 the screen is refreshed and all occurrences of that color-pair
288 are changed to the new definition.
290 As an extension, ncurses allows you to set color pair \fB0\fP via
291 the \fBassume_default_colors\fP(3X) routine, or to specify the use of
292 default colors (color number \fB\-1\fP) if you first invoke the
293 \fBuse_default_colors\fP(3X) routine.
294 .SS init_extended_pair
295 Because \fBinit_pair\fP uses signed \fBshort\fPs for its parameters,
296 that limits color-pairs and color-values
297 to 32767 on modern hardware.
298 The extension \fBinit_extended_pair\fP uses \fBint\fPs
299 for the color-pair and color-value,
300 allowing a larger number of colors to be supported.
302 The \fBinit_color\fP routine changes the definition of a color.
303 It takes four arguments:
304 the number of the color to be changed followed by three RGB values
305 (for the amounts of red, green, and blue components).
307 The first argument must be a legal color value;
308 default colors are not allowed here.
309 (See the section \fBColors\fP for the default color index.)
311 Each of the last three arguments
312 must be a value in the range \fB0\fP through \fB1000\fP.
314 When \fBinit_color\fP is used, all
315 occurrences of that color on the screen immediately change to the new
317 .SS init_extended_color
318 Because \fBinit_color\fP uses signed \fBshort\fPs for its parameters,
319 that limits color-values and their red, green, and blue components
320 to 32767 on modern hardware.
321 The extension \fBinit_extended_color\fP uses \fBint\fPs
322 for the color value and
323 for setting the red, green, and blue components,
324 allowing a larger number of colors to be supported.
326 The \fBcolor_content\fP routine gives programmers a way to find the intensity
327 of the red, green, and blue (RGB) components in a color.
328 It requires four arguments: the color number, and three addresses
329 of \fBshort\fRs for storing
330 the information about the amounts of red, green, and blue components in the
333 The first argument must be a legal color value, i.e.,
334 \fB0\fP through \fBCOLORS\-1\fP, inclusive.
336 The values that are stored at the addresses pointed to by the
337 last three arguments are in the range
338 \fB0\fP (no component) through \fB1000\fP
339 (maximum amount of component), inclusive.
340 .SS extended_color_content
341 Because \fBcolor_content\fP uses signed \fBshort\fPs for its parameters,
342 that limits color-values and their red, green, and blue components
343 to 32767 on modern hardware.
344 The extension \fBextended_color_content\fP uses \fBint\fPs
345 for the color value and
346 for returning the red, green, and blue components,
347 allowing a larger number of colors to be supported.
349 The \fBpair_content\fP routine allows programmers to find out what colors a
350 given color-pair consists of.
351 It requires three arguments: the color-pair
352 number, and two addresses of \fBshort\fRs for storing the foreground and the
353 background color numbers.
355 The first argument must be a legal color value,
356 i.e., in the range \fB1\fP through \fBCOLOR_PAIRS\-1\fP, inclusive.
358 The values that are stored at the addresses pointed
359 to by the second and third arguments are in the
360 range \fB0\fP through \fBCOLORS\fP, inclusive.
361 .SS extended_pair_content
362 Because \fBpair_content\fP uses signed \fBshort\fPs for its parameters,
363 that limits color-pair and color-values to 32767 on modern hardware.
364 The extension \fBextended_pair_content\fP uses \fBint\fPs
365 for the color pair and
366 for returning the foreground and background colors,
367 allowing a larger number of colors to be supported.
368 .SS reset_color_pairs
369 The extension \fBreset_color_pairs\fP tells ncurses to discard all
370 of the color-pair information which was set with \fBinit_pair\fP.
371 It also touches the current- and standard-screens, allowing an application to
372 switch color palettes rapidly.
374 \fBPAIR_NUMBER(\fIattrs\fR) extracts the color
375 value from its \fIattrs\fP parameter and returns it as a color pair number.
377 Its inverse \fBCOLOR_PAIR(\fIn\fB)\fR converts a color pair number
379 Attributes can hold color pairs in the range 0 to 255.
380 If you need a color pair larger than that, you must use functions
381 such as \fBattr_set\fP (which pass the color pair as a separate parameter)
382 rather than the legacy functions such as \fBattrset\fP.
384 The routines \fBcan_change_color\fP and \fBhas_colors\fP return \fBTRUE\fP
387 All other routines return the integer \fBERR\fP upon failure and an \fBOK\fP
388 (SVr4 specifies only \*(``an integer value
389 other than \fBERR\fP\*('') upon successful completion.
391 X/Open defines no error conditions.
392 SVr4 does document some error conditions which apply in general:
394 This implementation will return \fBERR\fP on attempts to
395 use color values outside the range \fB0\fP to \fBCOLORS\fP\-1
396 (except for the default colors extension),
397 or use color pairs outside the range \fB0\fP to \fBCOLOR_PAIRS\-1\fP.
399 Color values used in \fBinit_color\fP must be
400 in the range \fB0\fP to \fB1000\fP.
402 An error is returned from all functions
403 if the terminal has not been initialized.
405 An error is returned from secondary functions such as \fBinit_pair\fP
406 if \fBstart_color\fP was not called.
408 SVr4 does much the same, except that
409 it returns \fBERR\fP from \fBpair_content\fP if the pair was not initialized
410 using \fBinit_pairs\fP
412 it returns \fBERR\fP from \fBcolor_content\fP
413 if the terminal does not support changing colors.
415 This implementation does not return \fBERR\fP for either case.
417 Specific functions make additional checks:
421 returns an error if the terminal does not support
422 this feature, e.g., if the \fBinitialize_color\fP capability is absent
423 from the terminal description.
426 returns an error if the color table cannot be allocated.
429 In the \fBncurses\fP implementation, there is a separate color activation flag,
430 color palette, color pairs table,
431 and associated \fBCOLORS\fP and \fBCOLOR_PAIRS\fP counts
432 for each screen; the \fBstart_color\fP function only affects the current
434 The SVr4/XSI interface is not really designed with this in mind, and
435 historical implementations may use a single shared color palette.
437 Setting an implicit background color via a color pair affects only
438 character cells that a character write operation explicitly touches.
440 the background color used when parts of a window are blanked by erasing or
441 scrolling operations, see \fBcurs_bkgd\fP(3X).
443 Several caveats apply on older x86 machines
444 (e.g., i386, i486) with VGA-compatible graphics:
446 COLOR_YELLOW is actually brown.
447 To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fP attribute.
449 The A_BLINK attribute should in theory cause the background to go bright.
450 This often fails to work, and even some cards for which it mostly works
452 Paradise and compatibles) do the wrong thing when you try to set a bright
453 \*(``yellow\*('' background (you get a blinking yellow foreground instead).
455 Color RGB values are not settable.
457 SVr3.2 introduced color support to curses in 1987.
459 SVr4 made internal changes,
460 e.g., moving the storage for the color state
461 from \fBSP\fP (the \fBSCREEN\fP structure)
462 to \fBcur_term\fP (the \fBTERMINAL\fP structure),
463 but provided the same set of library functions.
465 SVr4 curses limits the number of color pairs to 64,
466 reserving color pair zero (0) as the terminal's initial uncolored state.
467 This limit arises because the color pair information is a bitfield
468 in the \fBchtype\fP data type (denoted by \fBA_COLOR\fP).
470 Other implementations of curses had different limits:
472 PCCurses (1987-1990) provided for only eight (8) colors.
474 PDCurses (1992-present) inherited the 8-color limitation from PCCurses,
475 but changed this to 256 in version 2.5 (2001),
476 along with changing \fBchtype\fP from 16-bits to 32-bits.
478 X/Open Curses (1992-present)
479 added a new structure \fBcchar_t\fP to store the character,
480 attributes and color-pair values, allowing increased range of color-pairs.
481 Both color-pairs and color-values used a signed \fBshort\fP,
482 limiting values to 15 bits.
484 ncurses (1992-present) uses eight bits for \fBA_COLOR\fP in \fBchtype\fP values.
486 Version 5.3 provided a wide-character interface (2002),
487 but left color-pairs as part of the attributes-field.
489 Since version 6 (2015),
490 ncurses uses a separate \fBint\fP for color-pairs in the \fBcchar_t\fP values.
491 When those color-pair values fit in 8 bits,
492 ncurses allows color-pairs to be manipulated
493 via the functions using \fBchtype\fP values.
495 NetBSD curses used 6 bits from
496 2000 (when colors were first supported) until 2004.
497 At that point, NetBSD changed to use 10 bits.
498 As of 2021, that size is unchanged.
499 Like ncurses before version 6,
500 the NetBSD color-pair information is stored in
501 the attributes field of \fBcchar_t\fP, limiting the number of color-pairs
502 by the size of the bitfield.
505 The functions marked as extensions were designed for \fBncurses\fP(3X),
506 and are not found in SVr4 curses, 4.4BSD curses,
507 or any other previous version of curses.
509 This implementation satisfies XSI Curses's minimum maximums
510 for \fBCOLORS\fP and \fBCOLOR_PAIRS\fP.
512 The \fBinit_pair\fP routine accepts negative values of foreground
513 and background color to support the \fBuse_default_colors\fP(3X) extension,
514 but only if that routine has been first invoked.
516 The assumption that \fBCOLOR_BLACK\fP is the default
517 background color for all terminals can be modified using the
518 \fBassume_default_colors\fP(3X) extension.
520 This implementation checks the pointers,
521 e.g., for the values returned by
522 \fBcolor_content\fP and \fBpair_content\fP,
523 and will treat those as optional parameters when null.
525 X/Open Curses does not specify a limit for the number of colors and
526 color pairs which a terminal can support.
527 However, in its use of \fBshort\fP for the parameters,
528 it carries over SVr4's implementation detail for the compiled
529 terminfo database, which uses signed 16-bit numbers.
530 This implementation provides extended versions of those functions
531 which use \fBshort\fP parameters,
532 allowing applications to use larger color- and pair-numbers.
534 The \fBreset_color_pairs\fP function is an extension of ncurses.
537 \fBcurs_initscr\fP(3X),
539 \fBcurs_variables\fP(3X),
540 \fBdefault_colors\fP(3X)
projects / ncurses.git / blob