doc/html/man/curs_color.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2019,2020 Thomas E. Dickey                                *
   4   * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
   5   *                                                                          *
   6   * Permission is hereby granted, free of charge, to any person obtaining a  *
   7   * copy of this software and associated documentation files (the            *
   8   * "Software"), to deal in the Software without restriction, including      *
   9   * without limitation the rights to use, copy, modify, merge, publish,      *
  10   * distribute, distribute with modifications, sublicense, and/or sell       *
  11   * copies of the Software, and to permit persons to whom the Software is    *
  12   * furnished to do so, subject to the following conditions:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  24   *                                                                          *
  25   * Except as contained in this notice, the name(s) of the above copyright   *
  26   * holders shall not be used in advertising or otherwise to promote the     *
  27   * sale, use or other dealings in this Software without prior written       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: curs_color.3x,v 1.63 2020/10/24 09:35:23 tom Exp @
  31 -->
  32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  33 <HTML>
  34 <HEAD>
  35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  37 <TITLE>curs_color 3x</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">curs_color 3x</H1>
  43 <PRE>
  44 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>                                                  <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
  45
  46
  47
  48
  49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        <STRONG>start_color</STRONG>, <STRONG>has_colors</STRONG>, <STRONG>can_change_color</STRONG>, <STRONG>init_pair</STRONG>, <STRONG>init_color</STRONG>,
  51        <STRONG>init_extended_pair</STRONG>, <STRONG>init_extended_color</STRONG>, <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>,
  52        <STRONG>extended_color_content</STRONG>, <STRONG>extended_pair_content</STRONG>, <STRONG>reset_color_pairs</STRONG>,
  53        <STRONG>COLOR_PAIR</STRONG>, <STRONG>PAIR_NUMBER</STRONG> - <STRONG>curses</STRONG> color manipulation routines
  54
  55
  56 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  57        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  58
  59        <STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
  60
  61        <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
  62        <STRONG>bool</STRONG> <STRONG>can_change_color(void);</STRONG>
  63
  64        <STRONG>int</STRONG> <STRONG>init_pair(short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>f</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>b</EM><STRONG>);</STRONG>
  65        <STRONG>int</STRONG> <STRONG>init_color(short</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>r</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>g</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>b</EM><STRONG>);</STRONG>
  66        /* extensions */
  67        <STRONG>int</STRONG> <STRONG>init_extended_pair(int</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>f</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>b</EM><STRONG>);</STRONG>
  68        <STRONG>int</STRONG> <STRONG>init_extended_color(int</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>r</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>g</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>b</EM><STRONG>);</STRONG>
  69
  70        <STRONG>int</STRONG> <STRONG>color_content(short</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>r</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>g</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>b</EM><STRONG>);</STRONG>
  71        <STRONG>int</STRONG> <STRONG>pair_content(short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>f</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>b</EM><STRONG>);</STRONG>
  72        /* extensions */
  73        <STRONG>int</STRONG> <STRONG>extended_color_content(int</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>r</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>g</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>b</EM><STRONG>);</STRONG>
  74        <STRONG>int</STRONG> <STRONG>extended_pair_content(int</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>f</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>b</EM><STRONG>);</STRONG>
  75
  76        /* extensions */
  77        <STRONG>void</STRONG> <STRONG>reset_color_pairs(void);</STRONG>
  78
  79        <STRONG>int</STRONG> <STRONG>COLOR_PAIR(int</STRONG> <EM>n</EM><STRONG>);</STRONG>
  80        <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM><STRONG>);</STRONG>
  81
  82
  83 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  84
  85 </PRE><H3><a name="h3-Overview">Overview</a></H3><PRE>
  86        <STRONG>curses</STRONG> supports color attributes on terminals with that capability.  To
  87        use  these  routines  <STRONG>start_color</STRONG>  must  be called, usually right after
  88        <STRONG>initscr</STRONG>.  Colors are always used in pairs (referred to as color-pairs).
  89        A  color-pair  consists  of  a  foreground color (for characters) and a
  90        background color (for the blank field on which the characters are  dis-
  91        played).   A  programmer  initializes  a  color-pair  with  the routine
  92        <STRONG>init_pair</STRONG>.  After it has been initialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>) can be used to
  93        convert the pair to a video attribute.
  94
  95        If  a  terminal is capable of redefining colors, the programmer can use
  96        the routine <STRONG>init_color</STRONG> to change the definition of a color.   The  rou-
  97        tines  <STRONG>has_colors</STRONG>  and <STRONG>can_change_color</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>, depending
  98        on whether the terminal has color capabilities and whether the program-
  99        mer can change the colors.  The routine <STRONG>color_content</STRONG> allows a program-
 100        mer to extract the amounts of red, green, and  blue  components  in  an
 101        initialized  color.   The  routine  <STRONG>pair_content</STRONG> allows a programmer to
 102        find out how a given color-pair is currently defined.
 103
 104
 105 </PRE><H3><a name="h3-Color-Rendering">Color Rendering</a></H3><PRE>
 106        The <STRONG>curses</STRONG> library combines these inputs to produce  the  actual  fore-
 107        ground and background colors shown on the screen:
 108
 109        <STRONG>o</STRONG>   per-character video attributes (e.g., via <STRONG>waddch</STRONG>),
 110
 111        <STRONG>o</STRONG>   the window attribute (e.g., by <STRONG>wattrset</STRONG>), and
 112
 113        <STRONG>o</STRONG>   the background character (e.g., <STRONG>wbkgdset</STRONG>).
 114
 115        Per-character and window attributes are usually set by a parameter con-
 116        taining video attributes including a color pair value.  Some  functions
 117        such as <STRONG>wattr_set</STRONG> use a separate parameter which is the color pair num-
 118        ber.
 119
 120        The background character is a special case:  it  includes  a  character
 121        value, just as if it were passed to <STRONG>waddch</STRONG>.
 122
 123        The  <STRONG>curses</STRONG> library does the actual work of combining these color pairs
 124        in an internal function called from <STRONG>waddch</STRONG>:
 125
 126        <STRONG>o</STRONG>   If the parameter passed to <STRONG>waddch</STRONG> is <EM>blank</EM>, and it uses the special
 127            color pair 0,
 128
 129            <STRONG>o</STRONG>   <STRONG>curses</STRONG> next checks the window attribute.
 130
 131            <STRONG>o</STRONG>   If  the window attribute does not use color pair 0, <STRONG>curses</STRONG> uses
 132                the color pair from the window attribute.
 133
 134            <STRONG>o</STRONG>   Otherwise, <STRONG>curses</STRONG> uses the background character.
 135
 136        <STRONG>o</STRONG>   If the parameter passed to <STRONG>waddch</STRONG> is <EM>not</EM> <EM>blank</EM>, or it does not  use
 137            the  special  color  pair 0, <STRONG>curses</STRONG> prefers the color pair from the
 138            parameter, if it is nonzero.  Otherwise, it tries the window attri-
 139            bute next, and finally the background character.
 140
 141        Some  <STRONG>curses</STRONG>  functions such as <STRONG>wprintw</STRONG> call <STRONG>waddch</STRONG>.  Those do not com-
 142        bine its parameter with a color pair.  Consequently those calls use on-
 143        ly the window attribute or the background character.
 144
 145
 146 </PRE><H2><a name="h2-CONSTANTS">CONSTANTS</a></H2><PRE>
 147        In <STRONG>&lt;curses.h&gt;</STRONG> the following macros are defined.  These are the standard
 148        colors (ISO-6429).  <STRONG>curses</STRONG> also assumes that <STRONG>COLOR_BLACK</STRONG> is the default
 149        background color for all terminals.
 150
 151              <STRONG>COLOR_BLACK</STRONG>
 152              <STRONG>COLOR_RED</STRONG>
 153              <STRONG>COLOR_GREEN</STRONG>
 154              <STRONG>COLOR_YELLOW</STRONG>
 155              <STRONG>COLOR_BLUE</STRONG>
 156              <STRONG>COLOR_MAGENTA</STRONG>
 157              <STRONG>COLOR_CYAN</STRONG>
 158              <STRONG>COLOR_WHITE</STRONG>
 159
 160        Some  terminals  support  more than the eight (8) "ANSI" colors.  There
 161        are no standard names for those additional colors.
 162
 163
 164 </PRE><H2><a name="h2-VARIABLES">VARIABLES</a></H2><PRE>
 165
 166 </PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE>
 167        is initialized by <STRONG>start_color</STRONG> to the maximum number of colors the  ter-
 168        minal can support.
 169
 170
 171 </PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE>
 172        is  initialized by <STRONG>start_color</STRONG> to the maximum number of color pairs the
 173        terminal can support.
 174
 175
 176 </PRE><H2><a name="h2-FUNCTIONS">FUNCTIONS</a></H2><PRE>
 177
 178 </PRE><H3><a name="h3-start_color">start_color</a></H3><PRE>
 179        The <STRONG>start_color</STRONG> routine requires no arguments.  It must  be  called  if
 180        the  programmer wants to use colors, and before any other color manipu-
 181        lation routine is called.  It is good practice  to  call  this  routine
 182        right after <STRONG>initscr</STRONG>.  <STRONG>start_color</STRONG> does this:
 183
 184        <STRONG>o</STRONG>   It  initializes  two  global variables, <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG> (re-
 185            spectively defining the maximum number of  colors  and  color-pairs
 186            the terminal can support).
 187
 188        <STRONG>o</STRONG>   It  initializes  the special color pair <STRONG>0</STRONG> to the default foreground
 189            and background colors.  No other color pairs are initialized.
 190
 191        <STRONG>o</STRONG>   It restores the colors on the terminal to the values they had  when
 192            the terminal was just turned on.
 193
 194        <STRONG>o</STRONG>   If  the  terminal supports the <STRONG>initc</STRONG> (<STRONG>initialize_color</STRONG>) capability,
 195            <STRONG>start_color</STRONG> initializes its internal table  representing  the  red,
 196            green, and blue components of the color palette.
 197
 198            The components depend on whether the terminal uses CGA (aka "ANSI")
 199            or HLS (i.e.,  the  <STRONG>hls</STRONG>  (<STRONG>hue_lightness_saturation</STRONG>)  capability  is
 200            set).   The  table  is  initialized  first  for  eight basic colors
 201            (black, red, green, yellow, blue, magenta, cyan, and white),  using
 202            weights that depend upon the CGA/HLS choice.  For "ANSI" colors the
 203            weights are <STRONG>680</STRONG> or <STRONG>0</STRONG> depending on whether  the  corresponding  red,
 204            green,  or  blue component is used or not.  That permits using <STRONG>1000</STRONG>
 205            to represent bold/bright colors.  After the  initial  eight  colors
 206            (if  the  terminal  supports more than eight colors) the components
 207            are initialized using the same pattern, but with weights  of  <STRONG>1000</STRONG>.
 208            SVr4 uses a similar scheme, but uses <STRONG>1000</STRONG> for the components of the
 209            initial eight colors.
 210
 211            <STRONG>start_color</STRONG> does not attempt to set the terminal's color palette to
 212            match its built-in table.  An application may use <STRONG>init_color</STRONG> to al-
 213            ter the internal table along with the terminal's color.
 214
 215        These limits apply to color values and  color  pairs.   Values  outside
 216        these limits are not legal, and may result in a runtime error:
 217
 218        <STRONG>o</STRONG>   <STRONG>COLORS</STRONG>  corresponds to the terminal database's <STRONG>max_colors</STRONG> capabili-
 219            ty, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 220
 221        <STRONG>o</STRONG>   color values are expected to be in the range <STRONG>0</STRONG> to <STRONG>COLORS-1</STRONG>,  inclu-
 222            sive (including <STRONG>0</STRONG> and <STRONG>COLORS-1</STRONG>).
 223
 224        <STRONG>o</STRONG>   a  special  color value <STRONG>-1</STRONG> is used in certain extended functions to
 225            denote the <EM>default</EM> <EM>color</EM> (see <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>).
 226
 227        <STRONG>o</STRONG>   <STRONG>COLOR_PAIRS</STRONG> corresponds to the terminal database's <STRONG>max_pairs</STRONG>  capa-
 228            bility, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 229
 230        <STRONG>o</STRONG>   legal color pair values are in the range <STRONG>1</STRONG> to <STRONG>COLOR_PAIRS-1</STRONG>, inclu-
 231            sive.
 232
 233        <STRONG>o</STRONG>   color pair <STRONG>0</STRONG> is special; it denotes "no color".
 234
 235            Color pair <STRONG>0</STRONG> is assumed to be white on black, but is actually what-
 236            ever  the terminal implements before color is initialized.  It can-
 237            not be modified by the application.
 238
 239
 240 </PRE><H3><a name="h3-has_colors">has_colors</a></H3><PRE>
 241        The <STRONG>has_colors</STRONG> routine requires no arguments.  It returns <STRONG>TRUE</STRONG>  if  the
 242        terminal can manipulate colors; otherwise, it returns <STRONG>FALSE</STRONG>.  This rou-
 243        tine facilitates writing terminal-independent programs.  For example, a
 244        programmer  can  use  it  to  decide whether to use color or some other
 245        video attribute.
 246
 247
 248 </PRE><H3><a name="h3-can_change_color">can_change_color</a></H3><PRE>
 249        The <STRONG>can_change_color</STRONG> routine requires no arguments.  It returns <STRONG>TRUE</STRONG> if
 250        the  terminal  supports colors and can change their definitions; other,
 251        it returns <STRONG>FALSE</STRONG>.  This routine facilitates  writing  terminal-indepen-
 252        dent programs.
 253
 254
 255 </PRE><H3><a name="h3-init_pair">init_pair</a></H3><PRE>
 256        The <STRONG>init_pair</STRONG> routine changes the definition of a color-pair.  It takes
 257        three arguments: the number of the color-pair to be changed, the  fore-
 258        ground color number, and the background color number.  For portable ap-
 259        plications:
 260
 261        <STRONG>o</STRONG>   The first argument must be a legal color pair  value.   If  default
 262            colors are used (see <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>) the upper limit is ad-
 263            justed to allow for extra pairs which use a default color in  fore-
 264            ground and/or background.
 265
 266        <STRONG>o</STRONG>   The second and third arguments must be legal color values.
 267
 268        If  the  color-pair was previously initialized, the screen is refreshed
 269        and all occurrences of that color-pair are changed to the  new  defini-
 270        tion.
 271
 272        As  an  extension,  ncurses  allows you to set color pair <STRONG>0</STRONG> via the <STRONG>as-</STRONG>
 273        <STRONG><A HREF="assume_default_colors.3x.html">sume_default_colors(3x)</A></STRONG> routine, or to specify the use of default  col-
 274        ors  (color  number  <STRONG>-1</STRONG>) if you first invoke the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>
 275        routine.
 276
 277
 278 </PRE><H3><a name="h3-init_extended_pair">init_extended_pair</a></H3><PRE>
 279        Because <STRONG>init_pair</STRONG> uses signed <STRONG>short</STRONG>s for its  parameters,  that  limits
 280        color-pairs  and  color-values to 32767 on modern hardware.  The exten-
 281        sion <STRONG>init_extended_pair</STRONG> uses <STRONG>int</STRONG>s for the color-pair  and  color-value,
 282        allowing a larger number of colors to be supported.
 283
 284
 285 </PRE><H3><a name="h3-init_color">init_color</a></H3><PRE>
 286        The  <STRONG>init_color</STRONG>  routine  changes  the definition of a color.  It takes
 287        four arguments: the number of the color to be changed followed by three
 288        RGB values (for the amounts of red, green, and blue components).
 289
 290        <STRONG>o</STRONG>   The  first argument must be a legal color value; default colors are
 291            not allowed here.  (See the section <STRONG>Colors</STRONG> for  the  default  color
 292            index.)
 293
 294        <STRONG>o</STRONG>   Each  of  the  last  three arguments must be a value in the range <STRONG>0</STRONG>
 295            through <STRONG>1000</STRONG>.
 296
 297        When <STRONG>init_color</STRONG> is used, all occurrences of that color  on  the  screen
 298        immediately change to the new definition.
 299
 300
 301 </PRE><H3><a name="h3-init_extended_color">init_extended_color</a></H3><PRE>
 302        Because  <STRONG>init_color</STRONG>  uses signed <STRONG>short</STRONG>s for its parameters, that limits
 303        color-values and their red, green, and blue components to 32767 on mod-
 304        ern hardware.  The extension <STRONG>init_extended_color</STRONG> uses <STRONG>int</STRONG>s for the col-
 305        or value and for setting the red, green, and blue components,  allowing
 306        a larger number of colors to be supported.
 307
 308
 309 </PRE><H3><a name="h3-color_content">color_content</a></H3><PRE>
 310        The <STRONG>color_content</STRONG> routine gives programmers a way to find the intensity
 311        of the red, green, and blue (RGB) components in a color.   It  requires
 312        four  arguments:  the  color  number, and three addresses of <STRONG>short</STRONG>s for
 313        storing the information about the amounts of red, green, and blue  com-
 314        ponents in the given color.
 315
 316        <STRONG>o</STRONG>   The  first  argument  must  be a legal color value, i.e., <STRONG>0</STRONG> through
 317            <STRONG>COLORS-1</STRONG>, inclusive.
 318
 319        <STRONG>o</STRONG>   The values that are stored at the addresses pointed to by the  last
 320            three  arguments  are  in  the  range <STRONG>0</STRONG> (no component) through <STRONG>1000</STRONG>
 321            (maximum amount of component), inclusive.
 322
 323
 324 </PRE><H3><a name="h3-extended_color_content">extended_color_content</a></H3><PRE>
 325        Because <STRONG>color_content</STRONG> uses signed <STRONG>short</STRONG>s for its parameters, that  lim-
 326        its  color-values and their red, green, and blue components to 32767 on
 327        modern hardware.  The extension <STRONG>extended_color_content</STRONG>  uses  <STRONG>int</STRONG>s  for
 328        the  color value and for returning the red, green, and blue components,
 329        allowing a larger number of colors to be supported.
 330
 331
 332 </PRE><H3><a name="h3-pair_content">pair_content</a></H3><PRE>
 333        The <STRONG>pair_content</STRONG> routine allows programmers to find out what  colors  a
 334        given  color-pair consists of.  It requires three arguments: the color-
 335        pair number, and two addresses of <STRONG>short</STRONG>s for storing the foreground and
 336        the background color numbers.
 337
 338        <STRONG>o</STRONG>   The  first argument must be a legal color value, i.e., in the range
 339            <STRONG>1</STRONG> through <STRONG>COLOR_PAIRS-1</STRONG>, inclusive.
 340
 341        <STRONG>o</STRONG>   The values that are stored at the addresses pointed to by the  sec-
 342            ond  and  third arguments are in the range <STRONG>0</STRONG> through <STRONG>COLORS</STRONG>, inclu-
 343            sive.
 344
 345
 346 </PRE><H3><a name="h3-extended_pair_content">extended_pair_content</a></H3><PRE>
 347        Because <STRONG>pair_content</STRONG> uses signed <STRONG>short</STRONG>s for its parameters, that limits
 348        color-pair and color-values to 32767 on modern hardware.  The extension
 349        <STRONG>extended_pair_content</STRONG> uses <STRONG>int</STRONG>s for the color pair  and  for  returning
 350        the  foreground and background colors, allowing a larger number of col-
 351        ors to be supported.
 352
 353
 354 </PRE><H3><a name="h3-reset_color_pairs">reset_color_pairs</a></H3><PRE>
 355        The extension <STRONG>reset_color_pairs</STRONG> tells ncurses to  discard  all  of  the
 356        color-pair  information  which was set with <STRONG>init_pair</STRONG>.  It also touches
 357        the current- and standard-screens, allowing an  application  to  switch
 358        color palettes rapidly.
 359
 360
 361 </PRE><H3><a name="h3-PAIR_NUMBER">PAIR_NUMBER</a></H3><PRE>
 362        <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM>)  extracts  the  color value from its <EM>attrs</EM> parameter
 363        and returns it as a color pair number.
 364
 365
 366 </PRE><H3><a name="h3-COLOR_PAIR">COLOR_PAIR</a></H3><PRE>
 367        Its inverse <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number to an attribute.
 368        Attributes  can  hold color pairs in the range 0 to 255.  If you need a
 369        color pair larger than that, you must use functions  such  as  <STRONG>attr_set</STRONG>
 370        (which  pass  the  color  pair as a separate parameter) rather than the
 371        legacy functions such as <STRONG>attrset</STRONG>.
 372
 373
 374 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 375        The routines <STRONG>can_change_color</STRONG> and <STRONG>has_colors</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
 376
 377        All other routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG>  (SVr4
 378        specifies  only "an integer value other than <STRONG>ERR</STRONG>") upon successful com-
 379        pletion.
 380
 381        X/Open defines no error conditions.  SVr4 does document some error con-
 382        ditions which apply in general:
 383
 384        <STRONG>o</STRONG>   This implementation will return <STRONG>ERR</STRONG> on attempts to use color values
 385            outside the range <STRONG>0</STRONG> to <STRONG>COLORS</STRONG>-1 (except for the default colors  ex-
 386            tension), or use color pairs outside the range <STRONG>0</STRONG> to <STRONG>COLOR_PAIRS-1</STRONG>.
 387
 388            Color values used in <STRONG>init_color</STRONG> must be in the range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.
 389
 390            An  error  is  returned  from all functions if the terminal has not
 391            been initialized.
 392
 393            An error is returned from secondary functions such as <STRONG>init_pair</STRONG>  if
 394            <STRONG>start_color</STRONG> was not called.
 395
 396        <STRONG>o</STRONG>   SVr4  does much the same, except that it returns <STRONG>ERR</STRONG> from <STRONG>pair_con-</STRONG>
 397            <STRONG>tent</STRONG> if the pair was not initialized using <STRONG>init_pairs</STRONG>  and  it  re-
 398            turns  <STRONG>ERR</STRONG>  from  <STRONG>color_content</STRONG>  if  the  terminal does not support
 399            changing colors.
 400
 401            This implementation does not return <STRONG>ERR</STRONG> for either case.
 402
 403        Specific functions make additional checks:
 404
 405           <STRONG>init_color</STRONG>
 406                returns an error if the terminal does not support this feature,
 407                e.g.,  if  the  <STRONG>initialize_color</STRONG>  capability is absent from the
 408                terminal description.
 409
 410           <STRONG>start_color</STRONG>
 411                returns an error if the color table cannot be allocated.
 412
 413
 414 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 415        In the <STRONG>ncurses</STRONG> implementation, there is  a  separate  color  activation
 416        flag,  color palette, color pairs table, and associated <STRONG>COLORS</STRONG> and <STRONG>COL-</STRONG>
 417        <STRONG>OR_PAIRS</STRONG> counts for each screen; the <STRONG>start_color</STRONG> function only  affects
 418        the current screen.  The SVr4/XSI interface is not really designed with
 419        this in mind, and historical implementations may use  a  single  shared
 420        color palette.
 421
 422        Setting  an  implicit  background  color  via a color pair affects only
 423        character cells that a character write  operation  explicitly  touches.
 424        To  change the background color used when parts of a window are blanked
 425        by erasing or scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
 426
 427        Several caveats apply on older x86 machines  (e.g.,  i386,  i486)  with
 428        VGA-compatible graphics:
 429
 430        <STRONG>o</STRONG>   COLOR_YELLOW  is  actually  brown.  To get yellow, use COLOR_YELLOW
 431            combined with the <STRONG>A_BOLD</STRONG> attribute.
 432
 433        <STRONG>o</STRONG>   The A_BLINK attribute should in theory cause the background  to  go
 434            bright.  This often fails to work, and even some cards for which it
 435            mostly works (such as the Paradise and compatibles)  do  the  wrong
 436            thing  when  you try to set a bright "yellow" background (you get a
 437            blinking yellow foreground instead).
 438
 439        <STRONG>o</STRONG>   Color RGB values are not settable.
 440
 441
 442 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 443        This implementation satisfies XSI Curses's minimum maximums for  <STRONG>COLORS</STRONG>
 444        and <STRONG>COLOR_PAIRS</STRONG>.
 445
 446        The  <STRONG>init_pair</STRONG>  routine accepts negative values of foreground and back-
 447        ground color to support the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG> extension, but  only
 448        if that routine has been first invoked.
 449
 450        The assumption that <STRONG>COLOR_BLACK</STRONG> is the default background color for all
 451        terminals can be modified using  the  <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG>  exten-
 452        sion.
 453
 454        This  implementation checks the pointers, e.g., for the values returned
 455        by <STRONG>color_content</STRONG> and <STRONG>pair_content</STRONG>, and will treat those as optional pa-
 456        rameters when null.
 457
 458        X/Open  Curses  does  not  specify a limit for the number of colors and
 459        color pairs which a terminal can support.  However, in its use of <STRONG>short</STRONG>
 460        for  the  parameters,  it carries over SVr4's implementation detail for
 461        the compiled terminfo database, which uses signed 16-bit numbers.  This
 462        implementation  provides extended versions of those functions which use
 463        <STRONG>short</STRONG> parameters, allowing applications to use larger color- and  pair-
 464        numbers.
 465
 466        The <STRONG>reset_color_pairs</STRONG> function is an extension of ncurses.
 467
 468
 469 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 470        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,  <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,  <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>,  <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>de-</STRONG>
 471        <STRONG><A HREF="default_colors.3x.html">fault_colors(3x)</A></STRONG>
 472
 473
 474
 475                                                                 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
 476 </PRE>
 477 <div class="nav">
 478 <ul>
 479 <li><a href="#h2-NAME">NAME</a></li>
 480 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 481 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 482 <ul>
 483 <li><a href="#h3-Overview">Overview</a></li>
 484 <li><a href="#h3-Color-Rendering">Color Rendering</a></li>
 485 </ul>
 486 </li>
 487 <li><a href="#h2-CONSTANTS">CONSTANTS</a></li>
 488 <li><a href="#h2-VARIABLES">VARIABLES</a>
 489 <ul>
 490 <li><a href="#h3-COLORS">COLORS</a></li>
 491 <li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li>
 492 </ul>
 493 </li>
 494 <li><a href="#h2-FUNCTIONS">FUNCTIONS</a>
 495 <ul>
 496 <li><a href="#h3-start_color">start_color</a></li>
 497 <li><a href="#h3-has_colors">has_colors</a></li>
 498 <li><a href="#h3-can_change_color">can_change_color</a></li>
 499 <li><a href="#h3-init_pair">init_pair</a></li>
 500 <li><a href="#h3-init_extended_pair">init_extended_pair</a></li>
 501 <li><a href="#h3-init_color">init_color</a></li>
 502 <li><a href="#h3-init_extended_color">init_extended_color</a></li>
 503 <li><a href="#h3-color_content">color_content</a></li>
 504 <li><a href="#h3-extended_color_content">extended_color_content</a></li>
 505 <li><a href="#h3-pair_content">pair_content</a></li>
 506 <li><a href="#h3-extended_pair_content">extended_pair_content</a></li>
 507 <li><a href="#h3-reset_color_pairs">reset_color_pairs</a></li>
 508 <li><a href="#h3-PAIR_NUMBER">PAIR_NUMBER</a></li>
 509 <li><a href="#h3-COLOR_PAIR">COLOR_PAIR</a></li>
 510 </ul>
 511 </li>
 512 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 513 <li><a href="#h2-NOTES">NOTES</a></li>
 514 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 515 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 516 </ul>
 517 </div>
 518 </BODY>
 519 </HTML>