ncurses 5.9 - patch 20150214
[ncurses.git] / doc / html / man / curs_color.3x.html
index 4ebe0da04f4db20520b1216d40b66cfefe71c61b..cb101f5fb89706ec22c6d89d15418d4d6af061b5 100644 (file)
@@ -1,4 +1,3 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
 <!-- 
   ****************************************************************************
   * Copyright (c) 1998-2009,2010 Free Software Foundation, Inc.              *
   * sale, use or other dealings in this Software without prior written       *
   * authorization.                                                           *
   ****************************************************************************
-  * @Id: curs_color.3x,v 1.35 2010/12/20 00:50:58 tom Exp @
+  * @Id: curs_color.3x,v 1.36 2014/11/16 00:44:29 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">
 <H1>curs_color 3x</H1>
 <HR>
 <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>
 
 
 </PRE>
-<H2>DESCRIPTION</H2><PRE>
-   <STRONG>Overview</STRONG>
+<H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+
+</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
        called, usually right after <STRONG>initscr</STRONG>.   Colors  are  always
@@ -91,7 +94,9 @@
        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-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
        terminal to the values they had when the terminal was just
        turned on.
 
-       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
+       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>ors</STRONG> capability, which is typically a signed 16-bit in-
+           teger (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>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>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
+           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>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
+           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
        background color number.  For portable applications:
 
-       <STRONG>o</STRONG>   The  value of the first argument must be between <STRONG>1</STRONG> and
-           <STRONG>COLOR_PAIRS-1</STRONG>, except that 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 background.
+       <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  value  of  the second and third arguments must be
-           between 0 and <STRONG>COLORS</STRONG>.  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.
+       <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 definition.
 
-       As  an  extension,  ncurses allows you to set color pair 0
+       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
-       red,  green, and blue components).  The value of the first
-       argument must be between <STRONG>0</STRONG> and <STRONG>COLORS</STRONG>.  (See  the  section
-       <STRONG>Colors</STRONG>  for  the  default  color index.)  Each of the last
-       three arguments must be a value between 0 and 1000.   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
+       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-
+       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
+       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
        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
-       the  given color.  The value of the first argument must be
-       between 0 and <STRONG>COLORS</STRONG>.  The values that are stored  at  the
-       addresses  pointed  to by the last three arguments are be-
-       tween 0 (no component) and 1000 (maximum amount of  compo-
-       nent).
-
-       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  value of the first argument must be
-       between 1 and <STRONG>COLOR_PAIRS-1</STRONG>.  The values that  are  stored
-       at  the addresses pointed to by the second and third argu-
-       ments are between 0 and <STRONG>COLORS</STRONG>.
-
-   <STRONG>Colors</STRONG>
+       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
+       <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-
+       sive.  The values that are stored at the addresses pointed
+       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.
 
 
 </PRE>
-<H2>RETURN VALUE</H2><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>.
 
 
        X/Open  defines  no error conditions.  This implementation
        will return <STRONG>ERR</STRONG> 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_PAIRS-1.   Color  values  used in <STRONG>init_color</STRONG> must be in
-       the range 0 to 1000.  An error is returned from all  func-
+       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
        <STRONG>start_color</STRONG> was not called.
 
 
 </PRE>
-<H2>NOTES</H2><PRE>
+<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;
 
 
 </PRE>
-<H2>PORTABILITY</H2><PRE>
+<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>.
 
 
 
 </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>
-<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-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>