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