man/curs_color.3x

   1 .\"***************************************************************************
   2 .\" Copyright 2018-2019,2020 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.63 2020/10/24 09:35:23 tom Exp $
  31 .TH curs_color 3X ""
  32 .ie \n(.g .ds `` \(lq
  33 .el       .ds `` ``
  34 .ie \n(.g .ds '' \(rq
  35 .el       .ds '' ''
  36 .de bP
  37 .ie n  .IP \(bu 4
  38 .el    .IP \(bu 2
  39 ..
  40 .ds n 5
  41 .na
  42 .hy 0
  43 .SH NAME
  44 \fBstart_color\fR,
  45 \fBhas_colors\fR,
  46 \fBcan_change_color\fR,
  47 \fBinit_pair\fR,
  48 \fBinit_color\fR,
  49 \fBinit_extended_pair\fR,
  50 \fBinit_extended_color\fR,
  51 \fBcolor_content\fR,
  52 \fBpair_content\fR,
  53 \fBextended_color_content\fR,
  54 \fBextended_pair_content\fR,
  55 \fBreset_color_pairs\fR,
  56 \fBCOLOR_PAIR\fR,
  57 \fBPAIR_NUMBER\fR \- \fBcurses\fR color manipulation routines
  58 .ad
  59 .hy
  60 .SH SYNOPSIS
  61 \fB#include <curses.h>\fR
  62 .sp
  63 \fBint start_color(void);\fR
  64 .sp
  65 \fBbool has_colors(void);\fR
  66 .br
  67 \fBbool can_change_color(void);\fR
  68 .sp
  69 \fBint init_pair(short \fP\fIpair\fP\fB, short \fP\fIf\fP\fB, short \fP\fIb\fP\fB);\fR
  70 .br
  71 \fBint init_color(short \fP\fIcolor\fP\fB, short \fP\fIr\fP\fB, short \fP\fIg\fP\fB, short \fP\fIb\fP\fB);\fR
  72 .br
  73 /* extensions */
  74 .br
  75 \fBint init_extended_pair(int \fP\fIpair\fP\fB, int \fP\fIf\fP\fB, int \fP\fIb\fP\fB);\fR
  76 .br
  77 \fBint init_extended_color(int \fP\fIcolor\fP\fB, int \fP\fIr\fP\fB, int \fP\fIg\fP\fB, int \fP\fIb\fP\fB);\fR
  78 .sp
  79 \fBint color_content(short \fP\fIcolor\fP\fB, short *\fP\fIr\fP\fB, short *\fP\fIg\fP\fB, short *\fP\fIb\fP\fB);\fR
  80 .br
  81 \fBint pair_content(short \fP\fIpair\fP\fB, short *\fP\fIf\fP\fB, short *\fP\fIb\fP\fB);\fR
  82 .br
  83 /* extensions */
  84 .br
  85 \fBint extended_color_content(int \fP\fIcolor\fP\fB, int *\fP\fIr\fP\fB, int *\fP\fIg\fP\fB, int *\fP\fIb\fP\fB);\fR
  86 .br
  87 \fBint extended_pair_content(int \fP\fIpair\fP\fB, int *\fP\fIf\fP\fB, int *\fP\fIb\fP\fB);\fR
  88 .sp
  89 /* extensions */
  90 .br
  91 \fBvoid reset_color_pairs(void);\fR
  92 .sp
  93 \fBint COLOR_PAIR(int \fP\fIn\fP\fB);\fR
  94 .br
  95 \fBPAIR_NUMBER(\fR\fIattrs\fR\fB);\fP
  96 .br
  97 .SH DESCRIPTION
  98 .SS Overview
  99 \fBcurses\fR supports color attributes on terminals with that capability.
 100 To use these routines \fBstart_color\fR must be called, usually right after
 101 \fBinitscr\fR.
 102 Colors are always used in pairs (referred to as color-pairs).
 103 A color-pair consists of a foreground color (for characters) and a background
 104 color (for the blank field on which the characters are displayed).
 105 A programmer initializes a color-pair with the routine \fBinit_pair\fR.
 106 After it has been initialized, \fBCOLOR_PAIR\fR(\fIn\fR)
 107 can be used to convert the pair to a video attribute.
 108 .PP
 109 If a terminal is capable of redefining colors, the programmer can use the
 110 routine \fBinit_color\fR to change the definition of a color.
 111 The routines \fBhas_colors\fR and \fBcan_change_color\fR
 112 return \fBTRUE\fR or \fBFALSE\fR,
 113 depending on whether the terminal has color capabilities and whether the
 114 programmer can change the colors.
 115 The routine \fBcolor_content\fR allows a
 116 programmer to extract the amounts of red, green, and blue components in an
 117 initialized color.
 118 The routine \fBpair_content\fR allows a programmer to find
 119 out how a given color-pair is currently defined.
 120 .SS Color Rendering
 121 The \fBcurses\fP library combines these inputs to produce the
 122 actual foreground and background colors shown on the screen:
 123 .bP
 124 per-character video attributes (e.g., via \fBwaddch\fP),
 125 .bP
 126 the window attribute (e.g., by \fBwattrset\fP), and
 127 .bP
 128 the background character (e.g., \fBwbkgdset\fP).
 129 .PP
 130 Per-character and window attributes are usually set by a parameter containing
 131 video attributes including a color pair value.
 132 Some functions such as \fBwattr_set\fP use a separate parameter which
 133 is the color pair number.
 134 .PP
 135 The background character is a special case: it includes a character value,
 136 just as if it were passed to \fBwaddch\fP.
 137 .PP
 138 The \fBcurses\fP library does the actual work of combining these color
 139 pairs in an internal function called from \fBwaddch\fP:
 140 .bP
 141 If the parameter passed to \fBwaddch\fP is \fIblank\fP,
 142 and it uses the special color pair 0,
 143 .RS
 144 .bP
 145 \fBcurses\fP next checks the window attribute.
 146 .bP
 147 If the window attribute does not use color pair 0,
 148 \fBcurses\fP uses the color pair from the window attribute.
 149 .bP
 150 Otherwise, \fBcurses\fP uses the background character.
 151 .RE
 152 .bP
 153 If the parameter passed to \fBwaddch\fP is \fInot blank\fP,
 154 or it does not use the special color pair 0,
 155 \fBcurses\fP prefers the color pair from the parameter,
 156 if it is nonzero.
 157 Otherwise, it tries the window attribute next, and finally the
 158 background character.
 159 .PP
 160 Some \fBcurses\fP functions such as \fBwprintw\fP call \fBwaddch\fP.
 161 Those do not combine its parameter with a color pair.
 162 Consequently those calls use only the window attribute or
 163 the background character.
 164 .SH CONSTANTS
 165 .PP
 166 In \fB<curses.h>\fR the following macros are defined.
 167 These are the standard colors (ISO-6429).
 168 \fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
 169 background color for all terminals.
 170 .PP
 171 .nf
 172       \fBCOLOR_BLACK\fR
 173       \fBCOLOR_RED\fR
 174       \fBCOLOR_GREEN\fR
 175       \fBCOLOR_YELLOW\fR
 176       \fBCOLOR_BLUE\fR
 177       \fBCOLOR_MAGENTA\fR
 178       \fBCOLOR_CYAN\fR
 179       \fBCOLOR_WHITE\fR
 180 .fi
 181 .PP
 182 Some terminals support more than the eight (8) \*(``ANSI\*('' colors.
 183 There are no standard names for those additional colors.
 184 .SH VARIABLES
 185 .SS COLORS
 186 is initialized by \fBstart_color\fP to the maximum number of colors
 187 the terminal can support.
 188 .SS COLOR_PAIRS
 189 is initialized by \fBstart_color\fP to the maximum number of color pairs
 190 the terminal can support.
 191 .SH FUNCTIONS
 192 .SS start_color
 193 The \fBstart_color\fR routine requires no arguments.
 194 It must be called if the programmer wants to use colors, and before any other
 195 color manipulation routine is called.
 196 It is good practice to call this routine right after \fBinitscr\fR.
 197 \fBstart_color\fR does this:
 198 .bP
 199 It initializes two global variables, \fBCOLORS\fR and
 200 \fBCOLOR_PAIRS\fR (respectively defining the maximum number of colors
 201 and color-pairs the terminal can support).
 202 .bP
 203 It initializes the special color pair \fB0\fP to the default foreground
 204 and background colors.
 205 No other color pairs are initialized.
 206 .bP
 207 It restores the colors on the terminal to the values
 208 they had when the terminal was just turned on.
 209 .bP
 210 If the terminal supports the \fBinitc\fP (\fBinitialize_color\fP) capability,
 211 \fBstart_color\fP
 212 initializes its internal table representing the
 213 red, green, and blue components of the color palette.
 214 .IP
 215 The components depend on whether the terminal uses
 216 CGA (aka \*(``ANSI\*('') or
 217 HLS (i.e., the \fBhls\fP (\fBhue_lightness_saturation\fP) capability is set).
 218 The table is initialized first for eight basic colors
 219 (black, red, green, yellow, blue, magenta, cyan, and white),
 220 using weights that depend upon the CGA/HLS choice.
 221 For \*(``ANSI\*('' colors the weights are \fB680\fP or \fB0\fP
 222 depending on whether the corresponding
 223 red, green, or blue component is used or not.
 224 That permits using \fB1000\fP to represent bold/bright colors.
 225 After the initial eight colors
 226 (if the terminal supports more than eight colors)
 227 the components are initialized using the same pattern,
 228 but with weights of \fB1000\fP.
 229 SVr4 uses a similar scheme, but uses \fB1000\fP
 230 for the components of the initial eight colors.
 231 .IP
 232 \fBstart_color\fP does not attempt to set the terminal's color palette
 233 to match its built-in table.
 234 An application may use \fBinit_color\fP to alter the internal table
 235 along with the terminal's color.
 236 .PP
 237 These limits apply to color values and color pairs.
 238 Values outside these limits are not legal, and may result in a runtime error:
 239 .bP
 240 \fBCOLORS\fP corresponds to the terminal database's \fBmax_colors\fR capability,
 241 (see \fBterminfo\fR(\*n)).
 242 .bP
 243 color values are expected to be in the range \fB0\fP to \fBCOLORS\-1\fP,
 244 inclusive (including \fB0\fP and \fBCOLORS\-1\fP).
 245 .bP
 246 a special color value \fB\-1\fP is used in certain extended functions
 247 to denote the \fIdefault color\fP (see \fBuse_default_colors\fP(3X)).
 248 .bP
 249 \fBCOLOR_PAIRS\fP corresponds to
 250 the terminal database's \fBmax_pairs\fP capability,
 251 (see \fBterminfo\fR(\*n)).
 252 .bP
 253 legal color pair values are in the range \fB1\fP to \fBCOLOR_PAIRS\-1\fP,
 254 inclusive.
 255 .bP
 256 color pair \fB0\fP is special; it denotes \*(``no color\*(''.
 257 .IP
 258 Color pair \fB0\fP is assumed to be white on black,
 259 but is actually whatever the terminal implements before color is initialized.
 260 It cannot be modified by the application.
 261 .SS has_colors
 262 .PP
 263 The \fBhas_colors\fR routine requires no arguments.
 264 It returns \fBTRUE\fR if
 265 the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR.
 266 This routine facilitates writing terminal-independent programs.
 267 For example, a programmer can use it to decide
 268 whether to use color or some other video attribute.
 269 .SS can_change_color
 270 .PP
 271 The \fBcan_change_color\fR routine requires no arguments.
 272 It returns \fBTRUE\fR if the terminal supports colors
 273 and can change their definitions;
 274 other, it returns \fBFALSE\fR.
 275 This routine facilitates writing terminal-independent programs.
 276 .SS init_pair
 277 .PP
 278 The \fBinit_pair\fR routine changes the definition of a color-pair.
 279 It takes three arguments:
 280 the number of the color-pair to be changed, the foreground
 281 color number, and the background color number.
 282 For portable applications:
 283 .bP
 284 The first argument must be a legal color pair value.
 285 If default colors are used (see \fBuse_default_colors\fP(3X))
 286 the upper limit is adjusted to allow for extra pairs which use
 287 a default color in foreground and/or background.
 288 .bP
 289 The second and third arguments must be legal color values.
 290 .PP
 291 If the color-pair was previously initialized,
 292 the screen is refreshed and all occurrences of that color-pair
 293 are changed to the new definition.
 294 .PP
 295 As an extension, ncurses allows you to set color pair \fB0\fP via
 296 the \fBassume_default_colors\fR(3X) routine, or to specify the use of
 297 default colors (color number \fB\-1\fR) if you first invoke the
 298 \fBuse_default_colors\fR(3X) routine.
 299 .SS init_extended_pair
 300 .PP
 301 Because \fBinit_pair\fP uses signed \fBshort\fPs for its parameters,
 302 that limits color-pairs and color-values
 303 to 32767 on modern hardware.
 304 The extension \fBinit_extended_pair\fP uses \fBint\fPs
 305 for the color-pair and color-value,
 306 allowing a larger number of colors to be supported.
 307 .SS init_color
 308 .PP
 309 The \fBinit_color\fR routine changes the definition of a color.
 310 It takes four arguments:
 311 the number of the color to be changed followed by three RGB values
 312 (for the amounts of red, green, and blue components).
 313 .bP
 314 The first argument must be a legal color value;
 315 default colors are not allowed here.
 316 (See the section \fBColors\fR for the default color index.)
 317 .bP
 318 Each of the last three arguments
 319 must be a value in the range \fB0\fP through \fB1000\fP.
 320 .PP
 321 When \fBinit_color\fR is used, all
 322 occurrences of that color on the screen immediately change to the new
 323 definition.
 324 .SS init_extended_color
 325 .PP
 326 Because \fBinit_color\fP uses signed \fBshort\fPs for its parameters,
 327 that limits color-values and their red, green, and blue components
 328 to 32767 on modern hardware.
 329 The extension \fBinit_extended_color\fP uses \fBint\fPs
 330 for the color value and
 331 for setting the red, green, and blue components,
 332 allowing a larger number of colors to be supported.
 333 .SS color_content
 334 .PP
 335 The \fBcolor_content\fR routine gives programmers a way to find the intensity
 336 of the red, green, and blue (RGB) components in a color.
 337 It requires four arguments: the color number, and three addresses
 338 of \fBshort\fRs for storing
 339 the information about the amounts of red, green, and blue components in the
 340 given color.
 341 .bP
 342 The first argument must be a legal color value, i.e.,
 343 \fB0\fP through \fBCOLORS\-1\fP, inclusive.
 344 .bP
 345 The values that are stored at the addresses pointed to by the
 346 last three arguments are in the range
 347 \fB0\fP (no component) through \fB1000\fP
 348 (maximum amount of component), inclusive.
 349 .SS extended_color_content
 350 .PP
 351 Because \fBcolor_content\fP uses signed \fBshort\fPs for its parameters,
 352 that limits color-values and their red, green, and blue components
 353 to 32767 on modern hardware.
 354 The extension \fBextended_color_content\fP uses \fBint\fPs
 355 for the color value and
 356 for returning the red, green, and blue components,
 357 allowing a larger number of colors to be supported.
 358 .SS pair_content
 359 .PP
 360 The \fBpair_content\fR routine allows programmers to find out what colors a
 361 given color-pair consists of.
 362 It requires three arguments: the color-pair
 363 number, and two addresses of \fBshort\fRs for storing the foreground and the
 364 background color numbers.
 365 .bP
 366 The first argument must be a legal color value,
 367 i.e., in the range \fB1\fP through \fBCOLOR_PAIRS\-1\fR, inclusive.
 368 .bP
 369 The values that are stored at the addresses pointed
 370 to by the second and third arguments are in the
 371 range \fB0\fP through \fBCOLORS\fR, inclusive.
 372 .SS extended_pair_content
 373 .PP
 374 Because \fBpair_content\fP uses signed \fBshort\fPs for its parameters,
 375 that limits color-pair and color-values to 32767 on modern hardware.
 376 The extension \fBextended_pair_content\fP uses \fBint\fPs
 377 for the color pair and
 378 for returning the foreground and background colors,
 379 allowing a larger number of colors to be supported.
 380 .SS reset_color_pairs
 381 .PP
 382 The extension \fBreset_color_pairs\fP tells ncurses to discard all
 383 of the color-pair information which was set with \fBinit_pair\fP.
 384 It also touches the current- and standard-screens, allowing an application to
 385 switch color palettes rapidly.
 386 .SS PAIR_NUMBER
 387 .PP
 388 \fBPAIR_NUMBER(\fR\fIattrs\fR) extracts the color
 389 value from its \fIattrs\fP parameter and returns it as a color pair number.
 390 .SS COLOR_PAIR
 391 Its inverse \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR converts a color pair number
 392 to an attribute.
 393 Attributes can hold color pairs in the range 0 to 255.
 394 If you need a color pair larger than that, you must use functions
 395 such as \fBattr_set\fP (which pass the color pair as a separate parameter)
 396 rather than the legacy functions such as \fBattrset\fP.
 397 .SH RETURN VALUE
 398 The routines \fBcan_change_color\fR and \fBhas_colors\fR return \fBTRUE\fR
 399 or \fBFALSE\fR.
 400 .PP
 401 All other routines return the integer \fBERR\fR upon failure and an \fBOK\fR
 402 (SVr4 specifies only \*(``an integer value
 403 other than \fBERR\fR\*('') upon successful completion.
 404 .PP
 405 X/Open defines no error conditions.
 406 SVr4 does document some error conditions which apply in general:
 407 .bP
 408 This implementation will return \fBERR\fR on attempts to
 409 use color values outside the range \fB0\fP to \fBCOLORS\fP\-1
 410 (except for the default colors extension),
 411 or use color pairs outside the range \fB0\fP to \fBCOLOR_PAIRS\-1\fP.
 412 .IP
 413 Color values used in \fBinit_color\fP must be
 414 in the range \fB0\fP to \fB1000\fP.
 415 .IP
 416 An error is returned from all functions
 417 if the terminal has not been initialized.
 418 .IP
 419 An error is returned from secondary functions such as \fBinit_pair\fP
 420 if \fBstart_color\fP was not called.
 421 .bP
 422 SVr4 does much the same, except that
 423 it returns \fBERR\fP from \fBpair_content\fP if the pair was not initialized
 424 using \fBinit_pairs\fP
 425 and
 426 it returns \fBERR\fP from \fBcolor_content\fP
 427 if the terminal does not support changing colors.
 428 .IP
 429 This implementation does not return \fBERR\fP for either case.
 430 .PP
 431 Specific functions make additional checks:
 432 .RS 3
 433 .TP 5
 434 \fBinit_color\fP
 435 returns an error if the terminal does not support
 436 this feature, e.g., if the \fBinitialize_color\fP capability is absent
 437 from the terminal description.
 438 .TP 5
 439 \fBstart_color\fP
 440 returns an error if the color table cannot be allocated.
 441 .RE
 442 .SH NOTES
 443 In the \fBncurses\fR implementation, there is a separate color activation flag,
 444 color palette, color pairs table,
 445 and associated \fBCOLORS\fP and \fBCOLOR_PAIRS\fP counts
 446 for each screen; the \fBstart_color\fR function only affects the current
 447 screen.
 448 The SVr4/XSI interface is not really designed with this in mind, and
 449 historical implementations may use a single shared color palette.
 450 .PP
 451 Setting an implicit background color via a color pair affects only
 452 character cells that a character write operation explicitly touches.
 453 To change
 454 the background color used when parts of a window are blanked by erasing or
 455 scrolling operations, see \fBcurs_bkgd\fR(3X).
 456 .PP
 457 Several caveats apply on older x86 machines
 458 (e.g., i386, i486) with VGA-compatible graphics:
 459 .bP
 460 COLOR_YELLOW is actually brown.
 461 To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fR attribute.
 462 .bP
 463 The A_BLINK attribute should in theory cause the background to go bright.
 464 This often fails to work, and even some cards for which it mostly works
 465 (such as the
 466 Paradise and compatibles) do the wrong thing when you try to set a bright
 467 \*(``yellow\*('' background (you get a blinking yellow foreground instead).
 468 .bP
 469 Color RGB values are not settable.
 470 .SH PORTABILITY
 471 This implementation satisfies XSI Curses's minimum maximums
 472 for \fBCOLORS\fR and \fBCOLOR_PAIRS\fR.
 473 .PP
 474 The \fBinit_pair\fP routine accepts negative values of foreground
 475 and background color to support the \fBuse_default_colors\fR(3X) extension,
 476 but only if that routine has been first invoked.
 477 .PP
 478 The assumption that \fBCOLOR_BLACK\fR is the default
 479 background color for all terminals can be modified using the
 480 \fBassume_default_colors\fR(3X) extension.
 481 .PP
 482 This implementation checks the pointers,
 483 e.g., for the values returned by
 484 \fBcolor_content\fP and \fBpair_content\fP,
 485 and will treat those as optional parameters when null.
 486 .PP
 487 X/Open Curses does not specify a limit for the number of colors and
 488 color pairs which a terminal can support.
 489 However, in its use of \fBshort\fP for the parameters,
 490 it carries over SVr4's implementation detail for the compiled
 491 terminfo database, which uses signed 16-bit numbers.
 492 This implementation provides extended versions of those functions
 493 which use \fBshort\fP parameters,
 494 allowing applications to use larger color- and pair-numbers.
 495 .PP
 496 The \fBreset_color_pairs\fP function is an extension of ncurses.
 497 .SH SEE ALSO
 498 \fBcurses\fR(3X),
 499 \fBcurs_initscr\fR(3X),
 500 \fBcurs_attr\fR(3X),
 501 \fBcurs_variables\fR(3X),
 502 \fBdefault_colors\fR(3X)