4 <!-- Manpage converted by man2html 3.0.1 -->
8 <B>start_color</B>, <B>init_pair</B>, <B>init_color</B>, <B>has_colors</B>,
9 <B>can_change_color</B>, <B>color_content</B>, <B>pair_content</B>, <B>COLOR_PAIR</B>
10 - <B>curses</B> color manipulation routines
14 <H2>SYNOPSIS</H2><PRE>
15 <B>#</B> <B>include</B> <B><curses.h></B>
16 <B>int</B> <B>start_color(void);</B>
17 <B>int</B> <B>init_pair(short</B> <B>pair,</B> <B>short</B> <B>f,</B> <B>short</B> <B>b);</B>
18 <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>
19 <B>bool</B> <B>has_colors(void);</B>
20 <B>bool</B> <B>can_change_color(void);</B>
21 <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>
23 <B>int</B> <B>pair_content(short</B> <B>pair,</B> <B>short</B> <B>*f,</B> <B>short</B> <B>*b);</B>
27 <H2>DESCRIPTION</H2><PRE>
29 <B>curses</B> support color attributes on terminals with that
30 capability. To use these routines <B>start_color</B> must be
31 called, usually right after <B>initscr</B>. Colors are always
32 used in pairs (referred to as color-pairs). A color-pair
33 consists of a foreground color (for characters) and a
34 background color (for the blank field on which the charac-
35 ters are displayed). A programmer initializes a color-
36 pair with the routine <B>init_pair</B>. After it has been ini-
37 tialized, <B>COLOR_PAIR</B>(<I>n</I>), a macro defined in <B><curses.h></B>,
38 can be used as a new video attribute.
40 If a terminal is capable of redefining colors, the pro-
41 grammer can use the routine <B>init_color</B> to change the defi-
42 nition of a color. The routines <B>has_colors</B> and
43 <B>can_change_color</B> return <B>TRUE</B> or <B>FALSE</B>, depending on
44 whether the terminal has color capabilities and whether
45 the programmer can change the colors. The routine
46 <B>color_content</B> allows a programmer to extract the amounts
47 of red, green, and blue components in an initialized
48 color. The routine <B>pair_content</B> allows a programmer to
49 find out how a given color-pair is currently defined.
51 <B>Routine</B> <B>Descriptions</B>
52 The <B>start_color</B> routine requires no arguments. It must be
53 called if the programmer wants to use colors, and before
54 any other color manipulation routine is called. It is
55 good practice to call this routine right after <B>initscr</B>.
56 <B>start_color</B> initializes eight basic colors (black, red,
57 green, yellow, blue, magenta, cyan, and white), and two
58 global variables, <B>COLORS</B> and <B>COLOR_PAIRS</B> (respectively
59 defining the maximum number of colors and color-pairs the
60 terminal can support). It also restores the colors on the
61 terminal to the values they had when the terminal was just
64 The <B>init_pair</B> routine changes the definition of a color-
65 pair. It takes three arguments: the number of the color-
66 pair to be changed, the foreground color number, and the
67 background color number. For portable applications:
69 - The value of the first argument must be between <B>1</B> and
72 - The value of the second and third arguments must be
73 between 0 and <B>COLORS</B> (the 0 color pair is wired to
74 white on black and cannot be changed).
76 If the color-pair was previously initialized, the screen
77 is refreshed and all occurrences of that color-pair is
78 changed to the new definition.
80 As an extension, ncurses allows you to set color pair 0
81 via the <B>assume_default_colors</B> routine, or to specify the
82 use of default colors (color number <B>-1</B>) if you first
83 invoke the <B>use_default_colors</B> routine.
85 The <B>init_color</B> routine changes the definition of a color.
86 It takes four arguments: the number of the color to be
87 changed followed by three RGB values (for the amounts of
88 red, green, and blue components). The value of the first
89 argument must be between <B>0</B> and <B>COLORS</B>. (See the section
90 <B>Colors</B> for the default color index.) Each of the last
91 three arguments must be a value between 0 and 1000. When
92 <B>init_color</B> is used, all occurrences of that color on the
93 screen immediately change to the new definition.
95 The <B>has_colors</B> routine requires no arguments. It returns
96 <B>TRUE</B> if the terminal can manipulate colors; otherwise, it
97 returns <B>FALSE</B>. This routine facilitates writing terminal-
98 independent programs. For example, a programmer can use
99 it to decide whether to use color or some other video
102 The <B>can_change_color</B> routine requires no arguments. It
103 returns <B>TRUE</B> if the terminal supports colors and can
104 change their definitions; other, it returns <B>FALSE</B>. This
105 routine facilitates writing terminal-independent programs.
107 The <B>color_content</B> routine gives programmers a way to find
108 the intensity of the red, green, and blue (RGB) components
109 in a color. It requires four arguments: the color number,
110 and three addresses of <B>short</B>s for storing the information
111 about the amounts of red, green, and blue components in
112 the given color. The value of the first argument must be
113 between 0 and <B>COLORS</B>. The values that are stored at the
114 addresses pointed to by the last three arguments are
115 between 0 (no component) and 1000 (maximum amount of com-
118 The <B>pair_content</B> routine allows programmers to find out
119 what colors a given color-pair consists of. It requires
120 three arguments: the color-pair number, and two addresses
121 of <B>short</B>s for storing the foreground and the background
122 color numbers. The value of the first argument must be
123 between 1 and <B>COLOR_PAIRS-1</B>. The values that are stored
124 at the addresses pointed to by the second and third argu-
125 ments are between 0 and <B>COLORS</B>.
128 In <B><curses.h></B> the following macros are defined. These are
129 the default colors. <B>curses</B> also assumes that <B>COLOR_BLACK</B>
130 is the default background color for all terminals.
143 <H2>RETURN VALUE</H2><PRE>
144 The routines <B>can_change_color()</B> and <B>has_colors()</B> return
145 <B>TRUE</B> or <B>FALSE</B>.
147 All other routines return the integer <B>ERR</B> upon failure and
148 an <B>OK</B> (SVr4 specifies only "an integer value other than
149 <B>ERR</B>") upon successful completion.
154 In the <I>ncurses</I> implementation, there is a separate color
155 activation flag, color palette, color pairs table, and
156 associated COLORS and COLOR_PAIRS counts for each screen;
157 the <B>start_color</B> function only affects the current screen.
158 The SVr4/XSI interface is not really designed with this in
159 mind, and historical implementations may use a single
160 shared color palette.
162 Note that setting an implicit background color via a color
163 pair affects only character cells that a character write
164 operation explicitly touches. To change the background
165 color used when parts of a window are blanked by erasing
166 or scrolling operations, see <B><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></B>.
168 Several caveats apply on 386 and 486 machines with VGA-
171 - COLOR_YELLOW is actually brown. To get yellow, use
172 COLOR_YELLOW combined with the <B>A_BOLD</B> attribute.
174 - The A_BLINK attribute should in theory cause the
175 background to go bright. This often fails to work,
176 and even some cards for which it mostly works (such
177 as the Paradise and compatibles) do the wrong thing
178 when you try to set a bright "yellow" background (you
179 get a blinking yellow foreground instead).
181 - Color RGB values are not settable.
185 <H2>PORTABILITY</H2><PRE>
186 This implementation satisfies XSI Curses's minimum maxi-
187 mums for <B>COLORS</B> and <B>COLOR_PAIRS</B>.
189 The <B>init_pair</B> routine accepts negative values of fore-
190 ground and background color to support the
191 <B>use_default_colors</B> extension, but only if that routine has
194 The assumption that <B>COLOR_BLACK</B> is the default background
195 color for all terminals can be modified using the
196 <B>assume_default_colors</B> extension,
200 <H2>SEE ALSO</H2><PRE>
201 <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>default_col-</B>
202 <B><A HREF="ors.3x.html">ors(3x)</A></B>
238 Man(1) output converted with
239 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>