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.92 2023/11/25 17:36:51 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-11-25 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-11-25 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> - manipulate terminal colors with <EM>curses</EM>
  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        <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
  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        <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
  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        <EM>/*</EM> <EM>extension</EM> <EM>*/</EM>
  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        <EM>curses</EM> 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
  91        displayed).   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
  97        routines   <STRONG>has_colors</STRONG>   and  <STRONG>can_change_color</STRONG>  return  <STRONG>TRUE</STRONG>  or  <STRONG>FALSE</STRONG>,
  98        depending on whether the terminal has color  capabilities  and  whether
  99        the programmer can change the colors.  The routine <STRONG>color_content</STRONG> allows
 100        a programmer to extract the amounts of red, green, and blue  components
 101        in  an initialized color.  The routine <STRONG>pair_content</STRONG> allows a programmer
 102        to 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  <EM>curses</EM>  library  combines  these  inputs  to  produce  the  actual
 107        foreground 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
 116        containing  video  attributes  including  a  color  pair  value.   Some
 117        functions such as <STRONG>wattr_set</STRONG> use a separate parameter which is the color
 118        pair number.
 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  <EM>curses</EM> 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>   <EM>curses</EM> next checks the window attribute.
 130
 131            <STRONG>o</STRONG>   If  the window attribute does not use color pair 0, <EM>curses</EM> uses
 132                the color pair from the window attribute.
 133
 134            <STRONG>o</STRONG>   Otherwise, <EM>curses</EM> 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, <EM>curses</EM> prefers the color pair from the
 138            parameter, if it  is  nonzero.   Otherwise,  it  tries  the  window
 139            attribute next, and finally the background character.
 140
 141        Some  <EM>curses</EM>  functions  such  as  <STRONG>wprintw</STRONG>  call  <STRONG>waddch</STRONG>.  Those do not
 142        combine its parameter with a color pair.  Consequently those calls  use
 143        only 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).  <EM>curses</EM> 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
 168        terminal 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
 181        manipulation routine is called.  It  is  good  practice  to  call  this
 182        routine 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>
 185            (respectively 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
 213            alter 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 valid, 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>
 219            capability, (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>,
 222            inclusive (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>
 228            capability, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 229
 230        <STRONG>o</STRONG>   valid  color  pair  values  are  in  the  range <STRONG>1</STRONG> to <STRONG>COLOR_PAIRS-1</STRONG>,
 231            inclusive.
 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
 236            whatever  the  terminal implements before color is initialized.  It
 237            cannot 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
 243        routine  facilitates  writing   terminal-independent   programs.    For
 244        example, a programmer can use it to decide whether to use color or some
 245        other 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-
 252        independent 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
 258        foreground color number, and the background color number.  For portable
 259        applications:
 260
 261        <STRONG>o</STRONG>   The first argument must be a valid 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
 263            adjusted to allow for extra pairs which  use  a  default  color  in
 264            foreground and/or background.
 265
 266        <STRONG>o</STRONG>   The second and third arguments must be valid 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
 270        definition.
 271
 272        As  an  extension,  ncurses  allows  you  to  set  color pair <STRONG>0</STRONG> via the
 273        <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG> routine, or to specify  the  use  of  default
 274        colors (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
 281        extension <STRONG>init_extended_pair</STRONG> uses <STRONG>int</STRONG>s for the  color-pair  and  color-
 282        value, 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 valid 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
 304        modern  hardware.   The extension <STRONG>init_extended_color</STRONG> uses <STRONG>int</STRONG>s for the
 305        color value and for  setting  the  red,  green,  and  blue  components,
 306        allowing 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
 314        components in the given color.
 315
 316        <STRONG>o</STRONG>   The  first  argument  must  be a valid 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
 326        limits  color-values and their red, green, and blue components to 32767
 327        on 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 valid 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
 342            second  and  third  arguments  are  in  the range <STRONG>0</STRONG> through <STRONG>COLORS</STRONG>,
 343            inclusive.
 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
 351        colors 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
 379        completion.
 380
 381        X/Open defines no error conditions.   SVr4  does  document  some  error
 382        conditions 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
 386            extension),   or   use   color   pairs   outside  the  range  <STRONG>0</STRONG>  to
 387            <STRONG>COLOR_PAIRS-1</STRONG>.
 388
 389            Color values used in <STRONG>init_color</STRONG> must be in the range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.
 390
 391            An error is returned from all functions if  the  terminal  has  not
 392            been initialized.
 393
 394            An  error is returned from secondary functions such as <STRONG>init_pair</STRONG> if
 395            <STRONG>start_color</STRONG> was not called.
 396
 397        <STRONG>o</STRONG>   SVr4  does  much  the  same,  except  that  it  returns  <STRONG>ERR</STRONG>   from
 398            <STRONG>pair_content</STRONG>  if  the pair was not initialized using <STRONG>init_pairs</STRONG> and
 399            it returns <STRONG>ERR</STRONG> from <STRONG>color_content</STRONG> if the terminal does not  support
 400            changing colors.
 401
 402            This implementation does not return <STRONG>ERR</STRONG> for either case.
 403
 404        Specific functions make additional checks:
 405
 406           <STRONG>init_color</STRONG>
 407                returns an error if the terminal does not support this feature,
 408                e.g., if the <STRONG>initialize_color</STRONG> capability  is  absent  from  the
 409                terminal description.
 410
 411           <STRONG>start_color</STRONG>
 412                returns an error if the color table cannot be allocated.
 413
 414
 415 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 416        In  the  <EM>ncurses</EM>  implementation,  there is a separate color activation
 417        flag, color palette, color  pairs  table,  and  associated  <STRONG>COLORS</STRONG>  and
 418        <STRONG>COLOR_PAIRS</STRONG>  counts  for  each  screen;  the  <STRONG>start_color</STRONG> function only
 419        affects the current screen.   The  SVr4/XSI  interface  is  not  really
 420        designed  with  this  in mind, and historical implementations may use a
 421        single shared color palette.
 422
 423        Setting an implicit background color via  a  color  pair  affects  only
 424        character  cells  that  a character write operation explicitly touches.
 425        To change the background color used when parts of a window are  blanked
 426        by erasing or scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
 427
 428        Several  caveats  apply  on  older x86 machines (e.g., i386, i486) with
 429        VGA-compatible graphics:
 430
 431        <STRONG>o</STRONG>   COLOR_YELLOW is actually brown.  To get  yellow,  use  COLOR_YELLOW
 432            combined with the <STRONG>A_BOLD</STRONG> attribute.
 433
 434        <STRONG>o</STRONG>   The  A_BLINK  attribute should in theory cause the background to go
 435            bright.  This often fails to work, and even some cards for which it
 436            mostly  works  (such  as the Paradise and compatibles) do the wrong
 437            thing when you try to set a bright "yellow" background (you  get  a
 438            blinking yellow foreground instead).
 439
 440        <STRONG>o</STRONG>   Color RGB values are not settable.
 441
 442
 443 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 444        The  functions  marked as extensions were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and
 445        are not found in SVr4 curses, 4.4BSD  curses,  or  any  other  previous
 446        version of curses.
 447
 448
 449 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 450        This  implementation satisfies XSI Curses's minimum maximums for <STRONG>COLORS</STRONG>
 451        and <STRONG>COLOR_PAIRS</STRONG>.
 452
 453        The  <STRONG>init_pair</STRONG>  routine  accepts  negative  values  of  foreground  and
 454        background  color  to support the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG> extension, but
 455        only if that routine has been first invoked.
 456
 457        The assumption that <STRONG>COLOR_BLACK</STRONG> is the default background color for all
 458        terminals   can   be   modified   using  the  <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG>
 459        extension.
 460
 461        This implementation checks the pointers, e.g., for the values  returned
 462        by  <STRONG>color_content</STRONG>  and  <STRONG>pair_content</STRONG>,  and will treat those as optional
 463        parameters when null.
 464
 465        X/Open Curses does not specify a limit for the  number  of  colors  and
 466        color pairs which a terminal can support.  However, in its use of <STRONG>short</STRONG>
 467        for the parameters, it carries over SVr4's  implementation  detail  for
 468        the compiled terminfo database, which uses signed 16-bit numbers.  This
 469        implementation provides extended versions of those functions which  use
 470        <STRONG>short</STRONG>  parameters, allowing applications to use larger color- and pair-
 471        numbers.
 472
 473        The <STRONG>reset_color_pairs</STRONG> function is an extension of ncurses.
 474
 475
 476 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 477        SVr3.2 introduced color support to curses in 1987.
 478
 479        SVr4 made internal changes, e.g., moving  the  storage  for  the  color
 480        state  from  <STRONG>SP</STRONG>  (the  <STRONG>SCREEN</STRONG>  structure)  to  <STRONG>cur_term</STRONG>  (the  <STRONG>TERMINAL</STRONG>
 481        structure), but provided the same set of library functions.
 482
 483        SVr4 curses limits the number of color pairs  to  64,  reserving  color
 484        pair  zero  (0)  as the terminal's initial uncolored state.  This limit
 485        arises because the color pair information is a bitfield in  the  <STRONG>chtype</STRONG>
 486        data type (denoted by <STRONG>A_COLOR</STRONG>).
 487
 488        Other implementations of curses had different limits:
 489
 490        <STRONG>o</STRONG>   PCCurses (1987-1990) provided for only eight (8) colors.
 491
 492        <STRONG>o</STRONG>   PDCurses  (1992-present)  inherited  the  8-color  limitation  from
 493            PCCurses, but changed this to 256 in version 2.5 (2001), along with
 494            changing <STRONG>chtype</STRONG> from 16-bits to 32-bits.
 495
 496        <STRONG>o</STRONG>   X/Open Curses (1992-present) added a new structure <STRONG>cchar_t</STRONG> to store
 497            the character, attributes and color-pair values, allowing increased
 498            range  of  color-pairs.   Both  color-pairs and color-values used a
 499            signed <STRONG>short</STRONG>, limiting values to 15 bits.
 500
 501        <STRONG>o</STRONG>   ncurses (1992-present)  uses  eight  bits  for  <STRONG>A_COLOR</STRONG>  in  <STRONG>chtype</STRONG>
 502            values.
 503
 504            Version  5.3  provided  a wide-character interface (2002), but left
 505            color-pairs as part of the attributes-field.
 506
 507            Since version 6 (2015), ncurses uses a separate <STRONG>int</STRONG> for color-pairs
 508            in the <STRONG>cchar_t</STRONG> values.  When those color-pair values fit in 8 bits,
 509            ncurses allows color-pairs to  be  manipulated  via  the  functions
 510            using <STRONG>chtype</STRONG> values.
 511
 512        <STRONG>o</STRONG>   NetBSD  curses  used  6  bits  from  2000  (when  colors were first
 513            supported) until 2004.  At that point, NetBSD  changed  to  use  10
 514            bits.   As  of  2021,  that size is unchanged.  Like ncurses before
 515            version 6, the NetBSD  color-pair  information  is  stored  in  the
 516            attributes  field of <STRONG>cchar_t</STRONG>, limiting the number of color-pairs by
 517            the size of the bitfield.
 518
 519
 520 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 521        <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>,
 522        <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>
 523
 524
 525
 526 ncurses 6.4                       2023-11-25                    <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
 527 </PRE>
 528 <div class="nav">
 529 <ul>
 530 <li><a href="#h2-NAME">NAME</a></li>
 531 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 532 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 533 <ul>
 534 <li><a href="#h3-Overview">Overview</a></li>
 535 <li><a href="#h3-Color-Rendering">Color Rendering</a></li>
 536 </ul>
 537 </li>
 538 <li><a href="#h2-CONSTANTS">CONSTANTS</a></li>
 539 <li><a href="#h2-VARIABLES">VARIABLES</a>
 540 <ul>
 541 <li><a href="#h3-COLORS">COLORS</a></li>
 542 <li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li>
 543 </ul>
 544 </li>
 545 <li><a href="#h2-FUNCTIONS">FUNCTIONS</a>
 546 <ul>
 547 <li><a href="#h3-start_color">start_color</a></li>
 548 <li><a href="#h3-has_colors">has_colors</a></li>
 549 <li><a href="#h3-can_change_color">can_change_color</a></li>
 550 <li><a href="#h3-init_pair">init_pair</a></li>
 551 <li><a href="#h3-init_extended_pair">init_extended_pair</a></li>
 552 <li><a href="#h3-init_color">init_color</a></li>
 553 <li><a href="#h3-init_extended_color">init_extended_color</a></li>
 554 <li><a href="#h3-color_content">color_content</a></li>
 555 <li><a href="#h3-extended_color_content">extended_color_content</a></li>
 556 <li><a href="#h3-pair_content">pair_content</a></li>
 557 <li><a href="#h3-extended_pair_content">extended_pair_content</a></li>
 558 <li><a href="#h3-reset_color_pairs">reset_color_pairs</a></li>
 559 <li><a href="#h3-PAIR_NUMBER">PAIR_NUMBER</a></li>
 560 <li><a href="#h3-COLOR_PAIR">COLOR_PAIR</a></li>
 561 </ul>
 562 </li>
 563 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 564 <li><a href="#h2-NOTES">NOTES</a></li>
 565 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 566 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 567 <li><a href="#h2-HISTORY">HISTORY</a></li>
 568 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 569 </ul>
 570 </div>
 571 </BODY>
 572 </HTML>