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