ncurses 6.0 - patch 20170114
[ncurses.git] / doc / html / man / curs_color.3x.html
index 9cf3791793c61a09817f73d332d3461949a74655..cf446d172566445aa7beaf97177a39f72f78abee 100644 (file)
@@ -1,6 +1,6 @@
 <!-- 
   ****************************************************************************
-  * Copyright (c) 1998-2010,2015 Free Software Foundation, Inc.              *
+  * Copyright (c) 1998-2016,2017 Free Software Foundation, Inc.              *
   *                                                                          *
   * Permission is hereby granted, free of charge, to any person obtaining a  *
   * copy of this software and associated documentation files (the            *
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_color.3x,v 1.40 2015/12/05 20:09:42 tom Exp @
+  * @Id: curs_color.3x,v 1.46 2017/01/07 19:57:48 tom Exp @
+  * .br
+  * .br
+  * .br
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 
 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
        <STRONG>start_color</STRONG>, <STRONG>init_pair</STRONG>, <STRONG>init_color</STRONG>, <STRONG>has_colors</STRONG>,
-       <STRONG>can_change_color</STRONG>, <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>, <STRONG>COLOR_PAIR</STRONG>
-       - <STRONG>curses</STRONG> color manipulation routines
+       <STRONG>can_change_color</STRONG>, <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>, <STRONG>COLOR_PAIR</STRONG>,
+       <STRONG>PAIR_NUMBER</STRONG> - <STRONG>curses</STRONG> color manipulation routines
 
 
 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
-       <STRONG>#</STRONG> <STRONG>include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
+       <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
 
        <STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
        <STRONG>int</STRONG> <STRONG>init_pair(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>f,</STRONG> <STRONG>short</STRONG> <STRONG>b);</STRONG>
        <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>
+
        <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
        <STRONG>bool</STRONG> <STRONG>can_change_color(void);</STRONG>
+
        <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>
        <STRONG>*b);</STRONG>
        <STRONG>int</STRONG> <STRONG>pair_content(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>*f,</STRONG> <STRONG>short</STRONG> <STRONG>*b);</STRONG>
+
        <STRONG>int</STRONG> <STRONG>COLOR_PAIR(int</STRONG> <STRONG>n);</STRONG>
+       <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM><STRONG>);</STRONG>
 
 
 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
@@ -76,8 +83,8 @@
        background color (for the blank field on which the charac-
        ters are displayed).  A programmer  initializes  a  color-
        pair  with  the routine <STRONG>init_pair</STRONG>.  After it has been ini-
-       tialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>), a macro  defined  in  <STRONG>&lt;curses.h&gt;</STRONG>,
-       can be used as a new video attribute.
+       tialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>) can be used to convert the pair to
+       a video attribute.
 
        If  a  terminal  is capable of redefining colors, the pro-
        grammer can use the routine <STRONG>init_color</STRONG> to change the defi-
        <STRONG>o</STRONG>   the background character (e.g., <STRONG>wbkgdset</STRONG>).
 
        Per-character and window attributes are usually set  by  a
-       parameter  containing  video  attributes  including a <STRONG>COL-</STRONG>
-       <STRONG>OR_PAIR</STRONG> value.  Some functions such  as  <STRONG>wattr_set</STRONG>  use  a
-       separate parameter which is the color pair number.
+       parameter  containing  video  attributes including a color
+       pair value.  Some functions such as <STRONG>wattr_set</STRONG> use a  sepa-
+       rate parameter which is the color pair number.
 
        The  background character is a special case: it includes a
        character value, just as if it were passed to <STRONG>waddch</STRONG>.
        to  by  the  second and third arguments are in the range <STRONG>0</STRONG>
        through <STRONG>COLORS</STRONG>, inclusive.
 
+       <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM>) extracts the color value from its <EM>attrs</EM>
+       parameter  and returns it as a color pair number.  Its in-
+       verse <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number to an at-
+       tribute.   Attributes  can hold color pairs in the range 0
+       to 255.  If you need a color pair larger  than  that,  you
+       must  use functions such as <STRONG>attr_set</STRONG> (which pass the color
+       pair as a separate parameter) rather than the legacy func-
+       tions such as <STRONG>attrset</STRONG>.
+
 
 </PRE><H3><a name="h3-Colors">Colors</a></H3><PRE>
        In <STRONG>&lt;curses.h&gt;</STRONG> the following macros are defined.  These are
-       the  standard colors (ISO-6429).  <STRONG>curses</STRONG> also assumes that
+       the standard colors (ISO-6429).  <STRONG>curses</STRONG> also assumes  that
        <STRONG>COLOR_BLACK</STRONG> is the default background color for all termi-
        nals.
 
 
 
 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
-       The  routines  <STRONG>can_change_color()</STRONG>  and <STRONG>has_colors()</STRONG> return
-       <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
+       The routines <STRONG>can_change_color</STRONG> and <STRONG>has_colors</STRONG>  return  <STRONG>TRUE</STRONG>
+       or <STRONG>FALSE</STRONG>.
 
        All other routines return the integer <STRONG>ERR</STRONG> upon failure and
