ncurses 6.0 - patch 20180106
[ncurses.git] / doc / html / man / curs_color.3x.html
index 296d8e9e5db52acc5f13d71ce014e1d67dfc80fd..b30d0137dc200c5f58a2fdd27d2505e72f5aadf4 100644 (file)
+<!-- 
+  ****************************************************************************
+  * 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            *
+  * "Software"), to deal in the Software without restriction, including      *
+  * without limitation the rights to use, copy, modify, merge, publish,      *
+  * distribute, distribute with modifications, sublicense, and/or sell       *
+  * copies of the Software, and to permit persons to whom the Software is    *
+  * furnished to do so, subject to the following conditions:                 *
+  *                                                                          *
+  * The above copyright notice and this permission notice shall be included  *
+  * in all copies or substantial portions of the Software.                   *
+  *                                                                          *
+  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
+  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
+  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
+  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
+  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
+  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
+  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
+  *                                                                          *
+  * Except as contained in this notice, the name(s) of the above copyright   *
+  * holders shall not be used in advertising or otherwise to promote the     *
+  * sale, use or other dealings in this Software without prior written       *
+  * authorization.                                                           *
+  ****************************************************************************
+  * @Id: curs_color.3x,v 1.53 2017/11/20 01:03:45 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 https://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 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>
-       <B>start_color</B>,     <B>init_pair</B>,     <B>init_color</B>,    <B>has_colors</B>,
-       <B>can_change_color</B>, <B>color_content</B>, <B>pair_content</B>,  <B>COLOR_PAIR</B>
-       - <B>curses</B> color manipulation routines
 
 
-</PRE>
-<H2>SYNOPSIS</H2><PRE>
-       <B>#</B> <B>include</B> <B>&lt;curses.h&gt;</B>
-       <B>int</B> <B>start_color(void);</B>
-       <B>int</B> <B>init_pair(short</B> <B>pair,</B> <B>short</B> <B>f,</B> <B>short</B> <B>b);</B>
-       <B>int</B> <B>init_color(short</B> <B>color,</B> <B>short</B> <B>r,</B> <B>short</B> <B>g,</B> <B>short</B> <B>b);</B>
-       <B>bool</B> <B>has_colors(void);</B>
-       <B>bool</B> <B>can_change_color(void);</B>
-       <B>int</B>  <B>color_content(short</B>  <B>color,</B> <B>short</B> <B>*r,</B> <B>short</B> <B>*g,</B> <B>short</B>
-       <B>*b);</B>
-       <B>int</B> <B>pair_content(short</B> <B>pair,</B> <B>short</B> <B>*f,</B> <B>short</B> <B>*b);</B>
 
+</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
+       <STRONG>start_color</STRONG>, <STRONG>has_colors</STRONG>, <STRONG>can_change_color</STRONG>, <STRONG>init_pair</STRONG>, <STRONG>init_color</STRONG>,
+       <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>, <STRONG>reset_color_pairs</STRONG>, <STRONG>COLOR_PAIR</STRONG>, <STRONG>PAIR_NUMBER</STRONG>
+       - <STRONG>curses</STRONG> color manipulation routines
 
