Debian Codegraph @

upstream/debian-trixie/man3/color.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
4 .\" *
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: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
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. *
23 .\" *
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 *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_color.3x,v 1.113 2025/01/19 00:49:39 tom Exp $
31 .TH color 3NCURSES 2025-01-18 "ncurses 6.5" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .
48 .SH NAME
49 \fB\%start_color\fP,
50 \fB\%has_colors\fP,
51 \fB\%can_change_color\fP,
52 \fB\%init_pair\fP,
53 \fB\%init_color\fP,
54 \fB\%init_extended_pair\fP,
55 \fB\%init_extended_color\fP,
56 \fB\%color_content\fP,
57 \fB\%pair_content\fP,
58 \fB\%extended_color_content\fP,
59 \fB\%extended_pair_content\fP,
60 \fB\%reset_color_pairs\fP,
61 \fB\%COLOR_PAIR\fP,
62 \fB\%PAIR_NUMBER\fP,
63 \fB\%COLORS\fP,
64 \fB\%COLOR_PAIRS\fP,
65 \fB\%COLOR_BLACK\fP,
66 \fB\%COLOR_RED\fP,
67 \fB\%COLOR_GREEN\fP,
68 \fB\%COLOR_YELLOW\fP,
69 \fB\%COLOR_BLUE\fP,
70 \fB\%COLOR_MAGENTA\fP,
71 \fB\%COLOR_CYAN\fP,
72 \fB\%COLOR_WHITE\fP,
73 \fB\%A_COLOR\fP \-
74 manipulate terminal colors with \fIcurses\fR
75 .SH SYNOPSIS
76 .nf
77 \fB#include <curses.h>
78 .PP
79 \fI/* variables */
80 \fBint COLOR_PAIRS;
81 \fBint COLORS;
82 .PP
83 \fBint start_color(void);
84 .PP
85 \fBbool has_colors(void);
86 \fBbool can_change_color(void);
87 .PP
88 \fBint init_pair(short \fIpair\fP, short \fIf\fP, short \fIb\fP);
89 \fBint init_color(short \fIcolor\fP, short \fIr\fP, short \fIg\fP, short \fIb\fP);
90 \fI/* extensions */
91 \fBint init_extended_pair(int \fIpair\fP, int \fIf\fP, int \fIb\fP);
92 \fBint init_extended_color(int \fIcolor\fP, int \fIr\fP, int \fIg\fP, int \fIb\fP);
93 .PP
94 \fBint color_content(short \fIcolor\fP, short *\fIr\fP, short *\fIg\fP, short *\fIb\fP);
95 \fBint pair_content(short \fIpair\fP, short *\fIf\fP, short *\fIb\fP);
96 \fI/* extensions */
97 \fBint extended_color_content(int \fIcolor\fP, int *\fIr\fP, int *\fIg\fP, int *\fIb\fP);
98 \fBint extended_pair_content(int \fIpair\fP, int *\fIf\fP, int *\fIb\fP);
99 .PP
100 \fI/* extension */
101 \fBvoid reset_color_pairs(void);
102 .PP
103 \fI/* macros */
104 \fBint COLOR_PAIR(int \fIn\fP);
105 \fBPAIR_NUMBER(int \fIattr\fP);
106 \fBCOLOR_BLACK
107 \fBCOLOR_RED
108 \fBCOLOR_GREEN
109 \fBCOLOR_YELLOW
110 \fBCOLOR_BLUE
111 \fBCOLOR_MAGENTA
112 \fBCOLOR_CYAN
113 \fBCOLOR_WHITE
114 \fBA_COLOR
115 .fi
116 .SH DESCRIPTION
117 .SS Overview
118 \fIcurses\fP supports color attributes on terminals with that
119 capability.
120 Call \fB\%start_color\fP
121 (typically right after \fB\%initscr\fP(3NCURSES))
122 to enable this feature.
123 Colors are always used in pairs.
124 A
125 .I "color pair"
126 couples a foreground color for characters with a background color for
127 the blank field on which characters are rendered.
128 \fB\%init_pair\fP initializes a color pair.
129 The macro \fB\%COLOR_PAIR\fP(\fIn\fP) can then convert the pair to a
130 video attribute.
131 .PP
132 If a terminal has the relevant capability,
133 \fB\%init_color\fP permits (re)definition of a color.
134 \fB\%has_colors\fP and \fB\%can_change_color\fP
135 return \fBTRUE\fP or \fBFALSE\fP,
136 depending on whether the terminal has color capability and whether the
137 programmer can change the colors.
138 \fB\%color_content\fP permits extraction of the
139 red,
140 green,
141 and blue components of an initialized color.
142 \fB\%pair_content\fP permits discovery of a color pair's current
143 definition.
144 .SS Rendering
145 .I curses
146 combines the following data to render a character cell.
147 Any of them can include color information.
148 .bP
149 .I curses
150 character attributes,
151 as from \fB\%waddch\fP(3NCURSES) or \fB\%wadd_wch\fP(3NCURSES)
152 .bP
153 window attributes,
154 as from \fB\%wattrset\fP(3NCURSES) or \fB\%wattr_set\fP(3NCURSES)
155 .bP
156 window background character attributes,
157 as from \fB\%wbkgdset\fP(3NCURSES) or \fB\%wbkgrndset\fP(3NCURSES)
158 .PP
159 Per-character and window attributes are usually set through a function
160 parameter containing attributes including a color pair value.
161 Some functions,
162 such as \fB\%wattr_set\fP,
163 use a separate color pair number parameter.
164 .PP
165 The background character is a special case:
166 it includes a character code,
167 just as if it were passed to \fB\%waddch\fP.
168 .PP
169 The \fIcurses\fP library does the actual work of combining these color
170 pairs in an internal function called from \fB\%waddch\fP:
171 .bP
172 If the parameter passed to \fB\%waddch\fP is \fIblank\fP,
173 and it uses the special color pair 0,
174 .RS
175 .bP
176 \fIcurses\fP next checks the window attribute.
177 .bP
178 If the window attribute does not use color pair 0,
179 \fIcurses\fP uses the color pair from the window attribute.
180 .bP
181 Otherwise, \fIcurses\fP uses the background character.
182 .RE
183 .bP
184 If the parameter passed to \fB\%waddch\fP is \fInot blank\fP,
185 or it does not use the special color pair 0,
186 \fIcurses\fP prefers the color pair from the parameter,
187 if it is nonzero.
188 Otherwise, it tries the window attribute next, and finally the
189 background character.
190 .PP
191 Some \fIcurses\fP functions such as \fB\%wprintw\fP call \fB\%waddch\fP.
192 Those do not combine its parameter with a color pair.
193 Consequently those calls use only the window attribute or
194 the background character.
195 .SH CONSTANTS
196 In \fB\%<curses.h>\fP the following macros are defined.
197 These are the standard colors (ISO-6429).
198 \fIcurses\fP also assumes that \fB\%COLOR_BLACK\fP is the default
199 background color for all terminals.
200 .PP
201 .nf
202 \fBCOLOR_BLACK\fP
203 \fBCOLOR_RED\fP
204 \fBCOLOR_GREEN\fP
205 \fBCOLOR_YELLOW\fP
206 \fBCOLOR_BLUE\fP
207 \fBCOLOR_MAGENTA\fP
208 \fBCOLOR_CYAN\fP
209 \fBCOLOR_WHITE\fP
210 .fi
211 .PP
212 Some terminals support more than the eight (8) \*(``ANSI\*('' colors.
213 There are no standard names for those additional colors.
214 .PP
215 .B \%A_COLOR
216 is a bit mask that extracts a color pair identifier from a
217 .IR \%chtype "."
218 .SH VARIABLES
219 .SS COLORS
220 is initialized by \fB\%start_color\fP to the maximum number of colors
221 the terminal can support.
222 .SS COLOR_PAIRS
223 is initialized by \fB\%start_color\fP to the maximum number of color
224 pairs the terminal can support.
225 Often,
226 its value is the product \fB\%COLORS\fP \(mu \fB\%COLORS\fP,
227 but this is not always true.
228 .bP
229 A few terminals use the HLS color space
230 (see \fB\%start_color\fP below),
231 ignoring this rule;
232 and
233 .bP
234 terminals supporting a large number of colors are limited to the number
235 of color pairs that a
236 .I "signed short"
237 value can represent.
238 .SH FUNCTIONS
239 .SS start_color
240 The \fB\%start_color\fP routine requires no arguments.
241 It must be called if the programmer wants to use colors, and before any other
242 color manipulation routine is called.
243 It is good practice to call this routine right after \fB\%initscr\fP.
244 \fB\%start_color\fP does this:
245 .bP
246 It initializes two global variables, \fB\%COLORS\fP and
247 \fB\%COLOR_PAIRS\fP (respectively defining the maximum number of colors
248 and color pairs the terminal can support).
249 .bP
250 It initializes the special color pair \fB\%0\fP to the default foreground
251 and background colors.
252 No other color pairs are initialized.
253 .bP
254 It restores the colors on the terminal to the values
255 they had when the terminal was just turned on.
256 .bP
257 If the terminal supports the \fBinitc\fP \%(\fBinitialize_color\fP) capability,
258 \fB\%start_color\fP
259 initializes its internal table representing the
260 red, green, and blue components of the color palette.
261 .IP
262 The components depend on whether the terminal uses
263 CGA (aka \*(``ANSI\*('') or
264 HLS (i.e., the \fBhls\fP \%(\fBhue_lightness_saturation\fP) capability is set).
265 The table is initialized first for eight basic colors
266 (black, red, green, yellow, blue, magenta, cyan, and white),
267 using weights that depend upon the CGA/HLS choice.
268 For \*(``ANSI\*('' colors the weights are \fB680\fP or \fB0\fP
269 depending on whether the corresponding
270 red, green, or blue component is used or not.
271 That permits using \fB1000\fP to represent bold/bright colors.
272 After the initial eight colors
273 (if the terminal supports more than eight colors)
274 the components are initialized using the same pattern,
275 but with weights of \fB1000\fP.
276 SVr4 uses a similar scheme, but uses \fB1000\fP
277 for the components of the initial eight colors.
278 .IP
279 \fB\%start_color\fP does not attempt to set the terminal's color palette
280 to match its built-in table.
281 An application may use \fB\%init_color\fP to alter the internal table
282 along with the terminal's color.
283 .PP
284 These limits apply to color values and color pairs.
285 Values outside these limits are not valid, and may result in a runtime error:
286 .bP
287 \fBCOLORS\fP corresponds to the terminal database's \fB\%max_colors\fP capability,
288 (see \fB\%terminfo\fP(5)).
289 .bP
290 color values are expected to be in the range \fB0\fP to \fB\%COLORS\-1\fP,
291 inclusive (including \fB0\fP and \fB\%COLORS\-1\fP).
292 .bP
293 a special color value \fB\-1\fP is used in certain extended functions
294 to denote the \fIdefault color\fP (see \fB\%use_default_colors\fP(3NCURSES)).
295 .bP
296 \fB\%COLOR_PAIRS\fP corresponds to
297 the terminal database's \fB\%max_pairs\fP capability,
298 (see \fB\%terminfo\fP(5)).
299 .bP
300 valid color pair values are in the range \fB1\fP to \fB\%COLOR_PAIRS\-1\fP,
301 inclusive.
302 .bP
303 color pair \fB0\fP is special; it denotes \*(``no color\*(''.
304 .IP
305 Color pair \fB0\fP is assumed to be white on black,
306 but is actually whatever the terminal implements before color is initialized.
307 It cannot be modified by the application.
308 .SS has_colors
309 The \fB\%has_colors\fP routine requires no arguments.
310 It returns \fBTRUE\fP if
311 the terminal can manipulate colors; otherwise, it returns \fBFALSE\fP.
312 This routine facilitates writing terminal-independent programs.
313 For example, a programmer can use it to decide
314 whether to use color or some other video attribute.
315 .SS can_change_color
316 The \fB\%can_change_color\fP routine requires no arguments.
317 It returns \fBTRUE\fP if the terminal supports colors
318 and can change their definitions;
319 other, it returns \fBFALSE\fP.
320 This routine facilitates writing terminal-independent programs.
321 .SS init_pair
322 The \fB\%init_pair\fP routine changes the definition of a color pair.
323 It takes three arguments:
324 the number of the color pair to be changed, the foreground
325 color number, and the background color number.
326 For portable applications:
327 .bP
328 The first argument must be a valid color pair value.
329 If default colors are used (see \fB\%use_default_colors\fP(3NCURSES))
330 the upper limit is adjusted to allow for extra pairs which use
331 a default color in foreground and/or background.
332 .bP
333 The second and third arguments must be valid color values.
334 .PP
335 If the color pair was previously initialized,
336 the screen is refreshed and all occurrences of that color pair
337 are changed to the new definition.
338 .PP
339 As an extension,
340 \fI\%ncurses\fP allows you to set color pair \fB0\fP via the
341 \fB\%assume_default_colors\fP(3NCURSES) routine, or to specify the use of
342 default colors (color number \fB\-1\fP) if you first invoke the
343 \fB\%use_default_colors\fP(3NCURSES) routine.
344 .SS init_extended_pair
345 Because \fB\%init_pair\fP uses signed \fBshort\fPs for its parameters,
346 that limits color pairs and color-values
347 to 32767 on modern hardware.
348 The extension \fB\%init_extended_pair\fP uses \fBint\fPs
349 for the color pair and color-value,
350 allowing a larger number of colors to be supported.
351 .SS init_color
352 The \fB\%init_color\fP routine changes the definition of a color.
353 It takes four arguments:
354 the number of the color to be changed followed by three RGB values
355 (for the amounts of red, green, and blue components).
356 .bP
357 The first argument must be a valid color value;
358 default colors are not allowed here.
359 (See the section \fB\%Colors\fP for the default color index.)
360 .bP
361 Each of the last three arguments
362 must be a value in the range \fB0\fP through \fB1000\fP.
363 .PP
364 When \fB\%init_color\fP is used, all
365 occurrences of that color on the screen immediately change to the new
366 definition.
367 .SS init_extended_color
368 Because \fB\%init_color\fP uses signed \fBshort\fPs for its parameters,
369 that limits color-values and their red, green, and blue components
370 to 32767 on modern hardware.
371 The extension \fB\%init_extended_color\fP uses \fBint\fPs
372 for the color value and
373 for setting the red, green, and blue components,
374 allowing a larger number of colors to be supported.
375 .SS color_content
376 The \fB\%color_content\fP routine gives programmers a way to find the intensity
377 of the red, green, and blue (RGB) components in a color.
378 It requires four arguments: the color number, and three addresses
379 of \fBshort\fRs for storing
380 the information about the amounts of red, green, and blue components in the
381 given color.
382 .bP
383 The first argument must be a valid color value, i.e.,
384 \fB0\fP through \fB\%COLORS\-1\fP, inclusive.
385 .bP
386 The values that are stored at the addresses pointed to by the
387 last three arguments are in the range
388 \fB0\fP (no component) through \fB1000\fP
389 (maximum amount of component), inclusive.
390 .SS extended_color_content
391 Because \fB\%color_content\fP uses signed \fBshort\fPs for its parameters,
392 that limits color-values and their red, green, and blue components
393 to 32767 on modern hardware.
394 The extension \fB\%extended_color_content\fP uses \fBint\fPs
395 for the color value and
396 for returning the red, green, and blue components,
397 allowing a larger number of colors to be supported.
398 .SS pair_content
399 The \fB\%pair_content\fP routine allows programmers to find out what colors a
400 given color pair consists of.
401 It requires three arguments: the color pair
402 number, and two addresses of \fBshort\fRs for storing the foreground and the
403 background color numbers.
404 .bP
405 The first argument must be a valid color value,
406 i.e., in the range \fB1\fP through \fB\%COLOR_PAIRS\-1\fP, inclusive.
407 .bP
408 The values that are stored at the addresses pointed
409 to by the second and third arguments are in the
410 range \fB0\fP through \fB\%COLORS\fP, inclusive.
411 .SS extended_pair_content
412 Because \fB\%pair_content\fP uses signed \fBshort\fPs for its parameters,
413 that limits color pair and color-values to 32767 on modern hardware.
414 The extension \fB\%extended_pair_content\fP uses \fBint\fPs
415 for the color pair and
416 for returning the foreground and background colors,
417 allowing a larger number of colors to be supported.
418 .SS reset_color_pairs
419 The extension \fB\%reset_color_pairs\fP tells \fI\%ncurses\fP to discard
420 all of the color pair information which was set with \fB\%init_pair\fP.
421 It also touches the current- and standard-screens, allowing an application to
422 switch color palettes rapidly.
423 .SS COLOR_PAIR
424 \fB\%COLOR_PAIR(\fIn\fB)\fR converts a color pair number to an
425 attribute.
426 Attributes can hold color pairs in the range 0 to 255.
427 If you need a color pair larger than that,
428 you must use functions such as \fB\%attr_set\fP
429 (which pass the color pair as a separate parameter)
430 rather than the legacy functions such as \fB\%attrset\fP.
431 .SS PAIR_NUMBER
432 \fB\%PAIR_NUMBER(\fIattr\fR) extracts the color information from its
433 \fIattr\fP parameter and returns it as a color pair number;
434 it is the inverse operation of \fB\%COLOR_PAIR\fP.
435 .SH RETURN VALUE
436 .B \%can_change_color
437 and
438 .B \%has_colors
439 return
440 .B TRUE
441 or
442 .BR FALSE "."
443 The other functions return
444 .B OK
445 on success and
446 .B ERR
447 on failure.
448 .PP
449 In
450 .IR \%ncurses ","
451 functions returning an
452 .I int
453 recognize several error conditions.
454 .bP
455 All return
456 .B ERR
457 if the screen has not been initialized;
458 see \fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES).
459 .bP
460 All except
461 .B \%start_color
462 return
463 .B ERR
464 if
465 .B \%start_color
466 has not been called,
467 or itself returned
468 .BR ERR "."
469 .bP
470 .B \%start_color
471 returns
472 .B ERR
473 if it cannot allocate memory for its color pair table.
474 .bP
475 .B \%init_color
476 returns
477 .B ERR
478 if the terminal type does not support assignable color values;
479 that is,
480 if the
481 .B \%initialize_color
482 .RB ( initc )
483 capability is absent from its description.
484 .bP
485 .B \%init_color
486 returns
487 .B ERR
488 if any of its
489 .IR r ","
490 .IR g ","
491 .I b
492 arguments is outside the range 0-1000 inclusive.
493 .bP
494 .BR \%init_pair ","
495 .BR \%init_color ","
496 .BR \%init_extended_pair ","
497 .BR \%init_extended_color ","
498 .BR \%color_content ","
499 .BR \%pair_content ","
500 .BR \%extended_color_content ","
501 and
502 .B \%extended_pair_content
503 return
504 .B ERR
505 on attempts to use
506 .RS
507 .bP
508 color identifiers outside the range
509 .RB \%0- COLORS \-1
510 inclusive,
511 the default colors extension notwithstanding,
512 or
513 .bP
514 color pairs identifiers outside the range
515 .RB \%0- COLOR_PAIRS \-1
516 inclusive.
517 .RE
518 .SH NOTES
519 In
520 .IR \%ncurses ","
521 .B \%init_pair
522 accepts negative foreground and background color arguments
523 to support its \fB\%use_default_colors\fP(3NCURSES) extension,
524 but only after the latter function has been called.
525 .PP
526 The assumption that
527 .B \%COLOR_BLACK
528 is the terminal's default background color can be overridden using
529 .IR \%ncurses 's
530 \fB\%assume_default_colors\fP(3NCURSES) extension.
531 .PP
532 In
533 .IR \%ncurses ","
534 each pointer passed to
535 .B \%color_content
536 and
537 .B \%pair_content
538 can be null,
539 in which case the library ignores it,
540 permitting the application to disregard unnecessary information.
541 .PP
542 In
543 .IR \%ncurses ","
544 each screen has a
545 color activation flag,
546 color palette,
547 color pair table,
548 and associated
549 .B \%COLORS
550 and
551 .B \%COLOR_PAIRS
552 values for each screen;
553 .B \%start_color
554 affects only the current screen.
555 The SVr4 and X/Open Curses interface was not really designed
556 with this in mind;
557 historical implementations may use a single shared color palette.
558 .PP
559 Setting an implicit background color via a color pair affects only
560 character cells that a character write operation explicitly touches.
561 To change the background color used
562 when parts of a window are blanked by erasing or scrolling operations,
563 see \fB\%bkgd\fP(3NCURSES).
564 .PP
565 Several caveats apply to IBM PC-compatible machines
566 of the 80486 era and earlier
567 with CGA/EGA/VGA video.
568 .bP
569 .B \%COLOR_YELLOW
570 is actually brown.
571 To get yellow,
572 combine
573 .B \%COLOR_YELLOW
574 with the
575 .B \%A_BOLD
576 attribute.
577 .bP
578 The
579 .B \%A_BLINK
580 attribute should in theory make the background bright.
581 This often fails to work,
582 and even VGA controllers for which it mostly works,
583 such as those from Paradise and compatibles,
584 do the wrong thing
585 when you try to set a bright \*(``yellow\*('' background \(em
586 you get a blinking yellow foreground instead.
587 .bP
588 Color RGB values are not configurable on these devices
589 (in text mode).
590 .SH EXTENSIONS
591 The functions marked as extensions originated in
592 .IR \%ncurses ","
593 and are not found in SVr4
594 .IR curses ,
595 4.4BSD
596 .IR curses ,
597 or any other previous
598 .I curses
599 implementation.
600 .SH PORTABILITY
601 Applications employing
602 .I \%ncurses
603 extensions should condition their use on the visibility of the
604 .B \%NCURSES_VERSION
605 preprocessor macro.
606 .PP
607 X/Open Curses Issue\ 4 describes these functions.
608 It specifies no error conditions for them.
609 .PP
610 .I \%ncurses
611 satisfies X/Open Curses's minimum maximums for
612 .I \%COLORS
613 and
614 .IR \%COLOR_PAIRS "."
615 .PP
616 X/Open Curses does not specify a limit for the number of colors and
617 color pairs which a terminal can support.
618 However,
619 in its use of
620 .I short
621 for the parameters,
622 it carries over SVr4's implementation detail for the compiled
623 .I \%term\%info
624 database,
625 which uses signed 16-bit numbers.
626 .I \%ncurses
627 provides extended versions of the functions using
628 .I short
629 parameters,
630 allowing applications to use larger color and pair identifiers.
631 .PP
632 SVr4
633 .I curses
634 returns
635 .I ERR
636 from
637 .I \%pair_content
638 if its
639 .I pair
640 argument
641 was not initialized using
642 .IR \%init_pairs ,
643 and from
644 .I \%color_content
645 if the terminal does not support changing colors.
646 .I \%ncurses
647 does neither.
648 .SH HISTORY
649 SVr3.2 (1987) introduced color support with all of the symbols in the
650 synopsis above except those marked as extensions.
651 It reserved color pair 0 as the terminal's initial,
652 \*(``uncolored\*('' state,
653 .\" "we assume that color 0 is always a default background.", SVr3.2
654 .\" usr/src/lib/libcurses/screen/start_col.c
655 and limited the number of possible color pairs to 64,
656 because the color pair datum was encoded in six bits of a
657 .IR \%chtype "."
658 .PP
659 SVr4 made only internal changes,
660 such as moving the storage of color state
661 from the
662 .I SCREEN
663 structure
664 (pointed to by
665 .IR SP )
666 to the
667 .I \%TERMINAL
668 structure
669 (pointed to by
670 .IR \%cur_term ")."
671 .PP
672 Other
673 .I curses
674 implementations impose different limits on the number of colors and
675 color pairs.
676 .bP
677 .I \%PCCurses
678 (1987-1990) provided for only 8 colors
679 (and therefore required at most 8\(mu8 = 64 color pairs).
680 .bP
681 .I \%PDCurses
682 (1992-present) inherited the 8-color limitation from
683 .IR \%PCCurses ,
684 but changed this to 256 in version 2.5 (2001),
685 and widened its
686 .I \%chtype
687 from 16 to 32 bits.
688 .bP
689 X/Open Curses (1992-present)
690 specified a new structure type,
691 .IR \%cchar_t ","
692 to store the character code,
693 attribute flags,
694 and color pair identifier,
695 allowing an increased range of color pairs.
696 It specifies a
697 .I short
698 as storing identifiers for colors and color pairs,
699 limiting portable values to 15 bits;
700 negative values are invalid in System\ V.
701 .bP
702 .I \%ncurses
703 (1992-present),
704 in its non-wide configuration,
705 uses 8 bits of
706 .I \%chtype
707 for the color pair identifier.
708 .IP
709 Version 5.3 (2002) offered a wide-character interface,
710 but encoded the color pair identifier with attributes
711 in the character type.
712 .IP
713 Since version 6 (2015),
714 .I \%ncurses
715 uses a separate
716 .I int
717 for the color pair identifier in a
718 .IR \%cchar_t ","
719 introducing extension functions to manage the wider type.
720 When a color pair value fits in 8 bits,
721 .I \%ncurses
722 permits color pair data to be manipulated
723 via the functions taking
724 .I \%chtype
725 arguments,
726 even when a
727 .I curses
728 window uses wide-character cells.
729 .bP
730 NetBSD
731 .I curses
732 used 6 bits for the color pair identifier from 2000
733 (when it first added color support)
734 until 2004.
735 At that point,
736 NetBSD widened the color pair identifier to use 9 bits.
737 As of 2025,
738 that size is unchanged.
739 .\" http://cvsweb.netbsd.org/bsdweb.cgi/src/lib/libcurses/curses.h?rev=1.133
740 .\" indicates a mask of 0x03fe0000.
741 Like
742 .I \%ncurses
743 before version 6,
744 the NetBSD color pair datum is stored in
745 the attributes field of
746 .IR \%cchar_t ","
747 limiting the number of color pairs.
748 .SH SEE ALSO
749 \fB\%ncurses\fP(3NCURSES),
750 \fB\%attr\fP(3NCURSES),
751 \fB\%initscr\fP(3NCURSES),
752 \fB\%curses_variables\fP(3NCURSES),
753 \fB\%default_colors\fP(3NCURSES)