man/curs_color.3x

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