-</PRE>
-<H2>DESCRIPTION</H2><PRE>
-   <B>Overview</B>
-       <B>curses</B> support color attributes  on  terminals  with  that
-       capability.   To  use  these  routines <B>start_color</B> must be
-       called, usually right after <B>initscr</B>.   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 <B>init_pair</B>.  After it has been ini-
-       tialized, <B>COLOR_PAIR</B>(<I>n</I>), a macro  defined  in  <B>&lt;curses.h&gt;</B>,
-       can be used as a new video attribute.
-
-       If  a  terminal  is capable of redefining colors, the pro-
-       grammer can use the routine <B>init_color</B> to change the defi-
-       nition   of   a   color.    The  routines  <B>has_colors</B>  and
-       <B>can_change_color</B>  return  <B>TRUE</B>  or  <B>FALSE</B>,  depending   on
-       whether  the  terminal  has color capabilities and whether
-       the  programmer  can  change  the  colors.   The   routine
-       <B>color_content</B>  allows  a programmer to extract the amounts
-       of red, green,  and  blue  components  in  an  initialized
-       color.   The  routine  <B>pair_content</B> allows a programmer to
+
+</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
+       <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
+
+       <STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
+
+       <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
+       <STRONG>bool</STRONG> <STRONG>can_change_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>
+       /* extensions */
+       <STRONG>int</STRONG> <STRONG>init_extended_pair(int</STRONG> <STRONG>pair,</STRONG> <STRONG>int</STRONG> <STRONG>f,</STRONG> <STRONG>int</STRONG> <STRONG>b);</STRONG>
+       <STRONG>int</STRONG> <STRONG>init_extended_color(int</STRONG> <STRONG>color,</STRONG> <STRONG>int</STRONG> <STRONG>r,</STRONG> <STRONG>int</STRONG> <STRONG>g,</STRONG> <STRONG>int</STRONG> <STRONG>b);</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>
+       /* extensions */
+       <STRONG>int</STRONG> <STRONG>extended_color_content(int</STRONG> <STRONG>color,</STRONG> <STRONG>int</STRONG> <STRONG>*r,</STRONG> <STRONG>int</STRONG> <STRONG>*g,</STRONG> <STRONG>int</STRONG> <STRONG>*b);</STRONG>
+       <STRONG>int</STRONG> <STRONG>extended_pair_content(int</STRONG> <STRONG>pair,</STRONG> <STRONG>int</STRONG> <STRONG>*f,</STRONG> <STRONG>int</STRONG> <STRONG>*b);</STRONG>
+
+       /* extensions */
+       <STRONG>void</STRONG> <STRONG>reset_color_pairs(void);</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>
+
+</PRE><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
+       background  color (for the blank field on which the characters are dis-
+       played).  A  programmer  initializes  a  color-pair  with  the  routine
+       <STRONG>init_pair</STRONG>.  After it has been initialized, <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 programmer  can  use
+       the  routine  <STRONG>init_color</STRONG> to change the definition of a color.  The rou-
+       tines <STRONG>has_colors</STRONG> and <STRONG>can_change_color</STRONG> return <STRONG>TRUE</STRONG> or  <STRONG>FALSE</STRONG>,  depending
+       on whether the terminal has color capabilities and whether the program-
+       mer can change the colors.  The routine <STRONG>color_content</STRONG> allows a program-
+       mer  to  extract  the  amounts of red, green, and blue components in an
+       initialized color.  The routine <STRONG>pair_content</STRONG>  allows  a  programmer  to
        find out how a given color-pair is currently defined.
 
