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

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