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

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2022,2023 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.93 2023/12/16 21:07:24 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 2023-12-16 ncurses 6.4 Library calls</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">curs_color 3x 2023-12-16 ncurses 6.4 Library calls</H1>
  43 <PRE>
  44 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>                   Library calls                  <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>COLORS</STRONG>, <STRONG>COLOR_PAIRS</STRONG>,  <STRONG>COLOR_BLACK</STRONG>,  <STRONG>COLOR_RED</STRONG>,
  54        <STRONG>COLOR_GREEN</STRONG>,   <STRONG>COLOR_YELLOW</STRONG>,   <STRONG>COLOR_BLUE</STRONG>,  <STRONG>COLOR_MAGENTA</STRONG>,  <STRONG>COLOR_CYAN</STRONG>,
  55        <STRONG>COLOR_WHITE</STRONG> - manipulate terminal colors with <EM>curses</EM>
  56
  57
  58 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  59        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  60
  61        <STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
  62
  63        <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
  64        <STRONG>bool</STRONG> <STRONG>can_change_color(void);</STRONG>
  65
  66        <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>
  67        <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>
  68        <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
  69        <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>
  70        <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>
  71
  72        <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>
  73        <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>
  74        <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
  75        <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>
  76        <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>
  77
  78        <EM>/*</EM> <EM>extension</EM> <EM>*/</EM>
  79        <STRONG>void</STRONG> <STRONG>reset_color_pairs(void);</STRONG>
  80
  81        <STRONG>int</STRONG> <STRONG>COLOR_PAIR(int</STRONG> <EM>n</EM><STRONG>);</STRONG>
  82        <STRONG>PAIR_NUMBER(int</STRONG> <EM>attr</EM><STRONG>);</STRONG>
  83
  84
  85 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  86
  87 </PRE><H3><a name="h3-Overview">Overview</a></H3><PRE>
  88        <EM>curses</EM> supports color attributes on terminals with that capability.  To
  89        use  these  routines  <STRONG>start_color</STRONG>  must  be called, usually right after
  90        <STRONG>initscr</STRONG>.  Colors are always used in pairs (referred to as color pairs).
  91        A  color  pair  consists  of  a foreground color (for characters) and a
  92        background color (for the blank  field  on  which  the  characters  are
  93        displayed).   A  programmer  initializes  a color pair with the routine
  94        <STRONG>init_pair</STRONG>.  After it has been initialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>) can be used to
  95        convert the pair to a video attribute.
  96
  97        If  a  terminal is capable of redefining colors, the programmer can use
  98        the routine <STRONG>init_color</STRONG> to  change  the  definition  of  a  color.   The
  99        routines   <STRONG>has_colors</STRONG>   and  <STRONG>can_change_color</STRONG>  return  <STRONG>TRUE</STRONG>  or  <STRONG>FALSE</STRONG>,
 100        depending on whether the terminal has color  capabilities  and  whether
 101        the programmer can change the colors.  The routine <STRONG>color_content</STRONG> allows
 102        a programmer to extract the amounts of red, green, and blue  components
 103        in  an initialized color.  The routine <STRONG>pair_content</STRONG> allows a programmer
 104        to find out how a given color pair is currently defined.
 105
 106
 107 </PRE><H3><a name="h3-Color-Rendering">Color Rendering</a></H3><PRE>
 108        The  <EM>curses</EM>  library  combines  these  inputs  to  produce  the  actual
 109        foreground and background colors shown on the screen:
 110
 111        <STRONG>o</STRONG>   per-character video attributes (e.g., via <STRONG>waddch</STRONG>),
 112
 113        <STRONG>o</STRONG>   the window attribute (e.g., by <STRONG>wattrset</STRONG>), and
 114
 115        <STRONG>o</STRONG>   the background character (e.g., <STRONG>wbkgdset</STRONG>).
 116
 117        Per-character  and  window  attributes  are  usually set by a parameter
 118        containing  video  attributes  including  a  color  pair  value.   Some
 119        functions such as <STRONG>wattr_set</STRONG> use a separate parameter which is the color
 120        pair number.
 121
 122        The background character is a special case:  it  includes  a  character
 123        value, just as if it were passed to <STRONG>waddch</STRONG>.
 124
 125        The  <EM>curses</EM> library does the actual work of combining these color pairs
 126        in an internal function called from <STRONG>waddch</STRONG>:
 127
 128        <STRONG>o</STRONG>   If the parameter passed to <STRONG>waddch</STRONG> is <EM>blank</EM>, and it uses the special
 129            color pair 0,
 130
 131            <STRONG>o</STRONG>   <EM>curses</EM> next checks the window attribute.
 132
 133            <STRONG>o</STRONG>   If  the window attribute does not use color pair 0, <EM>curses</EM> uses
 134                the color pair from the window attribute.
 135
 136            <STRONG>o</STRONG>   Otherwise, <EM>curses</EM> uses the background character.
 137
 138        <STRONG>o</STRONG>   If the parameter passed to <STRONG>waddch</STRONG> is <EM>not</EM> <EM>blank</EM>, or it does not  use
 139            the  special  color  pair 0, <EM>curses</EM> prefers the color pair from the
 140            parameter, if it  is  nonzero.   Otherwise,  it  tries  the  window
 141            attribute next, and finally the background character.
 142
 143        Some  <EM>curses</EM>  functions  such  as  <STRONG>wprintw</STRONG>  call  <STRONG>waddch</STRONG>.  Those do not
 144        combine its parameter with a color pair.  Consequently those calls  use
 145        only the window attribute or the background character.
 146
 147
 148 </PRE><H2><a name="h2-CONSTANTS">CONSTANTS</a></H2><PRE>
 149        In <STRONG>&lt;curses.h&gt;</STRONG> the following macros are defined.  These are the standard
 150        colors (ISO-6429).  <EM>curses</EM> also assumes that <STRONG>COLOR_BLACK</STRONG> is the default
 151        background color for all terminals.
 152
 153              <STRONG>COLOR_BLACK</STRONG>
 154              <STRONG>COLOR_RED</STRONG>
 155              <STRONG>COLOR_GREEN</STRONG>
 156              <STRONG>COLOR_YELLOW</STRONG>
 157              <STRONG>COLOR_BLUE</STRONG>
 158              <STRONG>COLOR_MAGENTA</STRONG>
 159              <STRONG>COLOR_CYAN</STRONG>
 160              <STRONG>COLOR_WHITE</STRONG>
 161
 162        Some  terminals  support  more than the eight (8) "ANSI" colors.  There
 163        are no standard names for those additional colors.
 164
 165
 166 </PRE><H2><a name="h2-VARIABLES">VARIABLES</a></H2><PRE>
 167
 168 </PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE>
 169        is initialized by <STRONG>start_color</STRONG> to  the  maximum  number  of  colors  the
 170        terminal can support.
 171
 172
 173 </PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE>
 174        is  initialized by <STRONG>start_color</STRONG> to the maximum number of color pairs the
 175        terminal can support.
 176
 177
 178 </PRE><H2><a name="h2-FUNCTIONS">FUNCTIONS</a></H2><PRE>
 179
 180 </PRE><H3><a name="h3-start_color">start_color</a></H3><PRE>
 181        The <STRONG>start_color</STRONG> routine requires no arguments.  It must  be  called  if
 182        the  programmer  wants  to  use  colors,  and  before  any  other color
 183        manipulation routine is called.  It  is  good  practice  to  call  this
 184        routine right after <STRONG>initscr</STRONG>.  <STRONG>start_color</STRONG> does this:
 185
 186        <STRONG>o</STRONG>   It   initializes  two  global  variables,  <STRONG>COLORS</STRONG>  and  <STRONG>COLOR_PAIRS</STRONG>
 187            (respectively defining the maximum number of colors and color pairs
 188            the terminal can support).
 189
 190        <STRONG>o</STRONG>   It  initializes  the special color pair <STRONG>0</STRONG> to the default foreground
 191            and background colors.  No other color pairs are initialized.
 192
 193        <STRONG>o</STRONG>   It restores the colors on the terminal to the values they had  when
 194            the terminal was just turned on.
 195
 196        <STRONG>o</STRONG>   If  the  terminal supports the <STRONG>initc</STRONG> (<STRONG>initialize_color</STRONG>) capability,
 197            <STRONG>start_color</STRONG> initializes its internal table  representing  the  red,
 198            green, and blue components of the color palette.
 199
 200            The components depend on whether the terminal uses CGA (aka "ANSI")
 201            or HLS (i.e.,  the  <STRONG>hls</STRONG>  (<STRONG>hue_lightness_saturation</STRONG>)  capability  is
 202            set).   The  table  is  initialized  first  for  eight basic colors
 203            (black, red, green, yellow, blue, magenta, cyan, and white),  using
 204            weights that depend upon the CGA/HLS choice.  For "ANSI" colors the
 205            weights are <STRONG>680</STRONG> or <STRONG>0</STRONG> depending on whether  the  corresponding  red,
 206            green,  or  blue component is used or not.  That permits using <STRONG>1000</STRONG>
 207            to represent bold/bright colors.  After the  initial  eight  colors
 208            (if  the  terminal  supports more than eight colors) the components
 209            are initialized using the same pattern, but with weights  of  <STRONG>1000</STRONG>.
 210            SVr4 uses a similar scheme, but uses <STRONG>1000</STRONG> for the components of the
 211            initial eight colors.
 212
 213            <STRONG>start_color</STRONG> does not attempt to set the terminal's color palette to
 214            match  its  built-in  table.   An application may use <STRONG>init_color</STRONG> to
 215            alter the internal table along with the terminal's color.
 216
 217        These limits apply to color values and  color  pairs.   Values  outside
 218        these limits are not valid, and may result in a runtime error:
 219
 220        <STRONG>o</STRONG>   <STRONG>COLORS</STRONG>   corresponds   to   the   terminal   database's  <STRONG>max_colors</STRONG>
 221            capability, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 222
 223        <STRONG>o</STRONG>   color values are expected  to  be  in  the  range  <STRONG>0</STRONG>  to  <STRONG>COLORS-1</STRONG>,
 224            inclusive (including <STRONG>0</STRONG> and <STRONG>COLORS-1</STRONG>).
 225
 226        <STRONG>o</STRONG>   a  special  color value <STRONG>-1</STRONG> is used in certain extended functions to
 227            denote the <EM>default</EM> <EM>color</EM> (see <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>).
 228
 229        <STRONG>o</STRONG>   <STRONG>COLOR_PAIRS</STRONG>  corresponds  to  the  terminal  database's   <STRONG>max_pairs</STRONG>
 230            capability, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 231
 232        <STRONG>o</STRONG>   valid  color  pair  values  are  in  the  range <STRONG>1</STRONG> to <STRONG>COLOR_PAIRS-1</STRONG>,
 233            inclusive.
 234
 235        <STRONG>o</STRONG>   color pair <STRONG>0</STRONG> is special; it denotes "no color".
 236
 237            Color pair <STRONG>0</STRONG> is assumed to be  white  on  black,  but  is  actually
 238            whatever  the  terminal implements before color is initialized.  It
 239            cannot be modified by the application.
 240
 241
 242 </PRE><H3><a name="h3-has_colors">has_colors</a></H3><PRE>
 243        The <STRONG>has_colors</STRONG> routine requires no arguments.  It returns <STRONG>TRUE</STRONG>  if  the
 244        terminal  can  manipulate  colors;  otherwise,  it returns <STRONG>FALSE</STRONG>.  This
 245        routine  facilitates  writing   terminal-independent   programs.    For
 246        example, a programmer can use it to decide whether to use color or some
 247        other video attribute.
 248
 249
 250 </PRE><H3><a name="h3-can_change_color">can_change_color</a></H3><PRE>
 251        The <STRONG>can_change_color</STRONG> routine requires no arguments.  It returns <STRONG>TRUE</STRONG> if
 252        the  terminal  supports colors and can change their definitions; other,
 253        it  returns  <STRONG>FALSE</STRONG>.   This  routine   facilitates   writing   terminal-
 254        independent programs.
 255
 256
 257 </PRE><H3><a name="h3-init_pair">init_pair</a></H3><PRE>
 258        The <STRONG>init_pair</STRONG> routine changes the definition of a color pair.  It takes
 259        three arguments: the number of  the  color  pair  to  be  changed,  the
 260        foreground color number, and the background color number.  For portable
 261        applications:
 262
 263        <STRONG>o</STRONG>   The first argument must be a valid color pair  value.   If  default
 264            colors  are  used  (see  <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>) the upper limit is
 265            adjusted to allow for extra pairs which  use  a  default  color  in
 266            foreground and/or background.
 267
 268        <STRONG>o</STRONG>   The second and third arguments must be valid color values.
 269
 270        If  the  color pair was previously initialized, the screen is refreshed
 271        and all  occurrences  of  that  color  pair  are  changed  to  the  new
 272        definition.
 273
 274        As  an  extension,  <EM>ncurses</EM>  allows  you  to  set  color pair <STRONG>0</STRONG> via the
 275        <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG> routine, or to specify  the  use  of  default
 276        colors (color number <STRONG>-1</STRONG>) if you first invoke the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>
 277        routine.
 278
 279
 280 </PRE><H3><a name="h3-init_extended_pair">init_extended_pair</a></H3><PRE>
 281        Because <STRONG>init_pair</STRONG> uses signed <STRONG>short</STRONG>s for its  parameters,  that  limits
 282        color  pairs  and  color-values  to  32767  on  modern  hardware.   The
 283        extension <STRONG>init_extended_pair</STRONG> uses <STRONG>int</STRONG>s for the color  pair  and  color-
 284        value, allowing a larger number of colors to be supported.
 285
 286
 287 </PRE><H3><a name="h3-init_color">init_color</a></H3><PRE>
 288        The  <STRONG>init_color</STRONG>  routine  changes  the definition of a color.  It takes
 289        four arguments: the number of the color to be changed followed by three
 290        RGB values (for the amounts of red, green, and blue components).
 291
 292        <STRONG>o</STRONG>   The  first argument must be a valid color value; default colors are
 293            not allowed here.  (See the section <STRONG>Colors</STRONG> for  the  default  color
 294            index.)
 295
 296        <STRONG>o</STRONG>   Each  of  the  last  three arguments must be a value in the range <STRONG>0</STRONG>
 297            through <STRONG>1000</STRONG>.
 298
 299        When <STRONG>init_color</STRONG> is used, all occurrences of that color  on  the  screen
 300        immediately change to the new definition.
 301
 302
 303 </PRE><H3><a name="h3-init_extended_color">init_extended_color</a></H3><PRE>
 304        Because  <STRONG>init_color</STRONG>  uses signed <STRONG>short</STRONG>s for its parameters, that limits
 305        color-values and their red, green, and  blue  components  to  32767  on
 306        modern  hardware.   The extension <STRONG>init_extended_color</STRONG> uses <STRONG>int</STRONG>s for the
 307        color value and for  setting  the  red,  green,  and  blue  components,
 308        allowing a larger number of colors to be supported.
 309
 310
 311 </PRE><H3><a name="h3-color_content">color_content</a></H3><PRE>
 312        The <STRONG>color_content</STRONG> routine gives programmers a way to find the intensity
 313        of the red, green, and blue (RGB) components in a color.   It  requires
 314        four  arguments:  the  color  number, and three addresses of <STRONG>short</STRONG>s for
 315        storing the information about the  amounts  of  red,  green,  and  blue
 316        components in the given color.
 317
 318        <STRONG>o</STRONG>   The  first  argument  must  be a valid color value, i.e., <STRONG>0</STRONG> through
 319            <STRONG>COLORS-1</STRONG>, inclusive.
 320
 321        <STRONG>o</STRONG>   The values that are stored at the addresses pointed to by the  last
 322            three  arguments  are  in  the  range <STRONG>0</STRONG> (no component) through <STRONG>1000</STRONG>
 323            (maximum amount of component), inclusive.
 324
 325
 326 </PRE><H3><a name="h3-extended_color_content">extended_color_content</a></H3><PRE>
 327        Because <STRONG>color_content</STRONG> uses  signed  <STRONG>short</STRONG>s  for  its  parameters,  that
 328        limits  color-values and their red, green, and blue components to 32767
 329        on modern hardware.  The extension <STRONG>extended_color_content</STRONG> uses <STRONG>int</STRONG>s for
 330        the  color value and for returning the red, green, and blue components,
 331        allowing a larger number of colors to be supported.
 332
 333
 334 </PRE><H3><a name="h3-pair_content">pair_content</a></H3><PRE>
 335        The <STRONG>pair_content</STRONG> routine allows programmers to find out what  colors  a
 336        given  color  pair consists of.  It requires three arguments: the color
 337        pair number, and two addresses of <STRONG>short</STRONG>s for storing the foreground and
 338        the background color numbers.
 339
 340        <STRONG>o</STRONG>   The  first argument must be a valid color value, i.e., in the range
 341            <STRONG>1</STRONG> through <STRONG>COLOR_PAIRS-1</STRONG>, inclusive.
 342
 343        <STRONG>o</STRONG>   The values that are stored at  the  addresses  pointed  to  by  the
 344            second  and  third  arguments  are  in  the range <STRONG>0</STRONG> through <STRONG>COLORS</STRONG>,
 345            inclusive.
 346
 347
 348 </PRE><H3><a name="h3-extended_pair_content">extended_pair_content</a></H3><PRE>
 349        Because <STRONG>pair_content</STRONG> uses signed <STRONG>short</STRONG>s for its parameters, that limits
 350        color pair and color-values to 32767 on modern hardware.  The extension
 351        <STRONG>extended_pair_content</STRONG> uses <STRONG>int</STRONG>s for the color pair  and  for  returning
 352        the  foreground  and  background  colors,  allowing  a larger number of
 353        colors to be supported.
 354
 355
 356 </PRE><H3><a name="h3-reset_color_pairs">reset_color_pairs</a></H3><PRE>
 357        The extension <STRONG>reset_color_pairs</STRONG> tells <EM>ncurses</EM> to  discard  all  of  the
 358        color  pair  information which was set with <STRONG>init_pair</STRONG>.  It also touches
 359        the current- and standard-screens, allowing an  application  to  switch
 360        color palettes rapidly.
 361
 362
 363 </PRE><H3><a name="h3-COLOR_PAIR">COLOR_PAIR</a></H3><PRE>
 364        <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number to an attribute.  Attributes
 365        can hold color pairs in the range 0 to 255.  If you need a  color  pair
 366        larger  than  that, you must use functions such as <STRONG>attr_set</STRONG> (which pass
 367        the color  pair  as  a  separate  parameter)  rather  than  the  legacy
 368        functions such as <STRONG>attrset</STRONG>.
 369
 370
 371 </PRE><H3><a name="h3-PAIR_NUMBER">PAIR_NUMBER</a></H3><PRE>
 372        <STRONG>PAIR_NUMBER(</STRONG><EM>attr</EM>)   extracts   the  color  information  from  its  <EM>attr</EM>
 373        parameter and returns it as a color pair  number;  it  is  the  inverse
 374        operation of <STRONG>COLOR_PAIR</STRONG>.
 375
 376
 377 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 378        The routines <STRONG>can_change_color</STRONG> and <STRONG>has_colors</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
 379
 380        All  other routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4
 381        specifies only "an integer  value  other  than  <STRONG>ERR</STRONG>")  upon  successful
 382        completion.
 383
 384        X/Open  defines  no  error  conditions.   SVr4 does document some error
 385        conditions which apply in general:
 386
 387        <STRONG>o</STRONG>   This implementation will return <STRONG>ERR</STRONG> on attempts to use color values
 388            outside  the  range  <STRONG>0</STRONG>  to  <STRONG>COLORS</STRONG>-1 (except for the default colors
 389            extension),  or  use  color  pairs   outside   the   range   <STRONG>0</STRONG>   to
 390            <STRONG>COLOR_PAIRS-1</STRONG>.
 391
 392            Color values used in <STRONG>init_color</STRONG> must be in the range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.
 393
 394            An  error  is  returned  from all functions if the terminal has not
 395            been initialized.
 396
 397            An error is returned from secondary functions such as <STRONG>init_pair</STRONG>  if
 398            <STRONG>start_color</STRONG> was not called.
 399
 400        <STRONG>o</STRONG>   SVr4   does  much  the  same,  except  that  it  returns  <STRONG>ERR</STRONG>  from
 401            <STRONG>pair_content</STRONG> if the pair was not initialized using  <STRONG>init_pairs</STRONG>  and
 402            it  returns <STRONG>ERR</STRONG> from <STRONG>color_content</STRONG> if the terminal does not support
 403            changing colors.
 404
 405            This implementation does not return <STRONG>ERR</STRONG> for either case.
 406
 407        Specific functions make additional checks:
 408
 409           <STRONG>init_color</STRONG>
 410                returns an error if the terminal does not support this feature,
 411                e.g.,  if  the  <STRONG>initialize_color</STRONG>  capability is absent from the
 412                terminal description.
 413
 414           <STRONG>start_color</STRONG>
 415                returns an error if the color table cannot be allocated.
 416
 417
 418 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 419        In the <EM>ncurses</EM> implementation, there is  a  separate  color  activation
 420        flag,  color  palette,  color  pairs  table,  and associated <STRONG>COLORS</STRONG> and
 421        <STRONG>COLOR_PAIRS</STRONG> counts for  each  screen;  the  <STRONG>start_color</STRONG>  function  only
 422        affects  the  current  screen.   The  SVr4/XSI  interface is not really
 423        designed with this in mind, and historical implementations  may  use  a
 424        single shared color palette.
 425
 426        Setting  an  implicit  background  color  via a color pair affects only
 427        character cells that a character write  operation  explicitly  touches.
 428        To  change the background color used when parts of a window are blanked
 429        by erasing or scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
 430
 431        Several caveats apply on older x86 machines  (e.g.,  i386,  i486)  with
 432        VGA-compatible graphics:
 433
 434        <STRONG>o</STRONG>   COLOR_YELLOW  is  actually  brown.  To get yellow, use COLOR_YELLOW
 435            combined with the <STRONG>A_BOLD</STRONG> attribute.
 436
 437        <STRONG>o</STRONG>   The A_BLINK attribute should in theory cause the background  to  go
 438            bright.  This often fails to work, and even some cards for which it
 439            mostly works (such as the Paradise and compatibles)  do  the  wrong
 440            thing  when  you try to set a bright "yellow" background (you get a
 441            blinking yellow foreground instead).
 442
 443        <STRONG>o</STRONG>   Color RGB values are not settable.
 444
 445
 446 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 447        The functions marked as extensions were designed for  <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>,  and
 448        are  not  found  in  SVr4  curses, 4.4BSD curses, or any other previous
 449        version of curses.
 450
 451
 452 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 453        This implementation satisfies XSI Curses's minimum maximums for  <STRONG>COLORS</STRONG>
 454        and <STRONG>COLOR_PAIRS</STRONG>.
 455
 456        The  <STRONG>init_pair</STRONG>  routine  accepts  negative  values  of  foreground  and
 457        background color to support the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>  extension,  but
 458        only if that routine has been first invoked.
 459
 460        The assumption that <STRONG>COLOR_BLACK</STRONG> is the default background color for all
 461        terminals  can  be   modified   using   the   <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG>
 462        extension.
 463
 464        This  implementation checks the pointers, e.g., for the values returned
 465        by <STRONG>color_content</STRONG> and <STRONG>pair_content</STRONG>, and will  treat  those  as  optional
 466        parameters when null.
 467
 468        X/Open  Curses  does  not  specify a limit for the number of colors and
 469        color pairs which a terminal can support.  However, in its use of <STRONG>short</STRONG>
 470        for  the  parameters,  it carries over SVr4's implementation detail for
 471        the compiled terminfo database, which uses signed 16-bit numbers.  This
 472        implementation  provides extended versions of those functions which use
 473        <STRONG>short</STRONG> parameters, allowing applications to use larger color- and  pair-
 474        numbers.
 475
 476        The <STRONG>reset_color_pairs</STRONG> function is an extension of <EM>ncurses</EM>.
 477
 478
 479 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 480        SVr3.2 introduced color support to curses in 1987.
 481
 482        SVr4  made  internal  changes,  e.g.,  moving the storage for the color
 483        state  from  <STRONG>SP</STRONG>  (the  <STRONG>SCREEN</STRONG>  structure)  to  <STRONG>cur_term</STRONG>  (the  <STRONG>TERMINAL</STRONG>
 484        structure), but provided the same set of library functions.
 485
 486        SVr4  curses  limits  the  number of color pairs to 64, reserving color
 487        pair zero (0) as the terminal's initial uncolored  state.   This  limit
 488        arises  because  the color pair information is a bitfield in the <STRONG>chtype</STRONG>
 489        data type (denoted by <STRONG>A_COLOR</STRONG>).
 490
 491        Other implementations of curses had different limits:
 492
 493        <STRONG>o</STRONG>   PCCurses (1987-1990) provided for only eight (8) colors.
 494
 495        <STRONG>o</STRONG>   PDCurses  (1992-present)  inherited  the  8-color  limitation  from
 496            PCCurses, but changed this to 256 in version 2.5 (2001), along with
 497            changing <STRONG>chtype</STRONG> from 16-bits to 32-bits.
 498
 499        <STRONG>o</STRONG>   X/Open Curses (1992-present) added a new structure <STRONG>cchar_t</STRONG> to store
 500            the character, attributes and color pair values, allowing increased
 501            range of color pairs.  Both color pairs  and  color-values  used  a
 502            signed <STRONG>short</STRONG>, limiting values to 15 bits.
 503
 504        <STRONG>o</STRONG>   <EM>ncurses</EM>  (1992-present)  uses  eight  bits  for  <STRONG>A_COLOR</STRONG>  in <STRONG>chtype</STRONG>
 505            values.
 506
 507            Version 5.3 provided a wide-character interface  (2002),  but  left
 508            color pairs as part of the attributes-field.
 509
 510            Since version 6 (2015), ncurses uses a separate <STRONG>int</STRONG> for color pairs
 511            in the <STRONG>cchar_t</STRONG> values.  When those color pair values fit in 8 bits,
 512            ncurses  allows  color  pairs  to  be manipulated via the functions
 513            using <STRONG>chtype</STRONG> values.
 514
 515        <STRONG>o</STRONG>   NetBSD curses used  6  bits  from  2000  (when  colors  were  first
 516            supported)  until  2004.   At  that point, NetBSD changed to use 10
 517            bits.  As of 2021, that size is  unchanged.   Like  <EM>ncurses</EM>  before
 518            version  6,  the  NetBSD  color  pair  information is stored in the
 519            attributes field of <STRONG>cchar_t</STRONG>, limiting the number of color pairs  by
 520            the size of the bitfield.
 521
 522
 523 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 524        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,    <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>,   <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,   <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,
 525        <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>
 526
 527
 528
 529 ncurses 6.4                       2023-12-16                    <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
 530 </PRE>
 531 <div class="nav">
 532 <ul>
 533 <li><a href="#h2-NAME">NAME</a></li>
 534 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 535 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 536 <ul>
 537 <li><a href="#h3-Overview">Overview</a></li>
 538 <li><a href="#h3-Color-Rendering">Color Rendering</a></li>
 539 </ul>
 540 </li>
 541 <li><a href="#h2-CONSTANTS">CONSTANTS</a></li>
 542 <li><a href="#h2-VARIABLES">VARIABLES</a>
 543 <ul>
 544 <li><a href="#h3-COLORS">COLORS</a></li>
 545 <li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li>
 546 </ul>
 547 </li>
 548 <li><a href="#h2-FUNCTIONS">FUNCTIONS</a>
 549 <ul>
 550 <li><a href="#h3-start_color">start_color</a></li>
 551 <li><a href="#h3-has_colors">has_colors</a></li>
 552 <li><a href="#h3-can_change_color">can_change_color</a></li>
 553 <li><a href="#h3-init_pair">init_pair</a></li>
 554 <li><a href="#h3-init_extended_pair">init_extended_pair</a></li>
 555 <li><a href="#h3-init_color">init_color</a></li>
 556 <li><a href="#h3-init_extended_color">init_extended_color</a></li>
 557 <li><a href="#h3-color_content">color_content</a></li>
 558 <li><a href="#h3-extended_color_content">extended_color_content</a></li>
 559 <li><a href="#h3-pair_content">pair_content</a></li>
 560 <li><a href="#h3-extended_pair_content">extended_pair_content</a></li>
 561 <li><a href="#h3-reset_color_pairs">reset_color_pairs</a></li>
 562 <li><a href="#h3-COLOR_PAIR">COLOR_PAIR</a></li>
 563 <li><a href="#h3-PAIR_NUMBER">PAIR_NUMBER</a></li>
 564 </ul>
 565 </li>
 566 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 567 <li><a href="#h2-NOTES">NOTES</a></li>
 568 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 569 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 570 <li><a href="#h2-HISTORY">HISTORY</a></li>
 571 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 572 </ul>
 573 </div>
 574 </BODY>
 575 </HTML>