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

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
   2 <!--
   3   ****************************************************************************
   4   * Copyright (c) 1998-2004,2005 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.27 2005/05/15 16:55:36 tom Exp @
  31 -->
  32 <HTML>
  33 <HEAD>
  34 <TITLE>curs_color 3x</TITLE>
  35 <link rev=made href="mailto:bug-ncurses@gnu.org">
  36 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  37 </HEAD>
  38 <BODY>
  39 <H1>curs_color 3x</H1>
  40 <HR>
  41 <PRE>
  42 <!-- Manpage converted by man2html 3.0.1 -->
  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>NAME</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>SYNOPSIS</H2><PRE>
  57        <STRONG>#</STRONG> <STRONG>include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  58        <STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
  59        <STRONG>int</STRONG> <STRONG>init_pair(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>f,</STRONG> <STRONG>short</STRONG> <STRONG>b);</STRONG>
  60        <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>
  61        <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
  62        <STRONG>bool</STRONG> <STRONG>can_change_color(void);</STRONG>
  63        <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>
  64        <STRONG>*b);</STRONG>
  65        <STRONG>int</STRONG> <STRONG>pair_content(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>*f,</STRONG> <STRONG>short</STRONG> <STRONG>*b);</STRONG>
  66
  67
  68 </PRE>
  69 <H2>DESCRIPTION</H2><PRE>
  70    <STRONG>Overview</STRONG>
  71        <STRONG>curses</STRONG> support color attributes on terminals with that ca-
  72        pability.   To  use  these  routines  <STRONG>start_color</STRONG>  must be
  73        called, usually right after <STRONG>initscr</STRONG>.   Colors  are  always
  74        used  in pairs (referred to as color-pairs).  A color-pair
  75        consists of a foreground  color  (for  characters)  and  a
  76        background color (for the blank field on which the charac-
  77        ters are displayed).  A programmer  initializes  a  color-
  78        pair  with  the routine <STRONG>init_pair</STRONG>.  After it has been ini-
  79        tialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>), a macro  defined  in  <STRONG>&lt;curses.h&gt;</STRONG>,
  80        can  be  used  as a new video attribute.  If a terminal is
  81        capable of redefining colors, the programmer can  use  the
  82        routine  <STRONG>init_color</STRONG>  to  change the definition of a color.
  83        The routines <STRONG>has_colors</STRONG> and <STRONG>can_change_color</STRONG>  return  <STRONG>TRUE</STRONG>
  84        or  <STRONG>FALSE</STRONG>, depending on whether the terminal has color ca-
  85        pabilities and whether the programmer can change the  col-
  86        ors.  The routine <STRONG>color_content</STRONG> allows a programmer to ex-
  87        tract the amounts of red, green, and blue components in an
  88        initialized color.  The routine <STRONG>pair_content</STRONG> allows a pro-
  89        grammer to find out how a given  color-pair  is  currently
  90        defined.
  91
  92    <STRONG>Routine</STRONG> <STRONG>Descriptions</STRONG>
  93        The <STRONG>start_color</STRONG> routine requires no arguments.  It must be
  94        called if the programmer wants to use colors,  and  before
  95        any  other  color  manipulation  routine is called.  It is
  96        good practice to call this routine  right  after  <STRONG>initscr</STRONG>.
  97        <STRONG>start_color</STRONG>  initializes  eight  basic colors (black, red,
  98        green, yellow, blue, magenta, cyan, and  white),  and  two
  99        global  variables,  <STRONG>COLORS</STRONG>  and  <STRONG>COLOR_PAIRS</STRONG> (respectively
 100        defining the maximum number of colors and color-pairs  the
 101        terminal can support).  It also restores the colors on the
 102        terminal to the values they had when the terminal was just
 103        turned  on.   The <STRONG>init_pair</STRONG> routine changes the definition
 104        of a color-pair.  It takes three arguments: the number  of
 105        the color-pair to be changed, the foreground color number,
 106        and the background color number.   For  portable  applica-
 107        tions:
 108
 109        -    The value of the first argument must be between <STRONG>1</STRONG> and
 110             <STRONG>COLOR_PAIRS-1</STRONG>.
 111
 112        -    The value of the second and third arguments  must  be
 113             between  0 and <STRONG>COLORS</STRONG>.  Color pair 0 is assumed to be
 114             white on black, but is actually whatever the terminal
 115             implements before color is initialized.  It cannot be
 116             modified by the application.
 117
 118        If the color-pair was previously initialized,  the  screen
 119        is  refreshed  and  all occurrences of that color-pair are
 120        changed to the new definition.  As an  extension,  ncurses
 121        allows you to set color pair 0 via the <STRONG>assume_default_col-</STRONG>
 122        <STRONG>ors</STRONG> routine, or to specify the use of default colors (col-
 123        or  number  <STRONG>-1</STRONG>) if you first invoke the <STRONG>use_default_colors</STRONG>
 124        routine.  The <STRONG>init_color</STRONG> routine changes the definition of
 125        a color.  It takes four arguments: the number of the color
 126        to be changed  followed  by  three  RGB  values  (for  the
 127        amounts of red, green, and blue components).  The value of
 128        the first argument must be between <STRONG>0</STRONG> and <STRONG>COLORS</STRONG>.  (See the
 129        section  <STRONG>Colors</STRONG> for the default color index.)  Each of the
 130        last three arguments must be a value between 0  and  1000.
 131        When  <STRONG>init_color</STRONG> is used, all occurrences of that color on
 132        the screen immediately change to the new definition.   The
 133        <STRONG>has_colors</STRONG> routine requires no arguments.  It returns <STRONG>TRUE</STRONG>
 134        if the terminal can manipulate colors; otherwise,  it  re-
 135        turns  <STRONG>FALSE</STRONG>.   This routine facilitates writing terminal-
 136        independent programs.  For example, a programmer  can  use
 137        it  to decide whether to use color or some other video at-
 138        tribute.  The <STRONG>can_change_color</STRONG> routine requires  no  argu-
 139        ments.   It  returns  <STRONG>TRUE</STRONG> if the terminal supports colors
 140        and can change their definitions; other, it returns <STRONG>FALSE</STRONG>.
 141        This routine facilitates writing terminal-independent pro-
 142        grams.  The <STRONG>color_content</STRONG> routine gives programmers a  way
 143        to  find  the  intensity of the red, green, and blue (RGB)
 144        components in a color.  It requires  four  arguments:  the
 145        color  number,  and  three addresses of <STRONG>short</STRONG>s for storing
 146        the information about the amounts of red, green, and  blue
 147        components in the given color.  The value of the first ar-
 148        gument must be between 0 and <STRONG>COLORS</STRONG>.  The values that  are
 149        stored at the addresses pointed to by the last three argu-
 150        ments are between  0  (no  component)  and  1000  (maximum
 151        amount  of  component).   The  <STRONG>pair_content</STRONG> routine allows
 152        programmers to find out what  colors  a  given  color-pair
 153        consists  of.  It requires three arguments: the color-pair
 154        number, and two addresses of <STRONG>short</STRONG>s for storing the  fore-
 155        ground and the background color numbers.  The value of the
 156        first argument must be between 1 and  <STRONG>COLOR_PAIRS-1</STRONG>.   The
 157        values  that are stored at the addresses pointed to by the
 158        second and third arguments are between 0 and <STRONG>COLORS</STRONG>.
 159
 160    <STRONG>Colors</STRONG>
 161        In <STRONG>&lt;curses.h&gt;</STRONG> the following macros are defined.  These are
 162        the  default colors.  <STRONG>curses</STRONG> also assumes that <STRONG>COLOR_BLACK</STRONG>
 163        is the default background color for all terminals.
 164              <STRONG>COLOR_BLACK</STRONG>
 165              <STRONG>COLOR_RED</STRONG>
 166              <STRONG>COLOR_GREEN</STRONG>
 167              <STRONG>COLOR_YELLOW</STRONG>
 168              <STRONG>COLOR_BLUE</STRONG>
 169              <STRONG>COLOR_MAGENTA</STRONG>
 170              <STRONG>COLOR_CYAN</STRONG>
 171              <STRONG>COLOR_WHITE</STRONG>
 172
 173
 174 </PRE>
 175 <H2>RETURN VALUE</H2><PRE>
 176        The routines <STRONG>can_change_color()</STRONG>  and  <STRONG>has_colors()</STRONG>  return
 177        <STRONG>TRUE</STRONG>  or <STRONG>FALSE</STRONG>.  All other routines return the integer <STRONG>ERR</STRONG>
 178        upon failure and an <STRONG>OK</STRONG> (SVr4 specifies  only  "an  integer
 179        value other than <STRONG>ERR</STRONG>") upon successful completion.
 180
 181        X/Open  defines  no error conditions.  This implementation
 182        will return <STRONG>ERR</STRONG> on attempts to use  color  values  outside
 183        the range 0 to COLORS-1 (except for the default colors ex-
 184        tension), or use color pairs outside the range 0  to  COL-
 185        OR_PAIR-1.  Color values used in <STRONG>init_color</STRONG> must be in the
 186        range 0 to 1000.  An error is returned from all  functions
 187        if the terminal has not been initialized.  An error is re-
 188        turned from  secondary  functions  such  as  <STRONG>init_pair</STRONG>  if
 189        <STRONG>start_color</STRONG> was not called.
 190
 191               <STRONG>init_color</STRONG>
 192                    returns an error if the terminal does not sup-
 193                    port  this  feature,  e.g.,  if  the  <EM>initial-</EM>
 194                    <EM>ize</EM><STRONG>_</STRONG><EM>color</EM> capability is absent from the termi-
 195                    nal description.
 196
 197               <STRONG>start_color</STRONG>
 198                    returns an error If the color table cannot  be
 199                    allocated.
 200
 201
 202 </PRE>
 203 <H2>NOTES</H2><PRE>
 204        In  the  <EM>ncurses</EM> implementation, there is a separate color
 205        activation flag, color palette, color pairs table, and as-
 206        sociated  COLORS  and  COLOR_PAIRS counts for each screen;
 207        the <STRONG>start_color</STRONG> function only affects the current  screen.
 208        The SVr4/XSI interface is not really designed with this in
 209        mind, and historical  implementations  may  use  a  single
 210        shared color palette.  Note that setting an implicit back-
 211        ground color via a color pair affects only character cells
 212        that  a  character write operation explicitly touches.  To
 213        change the background color used when parts  of  a  window
 214        are  blanked  by  erasing  or  scrolling  operations,  see
 215        <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.  Several caveats apply on 386 and  486  ma-
 216        chines with VGA-compatible graphics:
 217
 218        -    COLOR_YELLOW  is  actually brown.  To get yellow, use
 219             COLOR_YELLOW combined with the <STRONG>A_BOLD</STRONG> attribute.
 220
 221        -    The A_BLINK attribute  should  in  theory  cause  the
 222             background  to  go bright.  This often fails to work,
 223             and even some cards for which it mostly  works  (such
 224             as  the  Paradise and compatibles) do the wrong thing
 225             when you try to set a bright "yellow" background (you
 226             get a blinking yellow foreground instead).
 227
 228        -    Color RGB values are not settable.
 229
 230
 231 </PRE>
 232 <H2>PORTABILITY</H2><PRE>
 233        This  implementation  satisfies XSI Curses's minimum maxi-
 234        mums for <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG>.
 235
 236        The <STRONG>init_pair</STRONG> routine accepts  negative  values  of  fore-
 237        ground   and  background  color  to  support  the  <STRONG>use_de-</STRONG>
 238        <STRONG>fault_colors</STRONG> extension, but only if that routine has  been
 239        first invoked.
 240
 241        The  assumption that <STRONG>COLOR_BLACK</STRONG> is the default background
 242        color for all terminals can  be  modified  using  the  <STRONG>as-</STRONG>
 243        <STRONG>sume_default_colors</STRONG> extension.
 244
 245        This  implementation  checks  the  pointers, e.g., for the
 246        values returned by  <STRONG>color_content</STRONG>  and  <STRONG>pair_content</STRONG>,  and
 247        will treat those as optional parameters when null.
 248
 249
 250 </PRE>
 251 <H2>SEE ALSO</H2><PRE>
 252        <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>default_col-</STRONG>
 253        <STRONG><A HREF="default_colors.3x.html">ors(3x)</A></STRONG>
 254
 255
 256
 257                                                          <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
 258 </PRE>
 259 <HR>
 260 <ADDRESS>
 261 Man(1) output converted with
 262 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 263 </ADDRESS>
 264 </BODY>
 265 </HTML>