-   <B>Routine</B> <B>Descriptions</B>
-       The <B>start_color</B> 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 <B>initscr</B>.
-       <B>start_color</B> initializes eight basic  colors  (black,  red,
-       green,  yellow,  blue,  magenta, cyan, and white), and two
-       global variables,  <B>COLORS</B>  and  <B>COLOR_PAIRS</B>  (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 <B>init_pair</B> 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:
-
-       -    The value of the first argument must be between <B>1</B> and
-            <B>COLOR_PAIRS-1</B>.
-
-       -    The value of the second and third arguments  must  be
-            between  0  and  <B>COLORS</B> (the 0 color pair is wired to
-            white on black and cannot be changed).
-
-       If the color-pair was previously initialized,  the  screen
-       is  refreshed  and  all  occurrences of that color-pair is
-       changed to the new definition.
-
-       As an extension, ncurses allows you to set  color  pair  0
-       via  the  <B>assume_default_colors</B> routine, or to specify the
-       use of default colors  (color  number  <B>-1</B>)  if  you  first
-       invoke the <B>use_default_colors</B> routine.
-
-       The  <B>init_color</B> 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 <B>0</B> and <B>COLORS</B>.  (See the section
-       <B>Colors</B> for the default color index.)   Each  of  the  last
-       three  arguments must be a value between 0 and 1000.  When
-       <B>init_color</B> is used, all occurrences of that color  on  the
-       screen immediately change to the new definition.
-
-       The  <B>has_colors</B> routine requires no arguments.  It returns
-       <B>TRUE</B> if the terminal can manipulate colors; otherwise,  it
-       returns <B>FALSE</B>.  This routine facilitates writing terminal-
-       independent programs.  For example, a programmer  can  use
-       it  to  decide  whether  to  use color or some other video
-       attribute.
-
-       The <B>can_change_color</B> routine requires  no  arguments.   It
-       returns  <B>TRUE</B>  if  the  terminal  supports  colors and can
-       change their definitions; other, it returns  <B>FALSE</B>.   This
-       routine facilitates writing terminal-independent programs.
-
-       The <B>color_content</B> 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 <B>short</B>s for storing the information
-       about the amounts of red, green, and  blue  components  in
-       the  given color.  The value of the first argument must be
-       between 0 and <B>COLORS</B>.  The values that are stored  at  the
-       addresses  pointed  to  by  the  last  three arguments are
-       between 0 (no component) and 1000 (maximum amount of  com-
-       ponent).
-
-       The  <B>pair_content</B>  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 <B>short</B>s for storing the foreground  and  the  background
-       color  numbers.   The  value of the first argument must be
-       between 1 and <B>COLOR_PAIRS-1</B>.  The values that  are  stored
-       at  the addresses pointed to by the second and third argu-
-       ments are between 0 and <B>COLORS</B>.
-
-   <B>Colors</B>
-       In <B>&lt;curses.h&gt;</B> the following macros are defined.  These are
-       the  default colors.  <B>curses</B> also assumes that <B>COLOR_BLACK</B>
-       is the default background color for all terminals.
-
-             <B>COLOR_BLACK</B>
-             <B>COLOR_RED</B>
-             <B>COLOR_GREEN</B>
-             <B>COLOR_YELLOW</B>
-             <B>COLOR_BLUE</B>
-             <B>COLOR_MAGENTA</B>
-             <B>COLOR_CYAN</B>
-             <B>COLOR_WHITE</B>
 
+</PRE><H3><a name="h3-Color-Rendering">Color Rendering</a></H3><PRE>
+       The  <STRONG>curses</STRONG>  library  combines these inputs to produce the actual fore-
+       ground and background colors shown on the screen:
 
-</PRE>
-<H2>RETURN VALUE</H2><PRE>
-       The routines <B>can_change_color()</B>  and  <B>has_colors()</B>  return
-       <B>TRUE</B> or <B>FALSE</B>.
+       <STRONG>o</STRONG>   per-character video attributes (e.g., via <STRONG>waddch</STRONG>),
 
-       All other routines return the integer <B>ERR</B> upon failure and
-       an <B>OK</B> (SVr4 specifies only "an integer  value  other  than
-       <B>ERR</B>") upon successful completion.
+       <STRONG>o</STRONG>   the window attribute (e.g., by <STRONG>wattrset</STRONG>), and
 
+       <STRONG>o</STRONG>   the background character (e.g., <STRONG>wbkgdset</STRONG>).
 
-</PRE>
-<H2>NOTES</H2><PRE>
-       In  the  <I>ncurses</I> implementation, there is a separate color
-       activation flag, color palette,  color  pairs  table,  and
-       associated  COLORS and COLOR_PAIRS counts for each screen;
-       the <B>start_color</B> 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.
+       Per-character and window attributes are usually set by a parameter con-
+       taining  video attributes including a color pair value.  Some functions
+       such as <STRONG>wattr_set</STRONG> use a separate parameter which is the color pair num-
+       ber.
 
-       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
-       or scrolling operations, see <B><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></B>.
+       The  background  character  is  a special case: it includes a character
+       value, just as if it were passed to <STRONG>waddch</STRONG>.
 
-       Several  caveats  apply  on 386 and 486 machines with VGA-
-       compatible graphics:
+       The <STRONG>curses</STRONG> library does the actual work of combining these color  pairs
+       in an internal function called from <STRONG>waddch</STRONG>:
 
-       -    COLOR_YELLOW is actually brown.  To get  yellow,  use
-            COLOR_YELLOW combined with the <B>A_BOLD</B> attribute.
+       <STRONG>o</STRONG>   If the parameter passed to <STRONG>waddch</STRONG> is <EM>blank</EM>, and it uses the special
+           color pair 0,
 
-       -    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).
+           <STRONG>o</STRONG>   <STRONG>curses</STRONG> next checks the window attribute.
 
-       -    Color RGB values are not settable.
+           <STRONG>o</STRONG>   If the window attribute does not use color pair 0, <STRONG>curses</STRONG>  uses
+               the color pair from the window attribute.
 
+           <STRONG>o</STRONG>   Otherwise, <STRONG>curses</STRONG> uses the background character.
 
-</PRE>
-<H2>PORTABILITY</H2><PRE>
-       This implementation satisfies XSI Curses's  minimum  maxi-
-       mums for <B>COLORS</B> and <B>COLOR_PAIRS</B>.
+       <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 at-
+           tribute next, and finally the background character.
 
-       The  <B>init_pair</B>  routine  accepts  negative values of fore-
-       ground   and   background    color    to    support    the
-       <B>use_default_colors</B> extension, but only if that routine has
-       been first invoked.
+       Some <STRONG>curses</STRONG> functions such as <STRONG>wprintw</STRONG> call <STRONG>waddch</STRONG>.  Those do  not  com-
+       bine its parameter with a color pair.  Consequently those calls use on-
+       ly the window attribute or the background character.
 
-       The assumption that <B>COLOR_BLACK</B> is the default  background
-       color   for  all  terminals  can  be  modified  using  the
-       <B>assume_default_colors</B> extension,
 
+</PRE><H2><a name="h2-CONSTANTS">CONSTANTS</a></H2><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 <STRONG>COLOR_BLACK</STRONG> is the default
+       background color for all terminals.
 
-</PRE>
-<H2>SEE ALSO</H2><PRE>
-       <B><A HREF="ncurses.3x.html">curses(3x)</A></B>, <B><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></B>, <B><A HREF="curs_attr.3x.html">curs_attr(3x)</A></B>, <B><A HREF="dft_fgbg.3x.html">dft_fgbg(3x)</A></B>
+             <STRONG>COLOR_BLACK</STRONG>
+             <STRONG>COLOR_RED</STRONG>
+             <STRONG>COLOR_GREEN</STRONG>
+             <STRONG>COLOR_YELLOW</STRONG>
+             <STRONG>COLOR_BLUE</STRONG>
+             <STRONG>COLOR_MAGENTA</STRONG>
+             <STRONG>COLOR_CYAN</STRONG>
+             <STRONG>COLOR_WHITE</STRONG>
+
+       Some terminals support more than the eight (8)  "ANSI"  colors.   There
+       are no standard names for those additional colors.
+
+
+</PRE><H2><a name="h2-VARIABLES">VARIABLES</a></H2><PRE>
+
+</PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE>
+       is  initialized by <STRONG>start_color</STRONG> to the maximum number of colors the ter-
+       minal can support.
+
+
+</PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE>
+       is initialized by <STRONG>start_color</STRONG> to the maximum number of color pairs  the
+       terminal can support.
+
+
+</PRE><H2><a name="h2-FUNCTIONS">FUNCTIONS</a></H2><PRE>
+
+</PRE><H3><a name="h3-start_color">start_color</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  manipu-
+       lation  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>COLOR_PAIRS</STRONG>  (re-
+           spectively  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_saturation</STRONG>) capability is
+           set).  The table  is  initialized  first  for  eight  basic  colors
+           (black,  red,  green,  yellow, 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 application may use <STRONG>init_color</STRONG> to al-
+           ter the internal table along with the terminal's color.
+
+       These  limits  apply  to  color values and color pairs.  Values 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_colors</STRONG>  capabili-
+           ty, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
+
+       <STRONG>o</STRONG>   color  values are expected to be in the range <STRONG>0</STRONG> to <STRONG>COLORS-1</STRONG>, inclu-
+           sive (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_default_colors</STRONG>).
+
+       <STRONG>o</STRONG>   <STRONG>COLOR_PAIRS</STRONG>  corresponds to the terminal database's <STRONG>max_pairs</STRONG> capa-
+           bility, (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>COLOR_PAIRS-1</STRONG>, inclu-
+           sive.
+
+       <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 actually what-
+           ever the terminal implements before color is initialized.  It  can-
+           not be modified by the application.
+
+
+</PRE><H3><a name="h3-has_colors">has_colors</a></H3><PRE>
+       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 rou-
+       tine facilitates writing terminal-independent programs.  For example, a
+       programmer can use it to decide whether to  use  color  or  some  other
+       video attribute.
+
+
+</PRE><H3><a name="h3-can_change_color">can_change_color</a></H3><PRE>
+       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-indepen-
+       dent programs.
+
+
+</PRE><H3><a name="h3-init_pair">init_pair</a></H3><PRE>
+       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 fore-
+       ground color number, and the background color number.  For portable ap-
+       plications:
+
+       <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 adjust-
+           ed to allow for extra pairs which use a default color in foreground
+           and/or background.
+
+       <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 changed to the new defini-
+       tion.
+
+       As an extension, ncurses allows you to set color pair  <STRONG>0</STRONG>  via  the  <STRONG>as-</STRONG>
+       <STRONG><A HREF="assume_default_colors.3x.html">sume_default_colors(3x)</A></STRONG>  routine, or to specify the use of default col-
+       ors (color number <STRONG>-1</STRONG>) if you first  invoke  the  <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>
+       routine.
+
+       The  extension  <STRONG>reset_color_pairs</STRONG>  tells  ncurses to discard all of the
+       color-pair information which was set with <STRONG>init_pair</STRONG>.  It  also  touches
+       the  current-  and  standard-screens, allowing an application to switch
+       color palettes rapidly.
+
+
+</PRE><H3><a name="h3-init_color">init_color</a></H3><PRE>
+       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).
+
+       <STRONG>o</STRONG>   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
+           index.)
+
+       <STRONG>o</STRONG>   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 occurrences of that color on the screen
+       immediately change to the new definition.
+
+
+</PRE><H3><a name="h3-color_content">color_content</a></H3><PRE>
+       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 com-
+       ponents in the given color.
+
+       <STRONG>o</STRONG>   The first argument must be a legal color  value,  i.e.,  <STRONG>0</STRONG>  through
+           <STRONG>COLORS-1</STRONG>, inclusive.
+
+       <STRONG>o</STRONG>   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.
 
 
+</PRE><H3><a name="h3-pair_content">pair_content</a></H3><PRE>
+       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.
 
