-</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
- 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 charac-
- ters are displayed). A programmer initializes a color-
- pair with the routine <STRONG>init_pair</STRONG>. After it has been ini-
- tialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>), a macro defined in <STRONG><curses.h></STRONG>,
- can be used as a new video attribute.
-
- If a terminal is capable of redefining colors, the pro-
- grammer can use the routine <STRONG>init_color</STRONG> to change the defi-
- nition of a color. The routines <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 programmer can change the colors. The routine <STRONG>col-</STRONG>
- <STRONG>or_content</STRONG> allows a programmer 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.
-
- <STRONG>Routine</STRONG> <STRONG>Descriptions</STRONG>
- 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.
-
- 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 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.
-
- 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
- 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
- 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.
-
- 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 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>
- In <STRONG><curses.h></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.
+ <STRONG>int</STRONG> <STRONG>color_content(short</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>r</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>g</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>b</EM><STRONG>);</STRONG>
+ <STRONG>int</STRONG> <STRONG>pair_content(short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>f</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG><EM>b</EM><STRONG>);</STRONG>
+ /* extensions */
+ <STRONG>int</STRONG> <STRONG>extended_color_content(int</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>r</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>g</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>b</EM><STRONG>);</STRONG>
+ <STRONG>int</STRONG> <STRONG>extended_pair_content(int</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>f</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>b</EM><STRONG>);</STRONG>
+
+ /* extensions */
+ <STRONG>void</STRONG> <STRONG>reset_color_pairs(void);</STRONG>
+
+ <STRONG>int</STRONG> <STRONG>COLOR_PAIR(int</STRONG> <EM>n</EM><STRONG>);</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.
+
+
+</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:
+
+ <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 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.
+
+ 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 uses 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 attribute.
+
+ <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 attri-
+ bute next, and finally the background character.
+
+ 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.
+
+
+</PRE><H2><a name="h2-CONSTANTS">CONSTANTS</a></H2><PRE>
+ In <STRONG><curses.h></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.