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

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