+       <STRONG>o</STRONG>   The first argument must be a legal color value, i.e., in the  range
+           <STRONG>1</STRONG> through <STRONG>COLOR_PAIRS-1</STRONG>, inclusive.
 
+       <STRONG>o</STRONG>   The  values that are stored at the addresses pointed to by the sec-
+           ond and third arguments are in the range <STRONG>0</STRONG> through  <STRONG>COLORS</STRONG>,  inclu-
+           sive.
 
 
+</PRE><H3><a name="h3-PAIR_NUMBER">PAIR_NUMBER</a></H3><PRE>
+       <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.
 
 
+</PRE><H3><a name="h3-COLOR_PAIR">COLOR_PAIR</a></H3><PRE>
+       Its inverse <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number to an attribute.
+       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 functions such as <STRONG>attrset</STRONG>.
 
 
+</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>.
 
+       All other routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG>  (SVr4
+       specifies  only "an integer value other than <STRONG>ERR</STRONG>") upon successful com-
+       pletion.
 
+       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 <STRONG>COLORS</STRONG>-1
+       (except for the default colors extension), or use color  pairs  outside
+       the  range <STRONG>0</STRONG> to <STRONG>COLOR_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 functions 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  <STRONG>initialize_color</STRONG>  capability is absent from the
+               terminal description.
 
