ncurses 6.0 - patch 20150606
[ncurses.git] / doc / html / man / curs_color.3x.html
index 5ff2f5f949488853b87ecf1b33158e8f1a69c265..8d0f00c6368ac4e1f5e80c8b0314d466bee0ddf1 100644 (file)
@@ -26,7 +26,7 @@
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_color.3x,v 1.37 2015/04/04 19:42:47 tom Exp @
+  * @Id: curs_color.3x,v 1.39 2015/06/06 23:29:02 tom Exp @
 -->
 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
@@ -71,8 +71,8 @@
 
 </PRE>
 <H3><a name="h3-Overview">Overview</a></H3><PRE>
-       <STRONG>curses</STRONG> support color attributes on terminals with that ca-
-       pability.   To  use  these  routines  <STRONG>start_color</STRONG>  must be
+       <STRONG>curses</STRONG> supports color attributes on  terminals  with  that
+       capability.   To  use  these  routines <STRONG>start_color</STRONG> must be
        called, usually right after <STRONG>initscr</STRONG>.   Colors  are  always
        used  in pairs (referred to as color-pairs).  A color-pair
        consists of a foreground  color  (for  characters)  and  a
        how a given color-pair is currently defined.
 
 
+</PRE>
+<H3><a name="h3-Color-Rendering">Color Rendering</a></H3><PRE>
+       The <STRONG>curses</STRONG> library combines these inputs  to  produce  the
+       actual  foreground  and  background  colors  shown  on the
+       screen:
+
+       <STRONG>o</STRONG>   per-character video attributes (e.g., via <STRONG>waddch</STRONG>),
+
+       <STRONG>o</STRONG>   the window attribute (e.g., by <STRONG>wattrset</STRONG>), and
+
+       <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.
+
+       The  background character is a special case: it includes a
+       character value, just as if it were passed to <STRONG>waddch</STRONG>.
+
+       The <STRONG>curses</STRONG> library does the actual work of combining these
+       color pairs in an internal function called from <STRONG>waddch</STRONG>:
+
+       <STRONG>o</STRONG>   If the parameter passed to <STRONG>waddch</STRONG> is <EM>blank</EM>, and it us-
+           es the special color pair 0,
+
+           <STRONG>o</STRONG>   <STRONG>curses</STRONG> next checks the window attribute.
+
+           <STRONG>o</STRONG>   If the window attribute does not use color pair 0,
+               <STRONG>curses</STRONG>  uses  the  color  pair from the window at-
+               tribute.
+
+           <STRONG>o</STRONG>   Otherwise, <STRONG>curses</STRONG> uses the background character.
+
+       <STRONG>o</STRONG>   If the parameter passed to <STRONG>waddch</STRONG> is <EM>not</EM> <EM>blank</EM>, or  it
+           does  not use the special color pair 0, <STRONG>curses</STRONG> prefers
+           the color pair from the parameter, if it  is  nonzero.
+           Otherwise, it tries the window attribute next, and fi-
+           nally the background character.
+
+       Some <STRONG>curses</STRONG> functions such as <STRONG>wprintw</STRONG> call <STRONG>waddch</STRONG>.   Those
+       do  not  combine  its parameter with a color pair.  Conse-
+       quently those calls use only the window attribute  or  the
+       background character.
+
+
 </PRE>
 <H3><a name="h3-Routine-Descriptions">Routine Descriptions</a></H3><PRE>
        The <STRONG>start_color</STRONG> 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 <STRONG>initscr</STRONG>.
+       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  <STRONG>initscr</STRONG>.
        <STRONG>start_color</STRONG> does this:
 
