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

   1 <!--
   2   ****************************************************************************
   3   * Copyright (c) 1998-2010,2015 Free Software Foundation, Inc.              *
   4   *                                                                          *
   5   * Permission is hereby granted, free of charge, to any person obtaining a  *
   6   * copy of this software and associated documentation files (the            *
   7   * "Software"), to deal in the Software without restriction, including      *
   8   * without limitation the rights to use, copy, modify, merge, publish,      *
   9   * distribute, distribute with modifications, sublicense, and/or sell       *
  10   * copies of the Software, and to permit persons to whom the Software is    *
  11   * furnished to do so, subject to the following conditions:                 *
  12   *                                                                          *
  13   * The above copyright notice and this permission notice shall be included  *
  14   * in all copies or substantial portions of the Software.                   *
  15   *                                                                          *
  16   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23   *                                                                          *
  24   * Except as contained in this notice, the name(s) of the above copyright   *
  25   * holders shall not be used in advertising or otherwise to promote the     *
  26   * sale, use or other dealings in this Software without prior written       *
  27   * authorization.                                                           *
  28   ****************************************************************************
  29   * @Id: curs_color.3x,v 1.37 2015/04/04 19:42:47 tom Exp @
  30 -->
  31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  32 <HTML>
  33 <HEAD>
  34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  35 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
  36 <TITLE>curs_color 3x</TITLE>
  37 <link rev=made href="mailto:bug-ncurses@gnu.org">
  38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  39 </HEAD>
  40 <BODY>
  41 <H1 class="no-header">curs_color 3x</H1>
  42 <PRE>
  43 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>                                           <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
  44
  45
  46
  47
  48 </PRE>
  49 <H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        <STRONG>start_color</STRONG>, <STRONG>init_pair</STRONG>, <STRONG>init_color</STRONG>, <STRONG>has_colors</STRONG>,
  51        <STRONG>can_change_color</STRONG>, <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>, <STRONG>COLOR_PAIR</STRONG>
  52        - <STRONG>curses</STRONG> color manipulation routines
  53
  54
  55 </PRE>
  56 <H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  57        <STRONG>#</STRONG> <STRONG>include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  58
  59        <STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
  60        <STRONG>int</STRONG> <STRONG>init_pair(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>f,</STRONG> <STRONG>short</STRONG> <STRONG>b);</STRONG>
  61        <STRONG>int</STRONG> <STRONG>init_color(short</STRONG> <STRONG>color,</STRONG> <STRONG>short</STRONG> <STRONG>r,</STRONG> <STRONG>short</STRONG> <STRONG>g,</STRONG> <STRONG>short</STRONG> <STRONG>b);</STRONG>
  62        <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
  63        <STRONG>bool</STRONG> <STRONG>can_change_color(void);</STRONG>
  64        <STRONG>int</STRONG>  <STRONG>color_content(short</STRONG>  <STRONG>color,</STRONG> <STRONG>short</STRONG> <STRONG>*r,</STRONG> <STRONG>short</STRONG> <STRONG>*g,</STRONG> <STRONG>short</STRONG>
  65        <STRONG>*b);</STRONG>
  66        <STRONG>int</STRONG> <STRONG>pair_content(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>*f,</STRONG> <STRONG>short</STRONG> <STRONG>*b);</STRONG>
  67
  68
  69 </PRE>
  70 <H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  71
  72 </PRE>
  73 <H3><a name="h3-Overview">Overview</a></H3><PRE>
  74        <STRONG>curses</STRONG> support color attributes on terminals with that ca-
  75        pability.   To  use  these  routines  <STRONG>start_color</STRONG>  must be
  76        called, usually right after <STRONG>initscr</STRONG>.   Colors  are  always
  77        used  in pairs (referred to as color-pairs).  A color-pair
  78        consists of a foreground  color  (for  characters)  and  a
  79        background color (for the blank field on which the charac-
  80        ters are displayed).  A programmer  initializes  a  color-
  81        pair  with  the routine <STRONG>init_pair</STRONG>.  After it has been ini-
  82        tialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>), a macro  defined  in  <STRONG>&lt;curses.h&gt;</STRONG>,
  83        can be used as a new video attribute.
  84
  85        If  a  terminal  is capable of redefining colors, the pro-
  86        grammer can use the routine <STRONG>init_color</STRONG> to change the defi-
  87        nition   of   a   color.    The  routines  <STRONG>has_colors</STRONG>  and
  88        <STRONG>can_change_color</STRONG>  return  <STRONG>TRUE</STRONG>  or  <STRONG>FALSE</STRONG>,  depending   on
  89        whether  the  terminal  has color capabilities and whether
  90        the programmer can change the colors.   The  routine  <STRONG>col-</STRONG>
  91        <STRONG>or_content</STRONG>  allows  a programmer to extract the amounts of
  92        red, green, and blue components in an  initialized  color.
  93        The  routine  <STRONG>pair_content</STRONG> allows a programmer to find out
  94        how a given color-pair is currently defined.
  95
  96
  97 </PRE>
  98 <H3><a name="h3-Routine-Descriptions">Routine Descriptions</a></H3><PRE>
  99        The <STRONG>start_color</STRONG> routine requires no arguments.  It must be
 100        called  if  the programmer wants to use colors, and before
 101        any other color manipulation routine  is  called.   It  is
 102        good  practice  to  call this routine right after <STRONG>initscr</STRONG>.
 103        <STRONG>start_color</STRONG> does this:
 104
 105        <STRONG>o</STRONG>   It initializes two global variables, <STRONG>COLORS</STRONG>  and  <STRONG>COL-</STRONG>
 106            <STRONG>OR_PAIRS</STRONG>  (respectively defining the maximum number of
 107            colors and color-pairs the terminal can support).
 108
 109        <STRONG>o</STRONG>   It initializes the special color pair <STRONG>0</STRONG> to the default
 110            foreground  and  background  colors.   No  other color
 111            pairs are initialized.
 112
 113        <STRONG>o</STRONG>   It restores the colors on the terminal to  the  values
 114            they had when the terminal was just turned on.
 115
 116        <STRONG>o</STRONG>   If  the terminal supports the <STRONG>initc</STRONG> (<STRONG>initialize_color</STRONG>)
 117            capability, <STRONG>start_color</STRONG> initializes its internal table
 118            representing the red, green and blue components of the
 119            color palette.
 120
 121            The components depend on whether the terminal uses CGA
 122            (aka "ANSI") or HLS (i.e., the <STRONG>hls</STRONG> (<STRONG>hue_lightness_sat-</STRONG>
 123            <STRONG>uration</STRONG>) capability is set).  The table is initialized
 124            first  for eight basic colors (black, red, green, yel-
 125            low, blue, magenta, cyan, and white), and  after  that
 126            (if  the terminal supports more than eight colors) the
 127            components are initialized to <STRONG>1000</STRONG>.
 128
 129            <STRONG>start_color</STRONG> does not attempt  to  set  the  terminal's
 130            color  palette to match its built-in table.  An appli-
 131            cation may use <STRONG>init_color</STRONG> to alter the internal  table
 132            along with the terminal's color.
 133
 134        These  limits apply to color values and color pairs.  Val-
 135        ues outside these limits are not legal, and may result  in
 136        a runtime error:
 137
 138        <STRONG>o</STRONG>   <STRONG>COLORS</STRONG> corresponds to the terminal database's <STRONG>max_col-</STRONG>
 139            <STRONG>ors</STRONG> capability, which is typically a signed 16-bit in-
 140            teger (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 141
 142        <STRONG>o</STRONG>   color values are expected to be in the range <STRONG>0</STRONG> to <STRONG>COL-</STRONG>
 143            <STRONG>ORS-1</STRONG>, inclusive (including <STRONG>0</STRONG> and <STRONG>COLORS-1</STRONG>).
 144
 145        <STRONG>o</STRONG>   a special color value <STRONG>-1</STRONG> is used in  certain  extended
 146            functions  to  denote  the  <EM>default</EM> <EM>color</EM> (see <STRONG>use_de-</STRONG>
 147            <STRONG>fault_colors</STRONG>).
 148
 149        <STRONG>o</STRONG>   <STRONG>COLOR_PAIRS</STRONG> corresponds  to  the  terminal  database's
 150            <STRONG>max_pairs</STRONG>  capability,  which  is  typically  a signed
 151            16-bit integer (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 152
 153        <STRONG>o</STRONG>   legal color pair values are in the  range  <STRONG>1</STRONG>  to  <STRONG>COL-</STRONG>
 154            <STRONG>OR_PAIRS-1</STRONG>, inclusive.
 155
 156        <STRONG>o</STRONG>   color pair <STRONG>0</STRONG> is special; it denotes "no color".
 157
 158            Color  pair  <STRONG>0</STRONG> is assumed to be white on black, but is
 159            actually whatever the terminal implements before color
 160            is initialized.  It cannot be modified by the applica-
 161            tion.
 162
 163        The <STRONG>init_pair</STRONG> routine changes the definition of  a  color-
 164        pair.   It takes three arguments: the number of the color-
 165        pair to be changed, the foreground color number,  and  the
 166        background color number.  For portable applications:
 167
 168        <STRONG>o</STRONG>   The  first  argument must be a legal color pair value.
 169            If default colors are  used  (see  <STRONG>use_default_colors</STRONG>)
 170            the  upper  limit is adjusted to allow for extra pairs
 171            which use a default color in foreground  and/or  back-
 172            ground.
 173
 174        <STRONG>o</STRONG>   The  second  and  third  arguments must be legal color
 175            values.
 176
 177        If the color-pair was previously initialized,  the  screen
 178        is  refreshed  and  all occurrences of that color-pair are
 179        changed to the new definition.
 180
 181        As an extension, ncurses allows you to set  color  pair  <STRONG>0</STRONG>
 182        via  the  <STRONG>assume_default_colors</STRONG> routine, or to specify the
 183        use of default colors (color number <STRONG>-1</STRONG>) if you  first  in-
 184        voke the <STRONG>use_default_colors</STRONG> routine.
 185
 186        The  <STRONG>init_color</STRONG> routine changes the definition of a color.
 187        It takes four arguments: the number of  the  color  to  be
 188        changed  followed  by three RGB values (for the amounts of
 189        red, green, and blue components).  The first argument must
 190        be  a  legal  color  value; default colors are not allowed
 191        here.  (See the section <STRONG>Colors</STRONG> for the default  color  in-
 192        dex.)  Each of the last three arguments must be a value in
 193        the range <STRONG>0</STRONG> through <STRONG>1000</STRONG>.  When <STRONG>init_color</STRONG>  is  used,  all
 194        occurrences of that color on the screen immediately change
 195        to the new definition.
 196
 197        The <STRONG>has_colors</STRONG> routine requires no arguments.  It  returns
 198        <STRONG>TRUE</STRONG>  if the terminal can manipulate colors; otherwise, it
 199        returns <STRONG>FALSE</STRONG>.  This routine facilitates writing terminal-
 200        independent  programs.   For example, a programmer can use
 201        it to decide whether to use color or some other video  at-
 202        tribute.
 203
 204        The  <STRONG>can_change_color</STRONG>  routine  requires no arguments.  It
 205        returns <STRONG>TRUE</STRONG> if  the  terminal  supports  colors  and  can
 206        change  their  definitions; other, it returns <STRONG>FALSE</STRONG>.  This
 207        routine facilitates writing terminal-independent programs.
 208
 209        The <STRONG>color_content</STRONG> routine gives programmers a way to  find
 210        the intensity of the red, green, and blue (RGB) components
 211        in a color.  It requires four arguments: the color number,
 212        and  three addresses of <STRONG>short</STRONG>s for storing the information
 213        about the amounts of red, green, and  blue  components  in
 214        the given color.  The first argument must be a legal color
 215        value, i.e., <STRONG>0</STRONG> through <STRONG>COLORS-1</STRONG>,  inclusive.   The  values
 216        that  are  stored  at the addresses pointed to by the last
 217        three arguments are in the range <STRONG>0</STRONG> (no component)  through
 218        <STRONG>1000</STRONG> (maximum amount of component), inclusive.
 219
 220        The  <STRONG>pair_content</STRONG>  routine  allows programmers to find out
 221        what colors a given color-pair consists of.   It  requires
 222        three  arguments: the color-pair number, and two addresses
 223        of <STRONG>short</STRONG>s for storing the foreground  and  the  background
 224        color  numbers.   The first argument must be a legal color
 225        value, i.e., in the range <STRONG>1</STRONG> through <STRONG>COLOR_PAIRS-1</STRONG>,  inclu-
 226        sive.  The values that are stored at the addresses pointed
 227        to by the second and third arguments are in  the  range  <STRONG>0</STRONG>
 228        through <STRONG>COLORS</STRONG>, inclusive.
 229
 230
 231 </PRE>
 232 <H3><a name="h3-Colors">Colors</a></H3><PRE>
 233        In <STRONG>&lt;curses.h&gt;</STRONG> the following macros are defined.  These are
 234        the default colors.  <STRONG>curses</STRONG> also assumes that  <STRONG>COLOR_BLACK</STRONG>
 235        is the default background color for all terminals.
 236
 237              <STRONG>COLOR_BLACK</STRONG>
 238              <STRONG>COLOR_RED</STRONG>
 239              <STRONG>COLOR_GREEN</STRONG>
 240              <STRONG>COLOR_YELLOW</STRONG>
 241              <STRONG>COLOR_BLUE</STRONG>
 242              <STRONG>COLOR_MAGENTA</STRONG>
 243              <STRONG>COLOR_CYAN</STRONG>
 244              <STRONG>COLOR_WHITE</STRONG>
 245
 246
 247 </PRE>
 248 <H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 249        The  routines  <STRONG>can_change_color()</STRONG>  and <STRONG>has_colors()</STRONG> return
 250        <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
 251
 252        All other routines return the integer <STRONG>ERR</STRONG> upon failure and
 253        an  <STRONG>OK</STRONG>  (SVr4  specifies only "an integer value other than
 254        <STRONG>ERR</STRONG>") upon successful completion.
 255
 256        X/Open defines no error conditions.   This  implementation
 257        will  return  <STRONG>ERR</STRONG>  on attempts to use color values outside
 258        the range <STRONG>0</STRONG> to COLORS-1 (except for the default colors ex-
 259        tension),  or  use color pairs outside the range <STRONG>0</STRONG> to <STRONG>COL-</STRONG>
 260        <STRONG>OR_PAIRS-1</STRONG>.  Color values used in <STRONG>init_color</STRONG>  must  be  in
 261        the  range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.  An error is returned from all func-
 262        tions if the terminal has not been initialized.  An  error
 263        is  returned from secondary functions such as <STRONG>init_pair</STRONG> if
 264        <STRONG>start_color</STRONG> was not called.
 265
 266           <STRONG>init_color</STRONG>
 267                returns an error if the terminal does not  support
 268                this  feature, e.g., if the <EM>initialize</EM><STRONG>_</STRONG><EM>color</EM> capa-
 269                bility is absent from the terminal description.
 270
 271           <STRONG>start_color</STRONG>
 272                returns an error if the color table cannot be  al-
 273                located.
 274
 275
 276 </PRE>
 277 <H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 278        In  the  <EM>ncurses</EM> implementation, there is a separate color
 279        activation flag, color palette, color pairs table, and as-
 280        sociated  COLORS  and  COLOR_PAIRS counts for each screen;
 281        the <STRONG>start_color</STRONG> function only affects the current  screen.
 282        The SVr4/XSI interface is not really designed with this in
 283        mind, and historical  implementations  may  use  a  single
 284        shared color palette.
 285
 286        Note that setting an implicit background color via a color
 287        pair affects only character cells that a  character  write
 288        operation  explicitly  touches.   To change the background
 289        color used when parts of a window are blanked  by  erasing
 290        or scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
 291
 292        Several  caveats  apply  on 386 and 486 machines with VGA-
 293        compatible graphics:
 294
 295        <STRONG>o</STRONG>   COLOR_YELLOW is actually brown.  To  get  yellow,  use
 296            COLOR_YELLOW combined with the <STRONG>A_BOLD</STRONG> attribute.
 297
 298        <STRONG>o</STRONG>   The A_BLINK attribute should in theory cause the back-
 299            ground to go bright.  This often fails  to  work,  and
 300            even some cards for which it mostly works (such as the
 301            Paradise and compatibles) do the wrong thing when  you
 302            try  to  set  a  bright "yellow" background (you get a
 303            blinking yellow foreground instead).
 304
 305        <STRONG>o</STRONG>   Color RGB values are not settable.
 306
 307
 308 </PRE>
 309 <H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 310        This implementation satisfies XSI Curses's  minimum  maxi-
 311        mums for <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG>.
 312
 313        The  <STRONG>init_pair</STRONG>  routine  accepts  negative values of fore-
 314        ground  and  background  color  to  support  the   <STRONG>use_de-</STRONG>
 315        <STRONG>fault_colors</STRONG>  extension, but only if that routine has been
 316        first invoked.
 317
 318        The assumption that <STRONG>COLOR_BLACK</STRONG> is the default  background
 319        color  for  all  terminals  can  be modified using the <STRONG>as-</STRONG>
 320        <STRONG>sume_default_colors</STRONG> extension.
 321
 322        This implementation checks the  pointers,  e.g.,  for  the
 323        values  returned  by  <STRONG>color_content</STRONG>  and <STRONG>pair_content</STRONG>, and
 324        will treat those as optional parameters when null.
 325
 326
 327 </PRE>
 328 <H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 329        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,  <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,  <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>,  <STRONG>curs_vari-</STRONG>
 330        <STRONG><A HREF="curs_variables.3x.html">ables(3x)</A></STRONG>, <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>
 331
 332
 333
 334                                                          <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
 335 </PRE>
 336 <div class="nav">
 337 <ul>
 338 <li><a href="#h2-NAME">NAME</a></li>
 339 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 340 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 341 <ul>
 342 <li><a href="#h3-Overview">Overview</a></li>
 343 <li><a href="#h3-Routine-Descriptions">Routine Descriptions</a></li>
 344 <li><a href="#h3-Colors">Colors</a></li>
 345 </ul>
 346 </li>
 347 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 348 <li><a href="#h2-NOTES">NOTES</a></li>
 349 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 350 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 351 </ul>
 352 </div>
 353 </BODY>
 354 </HTML>