+
+</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 terminal 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 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
+ a runtime error:
+
+ <STRONG>o</STRONG> <STRONG>COLORS</STRONG> corresponds to the terminal database's <STRONG>max_col-</STRONG>
+ <STRONG>ors</STRONG> capability, (see <STRONG><A HREF="max_colterminfo.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, (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.
+
+
+</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 routine facilitates writing terminal-
+ independent programs. For example, a programmer can use
+ it to decide whether to use color or some other video at-
+ tribute.
+
+
+</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-independent 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 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-
+ ground.
+
+ <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 <STRONG>0</STRONG>
+ via the <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG> routine, or to specify
+ the use of default colors (color number <STRONG>-1</STRONG>) if you first
+ invoke the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG> routine.
+
+
+</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; de-
+ fault 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 components 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 second and third arguments are in the range <STRONG>0</STRONG>
+ through <STRONG>COLORS</STRONG>, inclusive.
+
+
+</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 completion.
+
+ 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 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