-       <STRONG>o</STRONG>   It initializes two global variables, <STRONG>COLORS</STRONG>  and  <STRONG>COL-</STRONG>
-           <STRONG>OR_PAIRS</STRONG>  (respectively defining the maximum number of
+       <STRONG>o</STRONG>   It  initializes  two global variables, <STRONG>COLORS</STRONG> and <STRONG>COL-</STRONG>
+           <STRONG>OR_PAIRS</STRONG> (respectively defining the maximum number  of
            colors and color-pairs the terminal can support).
 
        <STRONG>o</STRONG>   It initializes the special color pair <STRONG>0</STRONG> to the default
-           foreground  and  background  colors.   No  other color
+           foreground and  background  colors.   No  other  color
            pairs are initialized.
 
-       <STRONG>o</STRONG>   It restores the colors on the terminal to  the  values
+       <STRONG>o</STRONG>   It  restores  the colors on the terminal to the values
            they had when the terminal was just turned on.
 
-       <STRONG>o</STRONG>   If  the terminal supports the <STRONG>initc</STRONG> (<STRONG>initialize_color</STRONG>)
+       <STRONG>o</STRONG>   If the terminal supports the <STRONG>initc</STRONG>  (<STRONG>initialize_color</STRONG>)
            capability, <STRONG>start_color</STRONG> initializes its internal table
            representing the red, green and blue components of the
            color palette.
            The components depend on whether the terminal uses CGA
            (aka "ANSI") or HLS (i.e., the <STRONG>hls</STRONG> (<STRONG>hue_lightness_sat-</STRONG>
            <STRONG>uration</STRONG>) capability is set).  The table is initialized
-           first  for eight basic colors (black, red, green, yel-
-           low, blue, magenta, cyan, and white), and  after  that
-           (if  the terminal supports more than eight colors) the
+           first for eight basic colors (black, red, green,  yel-
+           low,  blue,  magenta, cyan, and white), and after that
+           (if the terminal supports more than eight colors)  the
            components are initialized to <STRONG>1000</STRONG>.
 
-           <STRONG>start_color</STRONG> does not attempt  to  set  the  terminal's
-           color  palette to match its built-in table.  An appli-
-           cation may use <STRONG>init_color</STRONG> to alter the internal  table
+           <STRONG>start_color</STRONG>  does  not  attempt  to set the terminal's
+           color palette to match its built-in table.  An  appli-
+           cation  may use <STRONG>init_color</STRONG> to alter the internal table
            along with the terminal's color.
 
-       These  limits apply to color values and color pairs.  Val-
-       ues outside these limits are not legal, and may result  in
+       These limits apply to color values and color pairs.   Val-
+       ues  outside these limits are not legal, and may result in
        a runtime error:
 
        <STRONG>o</STRONG>   <STRONG>COLORS</STRONG> corresponds to the terminal database's <STRONG>max_col-</STRONG>
        <STRONG>o</STRONG>   color values are expected to be in the range <STRONG>0</STRONG> to <STRONG>COL-</STRONG>
            <STRONG>ORS-1</STRONG>, inclusive (including <STRONG>0</STRONG> and <STRONG>COLORS-1</STRONG>).
 
-       <STRONG>o</STRONG>   a special color value <STRONG>-1</STRONG> is used in  certain  extended
-           functions  to  denote  the  <EM>default</EM> <EM>color</EM> (see <STRONG>use_de-</STRONG>
+       <STRONG>o</STRONG>   a  special  color value <STRONG>-1</STRONG> is used in certain extended
+           functions to denote the  <EM>default</EM>  <EM>color</EM>  (see  <STRONG>use_de-</STRONG>
            <STRONG>fault_colors</STRONG>).
 
-       <STRONG>o</STRONG>   <STRONG>COLOR_PAIRS</STRONG> corresponds  to  the  terminal  database's
-           <STRONG>max_pairs</STRONG>  capability,  which  is  typically  a signed
+       <STRONG>o</STRONG>   <STRONG>COLOR_PAIRS</STRONG>  corresponds  to  the  terminal database's
+           <STRONG>max_pairs</STRONG> capability,  which  is  typically  a  signed
            16-bit integer (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
 
-       <STRONG>o</STRONG>   legal color pair values are in the  range  <STRONG>1</STRONG>  to  <STRONG>COL-</STRONG>
+       <STRONG>o</STRONG>   legal  color  pair  values  are in the range <STRONG>1</STRONG> to <STRONG>COL-</STRONG>
            <STRONG>OR_PAIRS-1</STRONG>, inclusive.
 
        <STRONG>o</STRONG>   color pair <STRONG>0</STRONG> is special; it denotes "no color".
 
-           Color  pair  <STRONG>0</STRONG> is assumed to be white on black, but is
+           Color pair <STRONG>0</STRONG> is assumed to be white on black,  but  is
            actually whatever the terminal implements before color
            is initialized.  It cannot be modified by the applica-
            tion.
 
-       The <STRONG>init_pair</STRONG> 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
+       The  <STRONG>init_pair</STRONG>  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 applications:
 
-       <STRONG>o</STRONG>   The  first  argument must be a legal color pair value.
-           If default colors are  used  (see  <STRONG>use_default_colors</STRONG>)
-           the  upper  limit is adjusted to allow for extra pairs
-           which use a default color in foreground  and/or  back-
+       <STRONG>o</STRONG>   The first argument must be a legal color  pair  value.
+           If  default  colors  are used (see <STRONG>use_default_colors</STRONG>)
+           the upper limit is adjusted to allow for  extra  pairs
+           which  use  a default color in foreground and/or back-
            ground.
 
-       <STRONG>o</STRONG>   The  second  and  third  arguments must be legal color
+       <STRONG>o</STRONG>   The second and third arguments  must  be  legal  color
            values.
 
-       If the color-pair was previously initialized,  the  screen
-       is  refreshed  and  all occurrences of that color-pair are
+       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  <STRONG>0</STRONG>
-       via  the  <STRONG>assume_default_colors</STRONG> routine, or to specify the
-       use of default colors (color number <STRONG>-1</STRONG>) if you  first  in-
+       As  an  extension,  ncurses allows you to set color pair <STRONG>0</STRONG>
+       via the <STRONG>assume_default_colors</STRONG> routine, or to  specify  the
+       use  of  default colors (color number <STRONG>-1</STRONG>) if you first in-
        voke the <STRONG>use_default_colors</STRONG> routine.
 
-       The  <STRONG>init_color</STRONG> 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
+       The <STRONG>init_color</STRONG> 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 first argument must
-       be  a  legal  color  value; default colors are not allowed
-       here.  (See the section <STRONG>Colors</STRONG> for the default  color  in-
+       be a legal color value; default  colors  are  not  allowed
+       here.   (See  the section <STRONG>Colors</STRONG> for the default color in-
        dex.)  Each of the last three arguments must be a value in
-       the range <STRONG>0</STRONG> through <STRONG>1000</STRONG>.  When <STRONG>init_color</STRONG>  is  used,  all
+       the  range  <STRONG>0</STRONG>  through <STRONG>1000</STRONG>.  When <STRONG>init_color</STRONG> is used, all
        occurrences of that color on the screen immediately change
        to the new definition.
 
-       The <STRONG>has_colors</STRONG> routine requires no arguments.  It  returns
-       <STRONG>TRUE</STRONG>  if the terminal can manipulate colors; otherwise, it
+       The  <STRONG>has_colors</STRONG> routine requires no arguments.  It returns
+       <STRONG>TRUE</STRONG> if the terminal can manipulate colors; otherwise,  it
        returns <STRONG>FALSE</STRONG>.  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-
+       independent programs.  For example, a programmer  can  use
+       it  to decide whether to use color or some other video at-
        tribute.
 
-       The  <STRONG>can_change_color</STRONG>  routine  requires no arguments.  It
-       returns <STRONG>TRUE</STRONG> if  the  terminal  supports  colors  and  can
-       change  their  definitions; other, it returns <STRONG>FALSE</STRONG>.  This
+       The <STRONG>can_change_color</STRONG> routine requires  no  arguments.   It
+       returns  <STRONG>TRUE</STRONG>  if  the  terminal  supports  colors and can
+       change their definitions; other, it returns  <STRONG>FALSE</STRONG>.   This
        routine facilitates writing terminal-independent programs.
 
-       The <STRONG>color_content</STRONG> routine gives programmers a way to  find
+       The  <STRONG>color_content</STRONG> 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 <STRONG>short</STRONG>s for storing the information
-       about the amounts of red, green, and  blue  components  in
+       and three addresses of <STRONG>short</STRONG>s for storing the  information
+       about  the  amounts  of red, green, and blue components in
        the given color.  The first argument must be a legal color
-       value, i.e., <STRONG>0</STRONG> through <STRONG>COLORS-1</STRONG>,  inclusive.   The  values
-       that  are  stored  at the addresses pointed to by the last
-       three arguments are in the range <STRONG>0</STRONG> (no component)  through
+       value,  i.e.,  <STRONG>0</STRONG>  through <STRONG>COLORS-1</STRONG>, inclusive.  The values
+       that are stored at the addresses pointed to  by  the  last
+       three  arguments are in the range <STRONG>0</STRONG> (no component) through
        <STRONG>1000</STRONG> (maximum amount of component), inclusive.
 
-       The  <STRONG>pair_content</STRONG>  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 <STRONG>short</STRONG>s for storing the foreground  and  the  background
-       color  numbers.   The first argument must be a legal color
-       value, i.e., in the range <STRONG>1</STRONG> through <STRONG>COLOR_PAIRS-1</STRONG>,  inclu-
+       The <STRONG>pair_content</STRONG> 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  <STRONG>short</STRONG>s  for  storing the foreground and the background
+       color numbers.  The first argument must be a  legal  color
+       value,  i.e., in the range <STRONG>1</STRONG> through <STRONG>COLOR_PAIRS-1</STRONG>, inclu-
        sive.  The values that are stored at the addresses pointed
-       to by the second and third arguments are in  the  range  <STRONG>0</STRONG>
+       to  by  the  second and third arguments are in the range <STRONG>0</STRONG>
        through <STRONG>COLORS</STRONG>, inclusive.
 
 
 </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 default colors.  <STRONG>curses</STRONG> also assumes that  <STRONG>COLOR_BLACK</STRONG>
-       is the default background color for all terminals.
+       the  standard colors (ISO-6429).  <STRONG>curses</STRONG> also assumes that
+       <STRONG>COLOR_BLACK</STRONG> is the default background color for all termi-
+       nals.
 
              <STRONG>COLOR_BLACK</STRONG>
              <STRONG>COLOR_RED</STRONG>
 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 <ul>
 <li><a href="#h3-Overview">Overview</a></li>
+<li><a href="#h3-Color-Rendering">Color Rendering</a></li>
 <li><a href="#h3-Routine-Descriptions">Routine Descriptions</a></li>
 <li><a href="#h3-Colors">Colors</a></li>
 </ul>