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

   1 <HTML>
   2 <BODY>
   3 <PRE>
   4 <!-- Manpage converted by man2html 3.0.1 -->
   5
   6 </PRE>
   7 <H2>NAME</H2><PRE>
   8        <B>start_color</B>,     <B>init_pair</B>,     <B>init_color</B>,    <B>has_colors</B>,
   9        <B>can_change_color</B>, <B>color_content</B>, <B>pair_content</B>,  <B>COLOR_PAIR</B>
  10        - <B>curses</B> color manipulation routines
  11
  12
  13 </PRE>
  14 <H2>SYNOPSIS</H2><PRE>
  15        <B>#</B> <B>include</B> <B>&lt;curses.h&gt;</B>
  16        <B>int</B> <B>start_color(void);</B>
  17        <B>int</B> <B>init_pair(short</B> <B>pair,</B> <B>short</B> <B>f,</B> <B>short</B> <B>b);</B>
  18        <B>int</B> <B>init_color(short</B> <B>color,</B> <B>short</B> <B>r,</B> <B>short</B> <B>g,</B> <B>short</B> <B>b);</B>
  19        <B>bool</B> <B>has_colors(void);</B>
  20        <B>bool</B> <B>can_change_color(void);</B>
  21        <B>int</B>  <B>color_content(short</B>  <B>color,</B> <B>short</B> <B>*r,</B> <B>short</B> <B>*g,</B> <B>short</B>
  22        <B>*b);</B>
  23        <B>int</B> <B>pair_content(short</B> <B>pair,</B> <B>short</B> <B>*f,</B> <B>short</B> <B>*b);</B>
  24
  25
  26 </PRE>
  27 <H2>DESCRIPTION</H2><PRE>
  28    <B>Overview</B>
  29        <B>curses</B> support color attributes  on  terminals  with  that
  30        capability.   To  use  these  routines <B>start_color</B> must be
  31        called, usually right after <B>initscr</B>.   Colors  are  always
  32        used  in pairs (referred to as color-pairs).  A color-pair
  33        consists of a foreground  color  (for  characters)  and  a
  34        background color (for the blank field on which the charac-
  35        ters are displayed).  A programmer  initializes  a  color-
  36        pair  with  the routine <B>init_pair</B>.  After it has been ini-
  37        tialized, <B>COLOR_PAIR</B>(<I>n</I>), a macro  defined  in  <B>&lt;curses.h&gt;</B>,
  38        can be used as a new video attribute.
  39
  40        If  a  terminal  is capable of redefining colors, the pro-
  41        grammer can use the routine <B>init_color</B> to change the defi-
  42        nition   of   a   color.    The  routines  <B>has_colors</B>  and
  43        <B>can_change_color</B>  return  <B>TRUE</B>  or  <B>FALSE</B>,  depending   on
  44        whether  the  terminal  has color capabilities and whether
  45        the  programmer  can  change  the  colors.   The   routine
  46        <B>color_content</B>  allows  a programmer to extract the amounts
  47        of red, green,  and  blue  components  in  an  initialized
  48        color.   The  routine  <B>pair_content</B> allows a programmer to
  49        find out how a given color-pair is currently defined.
  50
  51    <B>Routine</B> <B>Descriptions</B>
  52        The <B>start_color</B> routine requires no arguments.  It must be
  53        called  if  the programmer wants to use colors, and before
  54        any other color manipulation routine  is  called.   It  is
  55        good  practice  to  call this routine right after <B>initscr</B>.
  56        <B>start_color</B> initializes eight basic  colors  (black,  red,
  57        green,  yellow,  blue,  magenta, cyan, and white), and two
  58        global variables,  <B>COLORS</B>  and  <B>COLOR_PAIRS</B>  (respectively
  59        defining  the maximum number of colors and color-pairs the
  60        terminal can support).  It also restores the colors on the
  61        terminal to the values they had when the terminal was just
  62        turned on.
  63
  64        The <B>init_pair</B> routine changes the definition of  a  color-
  65        pair.   It takes three arguments: the number of the color-
  66        pair to be changed, the foreground color number,  and  the
  67        background color number.  For portable applications:
  68
  69        -    The value of the first argument must be between <B>1</B> and
  70             <B>COLOR_PAIRS-1</B>.
  71
  72        -    The value of the second and third arguments  must  be
  73             between  0  and  <B>COLORS</B> (the 0 color pair is wired to
  74             white on black and cannot be changed).
  75
  76        If the color-pair was previously initialized,  the  screen
  77        is  refreshed  and  all  occurrences of that color-pair is
  78        changed to the new definition.
  79
  80        As an extension, ncurses allows you to set  color  pair  0
  81        via  the  <B>assume_default_colors</B> routine, or to specify the
  82        use of default colors  (color  number  <B>-1</B>)  if  you  first
  83        invoke the <B>use_default_colors</B> routine.
  84
  85        The  <B>init_color</B> routine changes the definition of a color.
  86        It takes four arguments: the number of  the  color  to  be
  87        changed  followed  by three RGB values (for the amounts of
  88        red, green, and blue components).  The value of the  first
  89        argument  must  be between <B>0</B> and <B>COLORS</B>.  (See the section
  90        <B>Colors</B> for the default color index.)   Each  of  the  last
  91        three  arguments must be a value between 0 and 1000.  When
  92        <B>init_color</B> is used, all occurrences of that color  on  the
  93        screen immediately change to the new definition.
  94
  95        The  <B>has_colors</B> routine requires no arguments.  It returns
  96        <B>TRUE</B> if the terminal can manipulate colors; otherwise,  it
  97        returns <B>FALSE</B>.  This routine facilitates writing terminal-
  98        independent programs.  For example, a programmer  can  use
  99        it  to  decide  whether  to  use color or some other video
 100        attribute.
 101
 102        The <B>can_change_color</B> routine requires  no  arguments.   It
 103        returns  <B>TRUE</B>  if  the  terminal  supports  colors and can
 104        change their definitions; other, it returns  <B>FALSE</B>.   This
 105        routine facilitates writing terminal-independent programs.
 106
 107        The <B>color_content</B> routine gives programmers a way to  find
 108        the intensity of the red, green, and blue (RGB) components
 109        in a color.  It requires four arguments: the color number,
 110        and  three addresses of <B>short</B>s for storing the information
 111        about the amounts of red, green, and  blue  components  in
 112        the  given color.  The value of the first argument must be
 113        between 0 and <B>COLORS</B>.  The values that are stored  at  the
 114        addresses  pointed  to  by  the  last  three arguments are
 115        between 0 (no component) and 1000 (maximum amount of  com-
 116        ponent).
 117
 118        The  <B>pair_content</B>  routine  allows programmers to find out
 119        what colors a given color-pair consists of.   It  requires
 120        three  arguments: the color-pair number, and two addresses
 121        of <B>short</B>s for storing the foreground  and  the  background
 122        color  numbers.   The  value of the first argument must be
 123        between 1 and <B>COLOR_PAIRS-1</B>.  The values that  are  stored
 124        at  the addresses pointed to by the second and third argu-
 125        ments are between 0 and <B>COLORS</B>.
 126
 127    <B>Colors</B>
 128        In <B>&lt;curses.h&gt;</B> the following macros are defined.  These are
 129        the  default colors.  <B>curses</B> also assumes that <B>COLOR_BLACK</B>
 130        is the default background color for all terminals.
 131
 132              <B>COLOR_BLACK</B>
 133              <B>COLOR_RED</B>
 134              <B>COLOR_GREEN</B>
 135              <B>COLOR_YELLOW</B>
 136              <B>COLOR_BLUE</B>
 137              <B>COLOR_MAGENTA</B>
 138              <B>COLOR_CYAN</B>
 139              <B>COLOR_WHITE</B>
 140
 141
 142 </PRE>
 143 <H2>RETURN VALUE</H2><PRE>
 144        The routines <B>can_change_color()</B>  and  <B>has_colors()</B>  return
 145        <B>TRUE</B> or <B>FALSE</B>.
 146
 147        All other routines return the integer <B>ERR</B> upon failure and
 148        an <B>OK</B> (SVr4 specifies only "an integer  value  other  than
 149        <B>ERR</B>") upon successful completion.
 150
 151
 152 </PRE>
 153 <H2>NOTES</H2><PRE>
 154        In  the  <I>ncurses</I> implementation, there is a separate color
 155        activation flag, color palette,  color  pairs  table,  and
 156        associated  COLORS and COLOR_PAIRS counts for each screen;
 157        the <B>start_color</B> function only affects the current  screen.
 158        The SVr4/XSI interface is not really designed with this in
 159        mind, and historical  implementations  may  use  a  single
 160        shared color palette.
 161
 162        Note that setting an implicit background color via a color
 163        pair affects only character cells that a  character  write
 164        operation  explicitly  touches.   To change the background
 165        color used when parts of a window are blanked  by  erasing
 166        or scrolling operations, see <B><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></B>.
 167
 168        Several  caveats  apply  on 386 and 486 machines with VGA-
 169        compatible graphics:
 170
 171        -    COLOR_YELLOW is actually brown.  To get  yellow,  use
 172             COLOR_YELLOW combined with the <B>A_BOLD</B> attribute.
 173
 174        -    The  A_BLINK  attribute  should  in  theory cause the
 175             background to go bright.  This often fails  to  work,
 176             and  even  some cards for which it mostly works (such
 177             as the Paradise and compatibles) do the  wrong  thing
 178             when you try to set a bright "yellow" background (you
 179             get a blinking yellow foreground instead).
 180
 181        -    Color RGB values are not settable.
 182
 183
 184 </PRE>
 185 <H2>PORTABILITY</H2><PRE>
 186        This implementation satisfies XSI Curses's  minimum  maxi-
 187        mums for <B>COLORS</B> and <B>COLOR_PAIRS</B>.
 188
 189        The  <B>init_pair</B>  routine  accepts  negative values of fore-
 190        ground   and   background    color    to    support    the
 191        <B>use_default_colors</B> extension, but only if that routine has
 192        been first invoked.
 193
 194        The assumption that <B>COLOR_BLACK</B> is the default  background
 195        color   for  all  terminals  can  be  modified  using  the
 196        <B>assume_default_colors</B> extension,
 197
 198
 199 </PRE>
 200 <H2>SEE ALSO</H2><PRE>
 201        <B><A HREF="ncurses.3x.html">curses(3x)</A></B>, <B><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></B>, <B><A HREF="curs_attr.3x.html">curs_attr(3x)</A></B>, <B><A HREF="dft_fgbg.3x.html">dft_fgbg(3x)</A></B>
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235 </PRE>
 236 <HR>
 237 <ADDRESS>
 238 Man(1) output converted with
 239 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 240 </ADDRESS>
 241 </BODY>
 242 </HTML>