man/curs_color.3x

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