| 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.126 2025/08/23 22:39:20 tom Exp $ |
| 31 |
.TH color 3NCURSES 2025-08-23 "ncurses 6.6" "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 |
\fIcurses\fP next checks the window attribute. |
| 175 |
.RS |
| 176 |
.bP |
| 177 |
If the window attribute does not use color pair 0, |
| 178 |
\fIcurses\fP uses the color pair from the window attribute. |
| 179 |
.bP |
| 180 |
Otherwise, \fIcurses\fP uses the background character. |
| 181 |
.RE |
| 182 |
.bP |
| 183 |
If the parameter passed to \fB\%waddch\fP is \fInot blank\fP, |
| 184 |
or it does not use the special color pair 0, |
| 185 |
\fIcurses\fP prefers the color pair from the parameter, |
| 186 |
if it is nonzero. |
| 187 |
Otherwise, it tries the window attribute next, and finally the |
| 188 |
background character. |
| 189 |
.PP |
| 190 |
Some \fIcurses\fP functions such as \fB\%wprintw\fP call \fB\%waddch\fP. |
| 191 |
Those do not combine its parameter with a color pair. |
| 192 |
Consequently those calls use only the window attribute or |
| 193 |
the background character. |
| 194 |
.SH CONSTANTS |
| 195 |
ISO\ 6429 and ECMA-48 |
| 196 |
define eight standard colors |
| 197 |
(also known as \*(``ANSI\*('' colors). |
| 198 |
.I curses\.h |
| 199 |
defines object-like macros |
| 200 |
.BR \%COLOR_BLACK "," |
| 201 |
.BR \%COLOR_RED "," |
| 202 |
.BR \%COLOR_GREEN "," |
| 203 |
.BR \%COLOR_YELLOW "," |
| 204 |
.BR \%COLOR_BLUE "," |
| 205 |
.BR \%COLOR_MAGENTA "," |
| 206 |
.BR \%COLOR_CYAN "," |
| 207 |
and |
| 208 |
.B \%COLOR_WHITE |
| 209 |
accordingly. |
| 210 |
.I curses |
| 211 |
assumes that |
| 212 |
.B \%COLOR_BLACK |
| 213 |
is the default background color for all terminals. |
| 214 |
.I \%ncurses |
| 215 |
offers an extension to override that assumption; |
| 216 |
see \fB\%assume_default_colors\fP(3NCURSES). |
| 217 |
Some terminals support additional colors that lack standard names. |
| 218 |
.PP |
| 219 |
.B \%A_COLOR |
| 220 |
is a bit mask that, |
| 221 |
when bitwise \*(``and\*(''-ed with a |
| 222 |
.IR \%chtype "," |
| 223 |
.\" XXX: and right-shifted by...? |
| 224 |
extracts its color pair identifier. |
| 225 |
.SH VARIABLES |
| 226 |
.SS COLORS |
| 227 |
is initialized by \fB\%start_color\fP to the maximum number of colors |
| 228 |
the terminal can support. |
| 229 |
.SS COLOR_PAIRS |
| 230 |
is initialized by \fB\%start_color\fP to the maximum number of color |
| 231 |
pairs the terminal can support. |
| 232 |
Often, |
| 233 |
its value is the product \fB\%COLORS\fP \(mu \fB\%COLORS\fP, |
| 234 |
but this is not always true. |
| 235 |
.bP |
| 236 |
A few terminals use the HLS color space |
| 237 |
(see \fB\%start_color\fP below), |
| 238 |
ignoring this rule; |
| 239 |
and |
| 240 |
.bP |
| 241 |
terminals supporting a large number of colors are limited to the number |
| 242 |
of color pairs that a |
| 243 |
.I "signed short" |
| 244 |
value can represent. |
| 245 |
.SH FUNCTIONS |
| 246 |
.SS start_color |
| 247 |
The \fB\%start_color\fP routine requires no arguments. |
| 248 |
It must be called if the programmer wants to use colors, and before any other |
| 249 |
color manipulation routine is called. |
| 250 |
It is good practice to call this routine right after \fB\%initscr\fP. |
| 251 |
\fB\%start_color\fP does this: |
| 252 |
.bP |
| 253 |
It initializes two global variables, \fB\%COLORS\fP and |
| 254 |
\fB\%COLOR_PAIRS\fP (respectively defining the maximum number of colors |
| 255 |
and color pairs the terminal can support). |
| 256 |
.bP |
| 257 |
It initializes the special color pair \fB\%0\fP to the default foreground |
| 258 |
and background colors. |
| 259 |
No other color pairs are initialized. |
| 260 |
.bP |
| 261 |
It restores the colors on the terminal to the values |
| 262 |
they had when the terminal was just turned on. |
| 263 |
.bP |
| 264 |
If the terminal supports the \fBinitc\fP \%(\fBinitialize_color\fP) capability, |
| 265 |
\fB\%start_color\fP |
| 266 |
initializes its internal table representing the |
| 267 |
red, green, and blue components of the color palette. |
| 268 |
.IP |
| 269 |
The components depend on whether the terminal uses |
| 270 |
CGA (aka \*(``ANSI\*('') or |
| 271 |
HLS (i.e., the \fBhls\fP \%(\fBhue_lightness_saturation\fP) capability is set). |
| 272 |
The table is initialized first for eight basic colors |
| 273 |
(black, red, green, yellow, blue, magenta, cyan, and white), |
| 274 |
using weights that depend upon the CGA/HLS choice. |
| 275 |
For \*(``ANSI\*('' colors the weights are \fB680\fP or \fB0\fP |
| 276 |
depending on whether the corresponding |
| 277 |
red, green, or blue component is used or not. |
| 278 |
That permits using \fB1000\fP to represent bold/bright colors. |
| 279 |
After the initial eight colors |
| 280 |
(if the terminal supports more than eight colors) |
| 281 |
the components are initialized using the same pattern, |
| 282 |
but with weights of \fB1000\fP. |
| 283 |
SVr4 uses a similar scheme, but uses \fB1000\fP |
| 284 |
for the components of the initial eight colors. |
| 285 |
.IP |
| 286 |
\fB\%start_color\fP does not attempt to set the terminal's color palette |
| 287 |
to match its built-in table. |
| 288 |
An application may use \fB\%init_color\fP to alter the internal table |
| 289 |
along with the terminal's color. |
| 290 |
.PP |
| 291 |
These limits apply to color values and color pairs. |
| 292 |
Values outside these limits are not valid, and may result in a runtime error: |
| 293 |
.bP |
| 294 |
\fBCOLORS\fP corresponds to the terminal database's \fB\%max_colors\fP capability, |
| 295 |
(see \fB\%terminfo\fP(5)). |
| 296 |
.bP |
| 297 |
color values are expected to be in the range \fB0\fP to \fB\%COLORS\-1\fP, |
| 298 |
inclusive (including \fB0\fP and \fB\%COLORS\-1\fP). |
| 299 |
.bP |
| 300 |
a special color value \fB\-1\fP is used in certain extended functions |
| 301 |
to denote the \fIdefault color\fP (see \fB\%use_default_colors\fP(3NCURSES)). |
| 302 |
.bP |
| 303 |
\fB\%COLOR_PAIRS\fP corresponds to |
| 304 |
the terminal database's \fB\%max_pairs\fP capability, |
| 305 |
(see \fB\%terminfo\fP(5)). |
| 306 |
.bP |
| 307 |
valid color pair values are in the range \fB1\fP to \fB\%COLOR_PAIRS\-1\fP, |
| 308 |
inclusive. |
| 309 |
.bP |
| 310 |
color pair \fB0\fP is special; it denotes \*(``no color\*(''. |
| 311 |
.IP |
| 312 |
Color pair \fB0\fP is assumed to be white on black, |
| 313 |
but is actually whatever the terminal implements before color is initialized. |
| 314 |
It cannot be modified by the application. |
| 315 |
.SS has_colors |
| 316 |
.B \%has_colors |
| 317 |
returns |
| 318 |
.B TRUE |
| 319 |
if the terminal supports colors and |
| 320 |
.B FALSE |
| 321 |
if it does not. |
| 322 |
\fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES) must be called first, |
| 323 |
but |
| 324 |
.B \%start_color |
| 325 |
need not be. |
| 326 |
An application might call |
| 327 |
.B \%has_colors |
| 328 |
to decide whether to use color |
| 329 |
or a video attribute like |
| 330 |
.B \%A_BOLD |
| 331 |
to render text. |
| 332 |
.PP |
| 333 |
Color support in |
| 334 |
.I curses |
| 335 |
requires that the terminal type description |
| 336 |
support the capabilities |
| 337 |
.B \%max_colors |
| 338 |
.RB \%( colors ), |
| 339 |
.B \%max_pairs |
| 340 |
.RB \%( pairs ), |
| 341 |
and any of |
| 342 |
.bP |
| 343 |
.B \%set_foreground |
| 344 |
.RB ( setf ) |
| 345 |
and |
| 346 |
.B \%set_background |
| 347 |
.RB ( setb ); |
| 348 |
.bP |
| 349 |
.B \%set_a_foreground |
| 350 |
.RB ( setaf ) |
| 351 |
and |
| 352 |
.B \%set_a_background |
| 353 |
.RB ( setab ); |
| 354 |
or |
| 355 |
.bP |
| 356 |
.B \%set_color_pair |
| 357 |
.RB ( scp ). |
| 358 |
.SS can_change_color |
| 359 |
The \fB\%can_change_color\fP routine requires no arguments. |
| 360 |
It returns \fBTRUE\fP if the terminal supports colors |
| 361 |
and can change their definitions; |
| 362 |
other, it returns \fBFALSE\fP. |
| 363 |
This routine facilitates writing terminal-independent programs. |
| 364 |
.SS init_pair |
| 365 |
The \fB\%init_pair\fP routine changes the definition of a color pair. |
| 366 |
It takes three arguments: |
| 367 |
the number of the color pair to be changed, the foreground |
| 368 |
color number, and the background color number. |
| 369 |
For portable applications: |
| 370 |
.bP |
| 371 |
The first argument must be a valid color pair value. |
| 372 |
If default colors are used (see \fB\%use_default_colors\fP(3NCURSES)) |
| 373 |
the upper limit is adjusted to allow for extra pairs which use |
| 374 |
a default color in foreground and/or background. |
| 375 |
.bP |
| 376 |
The second and third arguments must be valid color values. |
| 377 |
.PP |
| 378 |
If the color pair was previously initialized, |
| 379 |
the screen is refreshed and all occurrences of that color pair |
| 380 |
are changed to the new definition. |
| 381 |
.PP |
| 382 |
As an extension, |
| 383 |
\fI\%ncurses\fP allows you to set color pair \fB0\fP via the |
| 384 |
\fB\%assume_default_colors\fP(3NCURSES) routine, or to specify the use of |
| 385 |
default colors (color number \fB\-1\fP) if you first invoke the |
| 386 |
\fB\%use_default_colors\fP(3NCURSES) routine. |
| 387 |
.SS init_extended_pair |
| 388 |
Because \fB\%init_pair\fP uses signed \fBshort\fPs for its parameters, |
| 389 |
that limits color pairs and color-values |
| 390 |
to 32767 on modern hardware. |
| 391 |
The extension \fB\%init_extended_pair\fP uses \fBint\fPs |
| 392 |
for the color pair and color-value, |
| 393 |
allowing a larger number of colors to be supported. |
| 394 |
.SS init_color |
| 395 |
The \fB\%init_color\fP routine changes the definition of a color. |
| 396 |
It takes four arguments: |
| 397 |
the number of the color to be changed followed by three RGB values |
| 398 |
(for the amounts of red, green, and blue components). |
| 399 |
.bP |
| 400 |
The first argument must be a valid color value; |
| 401 |
default colors are not allowed here. |
| 402 |
(See the section \fB\%Colors\fP for the default color index.) |
| 403 |
.bP |
| 404 |
Each of the last three arguments |
| 405 |
must be a value in the range \fB0\fP through \fB1000\fP. |
| 406 |
.PP |
| 407 |
When \fB\%init_color\fP is used, all |
| 408 |
occurrences of that color on the screen immediately change to the new |
| 409 |
definition. |
| 410 |
.SS init_extended_color |
| 411 |
Because \fB\%init_color\fP uses signed \fBshort\fPs for its parameters, |
| 412 |
that limits color-values and their red, green, and blue components |
| 413 |
to 32767 on modern hardware. |
| 414 |
The extension \fB\%init_extended_color\fP uses \fBint\fPs |
| 415 |
for the color value and |
| 416 |
for setting the red, green, and blue components, |
| 417 |
allowing a larger number of colors to be supported. |
| 418 |
.SS color_content |
| 419 |
The \fB\%color_content\fP routine gives programmers a way to find the intensity |
| 420 |
of the red, green, and blue (RGB) components in a color. |
| 421 |
It requires four arguments: the color number, and three addresses |
| 422 |
of \fBshort\fRs for storing |
| 423 |
the information about the amounts of red, green, and blue components in the |
| 424 |
given color. |
| 425 |
.bP |
| 426 |
The first argument must be a valid color value, i.e., |
| 427 |
\fB0\fP through \fB\%COLORS\-1\fP, inclusive. |
| 428 |
.bP |
| 429 |
The values that are stored at the addresses pointed to by the |
| 430 |
last three arguments are in the range |
| 431 |
\fB0\fP (no component) through \fB1000\fP |
| 432 |
(maximum amount of component), inclusive. |
| 433 |
.SS extended_color_content |
| 434 |
Because \fB\%color_content\fP uses signed \fBshort\fPs for its parameters, |
| 435 |
that limits color-values and their red, green, and blue components |
| 436 |
to 32767 on modern hardware. |
| 437 |
The extension \fB\%extended_color_content\fP uses \fBint\fPs |
| 438 |
for the color value and |
| 439 |
for returning the red, green, and blue components, |
| 440 |
allowing a larger number of colors to be supported. |
| 441 |
.SS pair_content |
| 442 |
The \fB\%pair_content\fP routine allows programmers to find out what colors a |
| 443 |
given color pair consists of. |
| 444 |
It requires three arguments: the color pair |
| 445 |
number, and two addresses of \fBshort\fRs for storing the foreground and the |
| 446 |
background color numbers. |
| 447 |
.bP |
| 448 |
The first argument must be a valid color value, |
| 449 |
i.e., in the range \fB1\fP through \fB\%COLOR_PAIRS\-1\fP, inclusive. |
| 450 |
.bP |
| 451 |
The values that are stored at the addresses pointed |
| 452 |
to by the second and third arguments are in the |
| 453 |
range \fB0\fP through \fB\%COLORS\fP, inclusive. |
| 454 |
.SS extended_pair_content |
| 455 |
Because \fB\%pair_content\fP uses signed \fBshort\fPs for its parameters, |
| 456 |
that limits color pair and color-values to 32767 on modern hardware. |
| 457 |
The extension \fB\%extended_pair_content\fP uses \fBint\fPs |
| 458 |
for the color pair and |
| 459 |
for returning the foreground and background colors, |
| 460 |
allowing a larger number of colors to be supported. |
| 461 |
.SS reset_color_pairs |
| 462 |
The extension \fB\%reset_color_pairs\fP tells \fI\%ncurses\fP to discard |
| 463 |
all of the color pair information which was set with \fB\%init_pair\fP. |
| 464 |
It also touches the current- and standard-screens, allowing an application to |
| 465 |
switch color palettes rapidly. |
| 466 |
.SS COLOR_PAIR |
| 467 |
\fB\%COLOR_PAIR(\fIn\fB)\fR converts a color pair number to an |
| 468 |
attribute. |
| 469 |
Attributes can hold color pairs in the range 0 to 255. |
| 470 |
If you need a color pair larger than that, |
| 471 |
you must use functions such as \fB\%attr_set\fP |
| 472 |
(which pass the color pair as a separate parameter) |
| 473 |
rather than the legacy functions such as \fB\%attrset\fP. |
| 474 |
.SS PAIR_NUMBER |
| 475 |
\fB\%PAIR_NUMBER(\fIattr\fR) extracts the color information from its |
| 476 |
\fIattr\fP parameter and returns it as a color pair number; |
| 477 |
it is the inverse operation of \fB\%COLOR_PAIR\fP. |
| 478 |
.SH RETURN VALUE |
| 479 |
.B \%can_change_color |
| 480 |
and |
| 481 |
.B \%has_colors |
| 482 |
return |
| 483 |
.B TRUE |
| 484 |
or |
| 485 |
.BR FALSE "." |
| 486 |
The other functions return |
| 487 |
.B OK |
| 488 |
on success and |
| 489 |
.B ERR |
| 490 |
on failure. |
| 491 |
.PP |
| 492 |
In |
| 493 |
.IR \%ncurses "," |
| 494 |
functions returning an |
| 495 |
.I int |
| 496 |
recognize several error conditions. |
| 497 |
.bP |
| 498 |
All return |
| 499 |
.B ERR |
| 500 |
if the screen has not been initialized; |
| 501 |
see \fBinitscr\fP(3NCURSES) or \fBnewterm\fP(3NCURSES). |
| 502 |
.bP |
| 503 |
All except |
| 504 |
.B \%start_color |
| 505 |
return |
| 506 |
.B ERR |
| 507 |
if |
| 508 |
.B \%start_color |
| 509 |
has not been called, |
| 510 |
or itself returned |
| 511 |
.BR ERR "." |
| 512 |
.bP |
| 513 |
.B \%start_color |
| 514 |
returns |
| 515 |
.B ERR |
| 516 |
if it cannot allocate memory for its color pair table. |
| 517 |
.bP |
| 518 |
.B \%init_color |
| 519 |
returns |
| 520 |
.B ERR |
| 521 |
if the terminal type does not support assignable color values; |
| 522 |
that is, |
| 523 |
if the |
| 524 |
.B \%initialize_color |
| 525 |
.RB ( initc ) |
| 526 |
capability is absent from its description. |
| 527 |
.bP |
| 528 |
.B \%init_color |
| 529 |
returns |
| 530 |
.B ERR |
| 531 |
if any of its |
| 532 |
.IR r "," |
| 533 |
.IR g "," |
| 534 |
.I b |
| 535 |
arguments is outside the range 0-1000 inclusive. |
| 536 |
.bP |
| 537 |
.BR \%init_pair "," |
| 538 |
.BR \%init_color "," |
| 539 |
.BR \%init_extended_pair "," |
| 540 |
.BR \%init_extended_color "," |
| 541 |
.BR \%color_content "," |
| 542 |
.BR \%pair_content "," |
| 543 |
.BR \%extended_color_content "," |
| 544 |
and |
| 545 |
.B \%extended_pair_content |
| 546 |
return |
| 547 |
.B ERR |
| 548 |
on attempts to use |
| 549 |
.RS |
| 550 |
.bP |
| 551 |
color identifiers outside the range |
| 552 |
.RB \%0- COLORS \-1 |
| 553 |
inclusive, |
| 554 |
the default colors extension notwithstanding, |
| 555 |
or |
| 556 |
.bP |
| 557 |
color pair identifiers outside the range |
| 558 |
.RB \%0- COLOR_PAIRS \-1 |
| 559 |
inclusive. |
| 560 |
.RE |
| 561 |
.SH NOTES |
| 562 |
In |
| 563 |
.IR \%ncurses "," |
| 564 |
.B \%init_pair |
| 565 |
accepts negative foreground and background color arguments |
| 566 |
to support its \fB\%use_default_colors\fP(3NCURSES) extension, |
| 567 |
but only after the latter function has been called. |
| 568 |
.PP |
| 569 |
The assumption that |
| 570 |
.B \%COLOR_BLACK |
| 571 |
is the terminal's default background color can be overridden using |
| 572 |
.IR \%ncurses 's |
| 573 |
\fB\%assume_default_colors\fP(3NCURSES) extension. |
| 574 |
.PP |
| 575 |
In |
| 576 |
.IR \%ncurses "," |
| 577 |
each pointer passed to |
| 578 |
.B \%color_content |
| 579 |
and |
| 580 |
.B \%pair_content |
| 581 |
can be null, |
| 582 |
in which case the library ignores it, |
| 583 |
permitting the application to disregard unnecessary information. |
| 584 |
.PP |
| 585 |
In |
| 586 |
.IR \%ncurses "," |
| 587 |
each screen has a |
| 588 |
color activation flag, |
| 589 |
color palette, |
| 590 |
color pair table, |
| 591 |
and associated |
| 592 |
.B \%COLORS |
| 593 |
and |
| 594 |
.B \%COLOR_PAIRS |
| 595 |
values; |
| 596 |
.B \%start_color |
| 597 |
affects only the current screen. |
| 598 |
The SVr4 and X/Open Curses interface was not really designed |
| 599 |
with this in mind; |
| 600 |
historical implementations may use a single shared color palette. |
| 601 |
.PP |
| 602 |
Setting an implicit background color via a color pair affects only |
| 603 |
character cells that a character write operation explicitly touches. |
| 604 |
To change the background color used |
| 605 |
when parts of a window are blanked by erasing or scrolling operations, |
| 606 |
see \fB\%bkgd\fP(3NCURSES). |
| 607 |
.PP |
| 608 |
Several caveats apply to IBM PC-compatible machines |
| 609 |
of the 80486 era and earlier |
| 610 |
with CGA/EGA/VGA video. |
| 611 |
.bP |
| 612 |
.B \%COLOR_YELLOW |
| 613 |
was frequently converted, |
| 614 |
in the analog domain, |
| 615 |
to a shade of brown if the intensity bit was not set. |
| 616 |
.\" https://nerdlypleasures.blogspot.com/2023/03/the-saga-of-color-brown-in-early-years.html |
| 617 |
To get yellow on such devices, |
| 618 |
one would combine |
| 619 |
.B \%COLOR_YELLOW |
| 620 |
with the |
| 621 |
.B \%A_BOLD |
| 622 |
attribute. |
| 623 |
.bP |
| 624 |
The |
| 625 |
.B \%A_BLINK |
| 626 |
attribute should in theory make the background bright. |
| 627 |
This often fails to work, |
| 628 |
and even VGA controllers for which it mostly works, |
| 629 |
such as those from Paradise and compatibles, |
| 630 |
do the wrong thing |
| 631 |
when you try to set a bright \*(``yellow\*('' background \(em |
| 632 |
you get a blinking yellow foreground instead. |
| 633 |
.bP |
| 634 |
Color RGB values are not configurable on these devices |
| 635 |
(in text mode). |
| 636 |
.SH EXTENSIONS |
| 637 |
The functions marked as extensions originated in |
| 638 |
.IR \%ncurses "," |
| 639 |
and are not found in SVr4 |
| 640 |
.IR curses , |
| 641 |
4.4BSD |
| 642 |
.IR curses , |
| 643 |
or any other previous |
| 644 |
.I curses |
| 645 |
implementation. |
| 646 |
.SH PORTABILITY |
| 647 |
Applications employing |
| 648 |
.I \%ncurses |
| 649 |
extensions should condition their use on the visibility of the |
| 650 |
.B \%NCURSES_VERSION |
| 651 |
preprocessor macro. |
| 652 |
.PP |
| 653 |
X/Open Curses Issue\ 4 describes these functions. |
| 654 |
It specifies no error conditions for them. |
| 655 |
.PP |
| 656 |
.I \%ncurses |
| 657 |
satisfies X/Open Curses's minimum maximums for |
| 658 |
.I \%COLORS |
| 659 |
and |
| 660 |
.IR \%COLOR_PAIRS "." |
| 661 |
.PP |
| 662 |
X/Open Curses does not specify a limit for the number of colors and |
| 663 |
color pairs which a terminal can support. |
| 664 |
However, |
| 665 |
in its use of |
| 666 |
.I short |
| 667 |
for the parameters, |
| 668 |
it carries over SVr4's implementation detail for the compiled |
| 669 |
.I \%term\%info |
| 670 |
database, |
| 671 |
which uses signed 16-bit numbers. |
| 672 |
.I \%ncurses |
| 673 |
provides extended versions of the functions using |
| 674 |
.I short |
| 675 |
parameters, |
| 676 |
allowing applications to use larger color and pair identifiers. |
| 677 |
.PP |
| 678 |
SVr4 |
| 679 |
.I curses |
| 680 |
returns |
| 681 |
.I ERR |
| 682 |
from |
| 683 |
.I \%pair_content |
| 684 |
if its |
| 685 |
.I pair |
| 686 |
argument |
| 687 |
was not initialized using |
| 688 |
.IR \%init_pairs , |
| 689 |
and from |
| 690 |
.I \%color_content |
| 691 |
if the terminal does not support changing colors. |
| 692 |
.I \%ncurses |
| 693 |
does neither. |
| 694 |
.SH HISTORY |
| 695 |
SVr3.2 (1987) introduced color support to |
| 696 |
.I curses |
| 697 |
with all of the symbols |
| 698 |
in the synopsis above except those marked as extensions. |
| 699 |
It reserved color pair 0 as the terminal's initial, |
| 700 |
\*(``uncolored\*('' state, |
| 701 |
.\" "we assume that color 0 is always a default background.", SVr3.2 |
| 702 |
.\" usr/src/lib/libcurses/screen/start_col.c |
| 703 |
and limited the number of possible color pairs to 64, |
| 704 |
because the color pair datum was encoded in six bits of a |
| 705 |
.IR \%chtype "." |
| 706 |
.PP |
| 707 |
SVr4 made only internal changes, |
| 708 |
such as moving the storage of color state |
| 709 |
from the |
| 710 |
.I SCREEN |
| 711 |
structure |
| 712 |
(pointed to by |
| 713 |
.IR SP ) |
| 714 |
to the |
| 715 |
.I \%TERMINAL |
| 716 |
structure |
| 717 |
(pointed to by |
| 718 |
.IR \%cur_term ")." |
| 719 |
.PP |
| 720 |
Other |
| 721 |
.I curses |
| 722 |
implementations impose different limits on the number of colors and |
| 723 |
color pairs. |
| 724 |
.bP |
| 725 |
.I \%PCCurses |
| 726 |
(1987-1990) provided for only 8 colors |
| 727 |
(and therefore required at most 8\(mu8 = 64 color pairs). |
| 728 |
.bP |
| 729 |
.I \%PDCurses |
| 730 |
(1992-present) inherited the 8-color limitation from |
| 731 |
.IR \%PCCurses , |
| 732 |
but changed this to 256 in version 2.5 (2001), |
| 733 |
and widened its |
| 734 |
.I \%chtype |
| 735 |
from 16 to 32 bits. |
| 736 |
.bP |
| 737 |
X/Open Curses (1992-present) |
| 738 |
specified a new structure type, |
| 739 |
.IR \%cchar_t "," |
| 740 |
to store the character code, |
| 741 |
attribute flags, |
| 742 |
and color pair identifier, |
| 743 |
allowing an increased range of color pairs. |
| 744 |
It specifies a |
| 745 |
.I short |
| 746 |
as storing identifiers for colors and color pairs, |
| 747 |
limiting portable values to 15 bits; |
| 748 |
negative values are invalid in System\ V. |
| 749 |
.bP |
| 750 |
.I \%ncurses |
| 751 |
(1992-present), |
| 752 |
in its non-wide-character configuration, |
| 753 |
uses 8 bits of |
| 754 |
.I \%chtype |
| 755 |
for the color pair identifier. |
| 756 |
.IP |
| 757 |
Version 5.3 (2002) offered a wide-character interface, |
| 758 |
but encoded the color pair identifier with attributes |
| 759 |
in the character type. |
| 760 |
.IP |
| 761 |
Since version 6 (2015), |
| 762 |
.I \%ncurses |
| 763 |
uses a separate |
| 764 |
.I int |
| 765 |
for the color pair identifier in a |
| 766 |
.IR \%cchar_t "," |
| 767 |
introducing extension functions to manage the wider type. |
| 768 |
When a color pair value fits in 8 bits, |
| 769 |
.I \%ncurses |
| 770 |
permits color pair data to be manipulated |
| 771 |
via the functions taking |
| 772 |
.I \%chtype |
| 773 |
arguments, |
| 774 |
even when a |
| 775 |
.I curses |
| 776 |
window uses wide-character cells. |
| 777 |
.bP |
| 778 |
NetBSD |
| 779 |
.I curses |
| 780 |
used 6 bits for the color pair identifier from 2000 |
| 781 |
(when it first added color support) |
| 782 |
until 2004. |
| 783 |
At that point, |
| 784 |
NetBSD widened the color pair identifier to use 9 bits. |
| 785 |
As of 2025, |
| 786 |
that size is unchanged. |
| 787 |
.\" http://cvsweb.netbsd.org/bsdweb.cgi/src/lib/libcurses/curses.h?rev=1.133 |
| 788 |
.\" indicates a mask of 0x03fe0000. |
| 789 |
Like |
| 790 |
.I \%ncurses |
| 791 |
before version 6, |
| 792 |
the NetBSD color pair datum is stored in |
| 793 |
the attributes field of |
| 794 |
.IR \%cchar_t "," |
| 795 |
limiting the number of color pairs. |
| 796 |
.SH SEE ALSO |
| 797 |
\fB\%ncurses\fP(3NCURSES), |
| 798 |
\fB\%attr\fP(3NCURSES), |
| 799 |
\fB\%initscr\fP(3NCURSES), |
| 800 |
\fB\%curses_variables\fP(3NCURSES), |
| 801 |
\fB\%default_colors\fP(3NCURSES) |