-       an  <STRONG>OK</STRONG>  (SVr4  specifies only "an integer value other than
+       an <STRONG>OK</STRONG> (SVr4 specifies only "an integer  value  other  than
        <STRONG>ERR</STRONG>") upon successful completion.
 
-       X/Open defines no error conditions.   This  implementation
-       will  return  <STRONG>ERR</STRONG>  on attempts to use color values outside
+       X/Open  defines  no error conditions.  This implementation
+       will return <STRONG>ERR</STRONG> on attempts to use  color  values  outside
        the range <STRONG>0</STRONG> to COLORS-1 (except for the default colors ex-
-       tension),  or  use color pairs outside the range <STRONG>0</STRONG> to <STRONG>COL-</STRONG>
-       <STRONG>OR_PAIRS-1</STRONG>.  Color values used in <STRONG>init_color</STRONG>  must  be  in
-       the  range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.  An error is returned from all func-
-       tions if the terminal has not been initialized.  An  error
-       is  returned from secondary functions such as <STRONG>init_pair</STRONG> if
+       tension), or use color pairs outside the range <STRONG>0</STRONG>  to  <STRONG>COL-</STRONG>
+       <STRONG>OR_PAIRS-1</STRONG>.   Color  values  used in <STRONG>init_color</STRONG> must be in
+       the range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.  An error is returned from all  func-
+       tions  if the terminal has not been initialized.  An error
+       is returned from secondary functions such as <STRONG>init_pair</STRONG>  if
        <STRONG>start_color</STRONG> was not called.
 
           <STRONG>init_color</STRONG>
-               returns an error if the terminal does not  support
-               this  feature, e.g., if the <EM>initialize</EM><STRONG>_</STRONG><EM>color</EM> capa-
+               returns  an error if the terminal does not support
+               this feature, e.g., if the <STRONG>initialize_color</STRONG>  capa-
                bility is absent from the terminal description.
 
           <STRONG>start_color</STRONG>
-               returns an error if the color table cannot be  al-
+               returns  an error if the color table cannot be al-
                located.
 
 
 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
-       In  the  <EM>ncurses</EM> implementation, there is a separate color
+       In the <STRONG>ncurses</STRONG> 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 <STRONG>start_color</STRONG> function only affects the current  screen.
+       sociated COLORS and COLOR_PAIRS counts  for  each  screen;
+       the  <STRONG>start_color</STRONG> 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
+       mind,  and  historical  implementations  may  use a single
        shared color palette.
 
        Note that setting an implicit background 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
+       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 <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
 
-       Several  caveats  apply  on 386 and 486 machines with VGA-
+       Several caveats apply on 386 and 486  machines  with  VGA-
        compatible graphics:
 
-       <STRONG>o</STRONG>   COLOR_YELLOW is actually brown.  To  get  yellow,  use
+       <STRONG>o</STRONG>   COLOR_YELLOW  is  actually  brown.  To get yellow, use
            COLOR_YELLOW combined with the <STRONG>A_BOLD</STRONG> attribute.
 
        <STRONG>o</STRONG>   The A_BLINK attribute should in theory cause the back-
-           ground to go bright.  This often fails  to  work,  and
+           ground  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
+           Paradise  and compatibles) do the wrong thing when you
+           try to set a bright "yellow"  background  (you  get  a
            blinking yellow foreground instead).
 
        <STRONG>o</STRONG>   Color RGB values are not settable.
 
 
 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
-       This implementation satisfies XSI Curses's  minimum  maxi-
+       This  implementation  satisfies XSI Curses's minimum maxi-
        mums for <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG>.
 
-       The  <STRONG>init_pair</STRONG>  routine  accepts  negative values of fore-
-       ground  and  background  color  to  support  the   <STRONG>use_de-</STRONG>
-       <STRONG>fault_colors</STRONG>  extension, but only if that routine has been
+       The <STRONG>init_pair</STRONG> routine accepts  negative  values  of  fore-
+       ground   and  background  color  to  support  the  <STRONG>use_de-</STRONG>
+       <STRONG>fault_colors</STRONG> extension, but only if that routine has  been
        first invoked.
 
-       The assumption that <STRONG>COLOR_BLACK</STRONG> is the default  background
-       color  for  all  terminals  can  be modified using the <STRONG>as-</STRONG>
+       The  assumption that <STRONG>COLOR_BLACK</STRONG> is the default background
+       color for all terminals can  be  modified  using  the  <STRONG>as-</STRONG>
        <STRONG>sume_default_colors</STRONG> extension.
 
-       This implementation checks the  pointers,  e.g.,  for  the
-       values  returned  by  <STRONG>color_content</STRONG>  and <STRONG>pair_content</STRONG>, and
+       This  implementation  checks  the  pointers, e.g., for the
+       values returned by  <STRONG>color_content</STRONG>  and  <STRONG>pair_content</STRONG>,  and
        will treat those as optional parameters when null.