# curs_color 3x

    curs_color(3x)                                           curs_color(3x)

## NAME

           start_color, init_pair, init_color, has_colors,
           can_change_color, color_content, pair_content, COLOR_PAIR
           - curses color manipulation routines

## SYNOPSIS

           # include <curses.h>
           int start_color(void);
           int init_pair(short pair, short f, short b);
           int init_color(short color, short r, short g, short b);
           bool has_colors(void);
           bool can_change_color(void);
           int  color_content(short  color, short *r, short *g, short
           *b);
           int pair_content(short pair, short *f, short *b);

## DESCRIPTION

       Overview
           curses support color attributes on terminals with that ca-
           pability.   To  use  these  routines  start_color  must be
           called, usually right after initscr.   Colors  are  always
           used  in pairs (referred to as color-pairs).  A color-pair
           consists of a foreground  color  (for  characters)  and  a
           background color (for the blank field on which the charac-
           ters are displayed).  A programmer  initializes  a  color-
           pair  with  the routine init_pair.  After it has been ini-
           tialized, COLOR_PAIR(n), a macro  defined  in  <curses.h>,
           can  be  used  as a new video attribute.  If a terminal is
           capable of redefining colors, the programmer can  use  the
           routine  init_color  to  change the definition of a color.
           The routines has_colors and can_change_color  return  TRUE
           or  FALSE, depending on whether the terminal has color ca-
           pabilities and whether the programmer can change the  col-
           ors.  The routine color_content allows a programmer to ex-
           tract the amounts of red, green, and blue components in an
           initialized color.  The routine pair_content allows a pro-
           grammer to find out how a given  color-pair  is  currently
           defined.

       Routine Descriptions
           The start_color routine requires no arguments.  It must be
           called if the programmer wants to use colors,  and  before
           any  other  color  manipulation  routine is called.  It is
           good practice to call this routine  right  after  initscr.
           start_color  initializes  eight  basic colors (black, red,
           green, yellow, blue, magenta, cyan, and  white),  and  two
           global  variables,  COLORS  and  COLOR_PAIRS (respectively
           defining the maximum number of colors and color-pairs  the
           terminal can support).  It also restores the colors on the
           terminal to the values they had when the terminal was just
           turned  on.   The init_pair routine changes the definition
           of a color-pair.  It takes three arguments: the number  of
           the color-pair to be changed, the foreground color number,
           and the background color number.   For  portable  applica-
           tions:

           -    The value of the first argument must be between 1 and
                COLOR_PAIRS-1.

           -    The value of the second and third arguments  must  be
                between  0 and COLORS.  Color pair 0 is assumed to be
                white on black, but is actually whatever the terminal
                implements before color is initialized.  It cannot be
                modified by the application.

           If the color-pair was previously initialized,  the  screen
           is  refreshed  and  all occurrences of that color-pair are
           changed to the new definition.  As an  extension,  ncurses
           allows you to set color pair 0 via the assume_default_col-
           ors routine, or to specify the use of default colors (col-
           or  number  -1) if you first invoke the use_default_colors
           routine.  The init_color routine changes the definition of
           a color.  It takes four arguments: the number of the color
           to be changed  followed  by  three  RGB  values  (for  the
           amounts of red, green, and blue components).  The value of
           the first argument must be between 0 and COLORS.  (See the
           section  Colors for the default color index.)  Each of the
           last three arguments must be a value between 0  and  1000.
           When  init_color is used, all occurrences of that color on
           the screen immediately change to the new definition.   The
           has_colors routine requires no arguments.  It returns TRUE
           if the terminal can manipulate colors; otherwise,  it  re-
           turns  FALSE.   This routine facilitates writing terminal-
           independent programs.  For example, a programmer  can  use
           it  to decide whether to use color or some other video at-
           tribute.  The can_change_color routine requires  no  argu-
           ments.   It  returns  TRUE if the terminal supports colors
           and can change their definitions; other, it returns FALSE.
           This routine facilitates writing terminal-independent pro-
           grams.  The color_content routine gives programmers a  way
           to  find  the  intensity of the red, green, and blue (RGB)
           components in a color.  It requires  four  arguments:  the
           color  number,  and  three addresses of shorts for storing
           the information about the amounts of red, green, and  blue
           components in the given color.  The value of the first ar-
           gument must be between 0 and COLORS.  The values that  are
           stored at the addresses pointed to by the last three argu-
           ments are between  0  (no  component)  and  1000  (maximum
           amount  of  component).   The  pair_content routine allows
           programmers to find out what  colors  a  given  color-pair
           consists  of.  It requires three arguments: the color-pair
           number, and two addresses of shorts for storing the  fore-
           ground and the background color numbers.  The value of the
           first argument must be between 1 and  COLOR_PAIRS-1.   The
           values  that are stored at the addresses pointed to by the
           second and third arguments are between 0 and COLORS.

       Colors
           In <curses.h> the following macros are defined.  These are
           the  default colors.  curses also assumes that COLOR_BLACK
           is the default background color for all terminals.
                 COLOR_BLACK
                 COLOR_RED
                 COLOR_GREEN
                 COLOR_YELLOW
                 COLOR_BLUE
                 COLOR_MAGENTA
                 COLOR_CYAN
                 COLOR_WHITE

