ncurses 6.0 - patch 20151205
[ncurses.git] / doc / html / man / curs_color.3x.html
index b385da464dfbbfaed7cffff9d88ee774d924fc27..6f4aea054e9a0412b72af0a5123849610fc95317 100644 (file)
@@ -1,7 +1,6 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <!-- 
   ****************************************************************************
-  * Copyright (c) 1998-2009,2010 Free Software Foundation, Inc.              *
+  * Copyright (c) 1998-2010,2015 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.36 2014/11/16 00:44:29 tom Exp @
+  * @Id: curs_color.3x,v 1.40 2015/12/05 20:09:42 tom Exp @
 -->
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <HTML>
 <HEAD>
+<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+<meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
 <TITLE>curs_color 3x</TITLE>
 <link rev=made href="mailto:bug-ncurses@gnu.org">
 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 </HEAD>
 <BODY>
-<H1>curs_color 3x</H1>
-<HR>
+<H1 class="no-header">curs_color 3x</H1>
 <PRE>
-<!-- Manpage converted by man2html 3.0.1 -->
 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>                                           <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
 
 
 
 
 </PRE>
-<H2>NAME</H2><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
 
 
 </PRE>
-<H2>SYNOPSIS</H2><PRE>
+<H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
        <STRONG>#</STRONG> <STRONG>include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
 
        <STRONG>int</STRONG> <STRONG>start_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>
+
 
+</PRE>
+<H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
 
 </PRE>
-<H2>DESCRIPTION</H2><PRE>
-   <STRONG>Overview</STRONG>
-       <STRONG>curses</STRONG> support color attributes on terminals with that ca-
-       pability.   To  use  these  routines  <STRONG>start_color</STRONG>  must be
+<H3><a name="h3-Overview">Overview</a></H3><PRE>
+       <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
        The  routine  <STRONG>pair_content</STRONG> allows a programmer to find out
        how a given color-pair is currently defined.
 
-   <STRONG>Routine</STRONG> <STRONG>Descriptions</STRONG>
+
+</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>.
-       <STRONG>start_color</STRONG> initializes eight basic  colors  (black,  red,
-       green,  yellow,  blue,  magenta, cyan, and white), and two
-       global variables,  <STRONG>COLORS</STRONG>  and  <STRONG>COLOR_PAIRS</STRONG>  (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.
+       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
+           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
+           pairs are initialized.
+
+       <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>)
+           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
+           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
+           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
        to  by  the  second and third arguments are in the range <STRONG>0</STRONG>
        through <STRONG>COLORS</STRONG>, inclusive.
 
-   <STRONG>Colors</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  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>
 
 
 </PRE>
-<H2>RETURN VALUE</H2><PRE>
-       The routines <STRONG>can_change_color()</STRONG>  and  <STRONG>has_colors()</STRONG>  return
+<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>.
 
        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 <EM>initialize</EM><STRONG>_</STRONG><EM>color</EM> 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>NOTES</H2><PRE>
-       In the <EM>ncurses</EM> implementation, there is a  separate  color
+<H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+       In  the  <EM>ncurses</EM> 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>PORTABILITY</H2><PRE>
-       This  implementation  satisfies XSI Curses's minimum maxi-
+<H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+       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.
 
 
 </PRE>
-<H2>SEE ALSO</H2><PRE>
+<H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,  <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,  <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>,  <STRONG>curs_vari-</STRONG>
        <STRONG><A HREF="curs_variables.3x.html">ables(3x)</A></STRONG>, <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>
 
 
                                                          <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
 </PRE>
-<HR>
-Man(1) output converted with <a href="http://invisible-island.net/scripts/readme.html#others_scripts">man2html</a>
+<div class="nav">
+<ul>
+<li><a href="#h2-NAME">NAME</a></li>
+<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
+<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>
+</li>
+<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
+<li><a href="#h2-NOTES">NOTES</a></li>
+<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
+<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
+</ul>
+</div>
 </BODY>
 </HTML>