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)

Man(1) output converted with man2html