## RETURN VALUE

           The routines can_change_color()  and  has_colors()  return
           TRUE  or FALSE.  All other routines return the integer ERR
           upon failure and an OK (SVr4 specifies  only  "an  integer
           value other than ERR") upon successful completion.

           X/Open  defines  no error conditions.  This implementation
           will return ERR on attempts to use  color  values  outside
           the range 0 to COLORS-1 (except for the default colors ex-
           tension), or use color pairs outside the range 0  to  COL-
           OR_PAIR-1.  Color values used in init_color must be in the
           range 0 to 1000.  An error is returned from all  functions
           if the terminal has not been initialized.  An error is re-
           turned from  secondary  functions  such  as  init_pair  if
           start_color was not called.

                  init_color
                       returns an error if the terminal does not sup-
                       port  this  feature,  e.g.,  if  the  initial-
                       ize_color capability is absent from the termi-
                       nal description.

                  start_color
                       returns an error If the color table cannot  be
                       allocated.

## NOTES

           In  the  ncurses implementation, there is a separate color
           activation flag, color palette, color pairs table, and as-
           sociated  COLORS  and  COLOR_PAIRS counts for each screen;
           the start_color function only affects the current  screen.
           The SVr4/XSI interface is not really designed with this in
           mind, and historical  implementations  may  use  a  single
           shared color palette.  Note that setting an implicit back-
           ground color via a color pair affects only character cells
           that  a  character write operation explicitly touches.  To
           change the background color used when parts  of  a  window
           are  blanked  by  erasing  or  scrolling  operations,  see
           curs_bkgd(3x).  Several caveats apply on 386 and  486  ma-
           chines with VGA-compatible graphics:

           -    COLOR_YELLOW  is  actually brown.  To get yellow, use
                COLOR_YELLOW combined with the A_BOLD attribute.

           -    The A_BLINK attribute  should  in  theory  cause  the
                background  to  go bright.  This often fails to work,
                and even some cards for which it mostly  works  (such
                as  the  Paradise and compatibles) do the wrong thing
                when you try to set a bright "yellow" background (you
                get a blinking yellow foreground instead).

           -    Color RGB values are not settable.

## PORTABILITY

           This  implementation  satisfies XSI Curses's minimum maxi-
           mums for COLORS and COLOR_PAIRS.

           The init_pair routine accepts  negative  values  of  fore-
           ground   and  background  color  to  support  the  use_de-
           fault_colors extension, but only if that routine has  been
           first invoked.

           The  assumption that COLOR_BLACK is the default background
           color for all terminals can  be  modified  using  the  as-
           sume_default_colors extension.

           This  implementation  checks  the  pointers, e.g., for the
           values returned by  color_content  and  pair_content,  and
           will treat those as optional parameters when null.

## SEE ALSO

           curses(3x),  curs_initscr(3x), curs_attr(3x), default_col-
           ors(3x)

                                                             curs_color(3x)