+          <STRONG>start_color</STRONG>
+               returns an error if the color table cannot be allocated.
 
 
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+       In the <STRONG>ncurses</STRONG> implementation, there is  a  separate  color  activation
+       flag,  color palette, color pairs table, and associated <STRONG>COLORS</STRONG> and <STRONG>COL-</STRONG>
+       <STRONG>OR_PAIRS</STRONG> 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  shared
+       color palette.
 
+       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 or scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
 
+       Several caveats apply on older x86 machines  (e.g.,  i386,  i486)  with
+       VGA-compatible graphics:
 
+       <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 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).
 
+       <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 maximums for  <STRONG>COLORS</STRONG>
+       and <STRONG>COLOR_PAIRS</STRONG>.
 
+       The  <STRONG>init_pair</STRONG>  routine accepts negative values of foreground and back-
+       ground color to support the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></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><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG>  exten-
+       sion.
 
+       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 pa-
+       rameters when null.
 
+       X/Open  Curses  does  not  specify a limit for the number of colors and
+       color pairs which a terminal can support.  However, in its use of <STRONG>short</STRONG>
+       for  the  parameters,  it carries over SVr4's implementation detail for
+       the compiled terminfo database, which uses signed 16-bit numbers.  This
+       implementation  provides extended versions of those functions which use
+       <STRONG>short</STRONG> parameters, allowing applications to use larger color- and  pair-
+       numbers.
 
+       The <STRONG>reset_color_pairs</STRONG> function is an extension of ncurses.
 
 
+</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><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>de-</STRONG>
+       <STRONG><A HREF="default_colors.3x.html">fault_colors(3x)</A></STRONG>
 
 
 
+                                                                <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
 </PRE>
-<HR>
-<ADDRESS>
-Man(1) output converted with
-<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
-</ADDRESS>
+<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>
+</ul>
+</li>
+<li><a href="#h2-CONSTANTS">CONSTANTS</a></li>
+<li><a href="#h2-VARIABLES">VARIABLES</a>
+<ul>
+<li><a href="#h3-COLORS">COLORS</a></li>
+<li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li>
+</ul>
+</li>
+<li><a href="#h2-FUNCTIONS">FUNCTIONS</a>
+<ul>
+<li><a href="#h3-start_color">start_color</a></li>
+<li><a href="#h3-has_colors">has_colors</a></li>
+<li><a href="#h3-can_change_color">can_change_color</a></li>
+<li><a href="#h3-init_pair">init_pair</a></li>
+<li><a href="#h3-init_color">init_color</a></li>
+<li><a href="#h3-color_content">color_content</a></li>
+<li><a href="#h3-pair_content">pair_content</a></li>
+<li><a href="#h3-PAIR_NUMBER">PAIR_NUMBER</a></li>
+<li><a href="#h3-COLOR_PAIR">COLOR_PAIR</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>