5ff2f5f949488853b87ecf1b33158e8f1a69c265
[ncurses.git] / doc / html / man / curs_color.3x.html
1 <!-- 
2   ****************************************************************************
3   * Copyright (c) 1998-2010,2015 Free Software Foundation, Inc.              *
4   *                                                                          *
5   * Permission is hereby granted, free of charge, to any person obtaining a  *
6   * copy of this software and associated documentation files (the            *
7   * "Software"), to deal in the Software without restriction, including      *
8   * without limitation the rights to use, copy, modify, merge, publish,      *
9   * distribute, distribute with modifications, sublicense, and/or sell       *
10   * copies of the Software, and to permit persons to whom the Software is    *
11   * furnished to do so, subject to the following conditions:                 *
12   *                                                                          *
13   * The above copyright notice and this permission notice shall be included  *
14   * in all copies or substantial portions of the Software.                   *
15   *                                                                          *
16   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
17   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
18   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
19   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
20   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
21   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
22   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
23   *                                                                          *
24   * Except as contained in this notice, the name(s) of the above copyright   *
25   * holders shall not be used in advertising or otherwise to promote the     *
26   * sale, use or other dealings in this Software without prior written       *
27   * authorization.                                                           *
28   ****************************************************************************
29   * @Id: curs_color.3x,v 1.37 2015/04/04 19:42:47 tom Exp @
30 -->
31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
32 <HTML>
33 <HEAD>
34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
35 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
36 <TITLE>curs_color 3x</TITLE>
37 <link rev=made href="mailto:bug-ncurses@gnu.org">
38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
39 </HEAD>
40 <BODY>
41 <H1 class="no-header">curs_color 3x</H1>
42 <PRE>
43 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>                                           <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
44
45
46
47
48 </PRE>
49 <H2><a name="h2-NAME">NAME</a></H2><PRE>
50        <STRONG>start_color</STRONG>, <STRONG>init_pair</STRONG>, <STRONG>init_color</STRONG>, <STRONG>has_colors</STRONG>,
51        <STRONG>can_change_color</STRONG>, <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>, <STRONG>COLOR_PAIR</STRONG>
52        - <STRONG>curses</STRONG> color manipulation routines
53
54
55 </PRE>
56 <H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
57        <STRONG>#</STRONG> <STRONG>include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
58
59        <STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
60        <STRONG>int</STRONG> <STRONG>init_pair(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>f,</STRONG> <STRONG>short</STRONG> <STRONG>b);</STRONG>
61        <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>
62        <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
63        <STRONG>bool</STRONG> <STRONG>can_change_color(void);</STRONG>
64        <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>
65        <STRONG>*b);</STRONG>
66        <STRONG>int</STRONG> <STRONG>pair_content(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>*f,</STRONG> <STRONG>short</STRONG> <STRONG>*b);</STRONG>
67
68
69 </PRE>
70 <H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
71
72 </PRE>
73 <H3><a name="h3-Overview">Overview</a></H3><PRE>
74        <STRONG>curses</STRONG> support color attributes on terminals with that ca-
75        pability.   To  use  these  routines  <STRONG>start_color</STRONG>  must be
76        called, usually right after <STRONG>initscr</STRONG>.   Colors  are  always
77        used  in pairs (referred to as color-pairs).  A color-pair
78        consists of a foreground  color  (for  characters)  and  a
79        background color (for the blank field on which the charac-
80        ters are displayed).  A programmer  initializes  a  color-
81        pair  with  the routine <STRONG>init_pair</STRONG>.  After it has been ini-
82        tialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>), a macro  defined  in  <STRONG>&lt;curses.h&gt;</STRONG>,
83        can be used as a new video attribute.
84
85        If  a  terminal  is capable of redefining colors, the pro-
86        grammer can use the routine <STRONG>init_color</STRONG> to change the defi-
87        nition   of   a   color.    The  routines  <STRONG>has_colors</STRONG>  and
88        <STRONG>can_change_color</STRONG>  return  <STRONG>TRUE</STRONG>  or  <STRONG>FALSE</STRONG>,  depending   on
89        whether  the  terminal  has color capabilities and whether
90        the programmer can change the colors.   The  routine  <STRONG>col-</STRONG>
91        <STRONG>or_content</STRONG>  allows  a programmer to extract the amounts of
92        red, green, and blue components in an  initialized  color.
93        The  routine  <STRONG>pair_content</STRONG> allows a programmer to find out
94        how a given color-pair is currently defined.
95
96
97 </PRE>
98 <H3><a name="h3-Routine-Descriptions">Routine Descriptions</a></H3><PRE>
99        The <STRONG>start_color</STRONG> routine requires no arguments.  It must be
100        called  if  the programmer wants to use colors, and before
101        any other color manipulation routine  is  called.   It  is
102        good  practice  to  call this routine right after <STRONG>initscr</STRONG>.
103        <STRONG>start_color</STRONG> does this:
104
105        <STRONG>o</STRONG>   It initializes two global variables, <STRONG>COLORS</STRONG>  and  <STRONG>COL-</STRONG>
106            <STRONG>OR_PAIRS</STRONG>  (respectively defining the maximum number of
107            colors and color-pairs the terminal can support).
108
109        <STRONG>o</STRONG>   It initializes the special color pair <STRONG>0</STRONG> to the default
110            foreground  and  background  colors.   No  other color
111            pairs are initialized.
112
113        <STRONG>o</STRONG>   It restores the colors on the terminal to  the  values
114            they had when the terminal was just turned on.
115
116        <STRONG>o</STRONG>   If  the terminal supports the <STRONG>initc</STRONG> (<STRONG>initialize_color</STRONG>)
117            capability, <STRONG>start_color</STRONG> initializes its internal table
118            representing the red, green and blue components of the
119            color palette.
120
121            The components depend on whether the terminal uses CGA
122            (aka "ANSI") or HLS (i.e., the <STRONG>hls</STRONG> (<STRONG>hue_lightness_sat-</STRONG>
123            <STRONG>uration</STRONG>) capability is set).  The table is initialized
124            first  for eight basic colors (black, red, green, yel-
125            low, blue, magenta, cyan, and white), and  after  that
126            (if  the terminal supports more than eight colors) the
127            components are initialized to <STRONG>1000</STRONG>.
128
129            <STRONG>start_color</STRONG> does not attempt  to  set  the  terminal's
130            color  palette to match its built-in table.  An appli-
131            cation may use <STRONG>init_color</STRONG> to alter the internal  table
132            along with the terminal's color.
133
134        These  limits apply to color values and color pairs.  Val-
135        ues outside these limits are not legal, and may result  in
136        a runtime error:
137
138        <STRONG>o</STRONG>   <STRONG>COLORS</STRONG> corresponds to the terminal database's <STRONG>max_col-</STRONG>
139            <STRONG>ors</STRONG> capability, which is typically a signed 16-bit in-
140            teger (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
141
142        <STRONG>o</STRONG>   color values are expected to be in the range <STRONG>0</STRONG> to <STRONG>COL-</STRONG>
143            <STRONG>ORS-1</STRONG>, inclusive (including <STRONG>0</STRONG> and <STRONG>COLORS-1</STRONG>).
144
145        <STRONG>o</STRONG>   a special color value <STRONG>-1</STRONG> is used in  certain  extended
146            functions  to  denote  the  <EM>default</EM> <EM>color</EM> (see <STRONG>use_de-</STRONG>
147            <STRONG>fault_colors</STRONG>).
148
149        <STRONG>o</STRONG>   <STRONG>COLOR_PAIRS</STRONG> corresponds  to  the  terminal  database's
150            <STRONG>max_pairs</STRONG>  capability,  which  is  typically  a signed
151            16-bit integer (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>).
152
153        <STRONG>o</STRONG>   legal color pair values are in the  range  <STRONG>1</STRONG>  to  <STRONG>COL-</STRONG>
154            <STRONG>OR_PAIRS-1</STRONG>, inclusive.
155
156        <STRONG>o</STRONG>   color pair <STRONG>0</STRONG> is special; it denotes "no color".
157
158            Color  pair  <STRONG>0</STRONG> is assumed to be white on black, but is
159            actually whatever the terminal implements before color
160            is initialized.  It cannot be modified by the applica-
161            tion.
162
163        The <STRONG>init_pair</STRONG> routine changes the definition of  a  color-
164        pair.   It takes three arguments: the number of the color-
165        pair to be changed, the foreground color number,  and  the
166        background color number.  For portable applications:
167
168        <STRONG>o</STRONG>   The  first  argument must be a legal color pair value.
169            If default colors are  used  (see  <STRONG>use_default_colors</STRONG>)
170            the  upper  limit is adjusted to allow for extra pairs
171            which use a default color in foreground  and/or  back-
172            ground.
173
174        <STRONG>o</STRONG>   The  second  and  third  arguments must be legal color
175            values.
176
177        If the color-pair was previously initialized,  the  screen
178        is  refreshed  and  all occurrences of that color-pair are
179        changed to the new definition.
180
181        As an extension, ncurses allows you to set  color  pair  <STRONG>0</STRONG>
182        via  the  <STRONG>assume_default_colors</STRONG> routine, or to specify the
183        use of default colors (color number <STRONG>-1</STRONG>) if you  first  in-
184        voke the <STRONG>use_default_colors</STRONG> routine.
185
186        The  <STRONG>init_color</STRONG> routine changes the definition of a color.
187        It takes four arguments: the number of  the  color  to  be
188        changed  followed  by three RGB values (for the amounts of
189        red, green, and blue components).  The first argument must
190        be  a  legal  color  value; default colors are not allowed
191        here.  (See the section <STRONG>Colors</STRONG> for the default  color  in-
192        dex.)  Each of the last three arguments must be a value in
193        the range <STRONG>0</STRONG> through <STRONG>1000</STRONG>.  When <STRONG>init_color</STRONG>  is  used,  all
194        occurrences of that color on the screen immediately change
195        to the new definition.
196
197        The <STRONG>has_colors</STRONG> routine requires no arguments.  It  returns
198        <STRONG>TRUE</STRONG>  if the terminal can manipulate colors; otherwise, it
199        returns <STRONG>FALSE</STRONG>.  This routine facilitates writing terminal-
200        independent  programs.   For example, a programmer can use
201        it to decide whether to use color or some other video  at-
202        tribute.
203
204        The  <STRONG>can_change_color</STRONG>  routine  requires no arguments.  It
205        returns <STRONG>TRUE</STRONG> if  the  terminal  supports  colors  and  can
206        change  their  definitions; other, it returns <STRONG>FALSE</STRONG>.  This
207        routine facilitates writing terminal-independent programs.
208
209        The <STRONG>color_content</STRONG> routine gives programmers a way to  find
210        the intensity of the red, green, and blue (RGB) components
211        in a color.  It requires four arguments: the color number,
212        and  three addresses of <STRONG>short</STRONG>s for storing the information
213        about the amounts of red, green, and  blue  components  in
214        the given color.  The first argument must be a legal color
215        value, i.e., <STRONG>0</STRONG> through <STRONG>COLORS-1</STRONG>,  inclusive.   The  values
216        that  are  stored  at the addresses pointed to by the last
217        three arguments are in the range <STRONG>0</STRONG> (no component)  through
218        <STRONG>1000</STRONG> (maximum amount of component), inclusive.
219
220        The  <STRONG>pair_content</STRONG>  routine  allows programmers to find out
221        what colors a given color-pair consists of.   It  requires
222        three  arguments: the color-pair number, and two addresses
223        of <STRONG>short</STRONG>s for storing the foreground  and  the  background
224        color  numbers.   The first argument must be a legal color
225        value, i.e., in the range <STRONG>1</STRONG> through <STRONG>COLOR_PAIRS-1</STRONG>,  inclu-
226        sive.  The values that are stored at the addresses pointed
227        to by the second and third arguments are in  the  range  <STRONG>0</STRONG>
228        through <STRONG>COLORS</STRONG>, inclusive.
229
230
231 </PRE>
232 <H3><a name="h3-Colors">Colors</a></H3><PRE>
233        In <STRONG>&lt;curses.h&gt;</STRONG> the following macros are defined.  These are
234        the default colors.  <STRONG>curses</STRONG> also assumes that  <STRONG>COLOR_BLACK</STRONG>
235        is the default background color for all terminals.
236
237              <STRONG>COLOR_BLACK</STRONG>
238              <STRONG>COLOR_RED</STRONG>
239              <STRONG>COLOR_GREEN</STRONG>
240              <STRONG>COLOR_YELLOW</STRONG>
241              <STRONG>COLOR_BLUE</STRONG>
242              <STRONG>COLOR_MAGENTA</STRONG>
243              <STRONG>COLOR_CYAN</STRONG>
244              <STRONG>COLOR_WHITE</STRONG>
245
246
247 </PRE>
248 <H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
249        The  routines  <STRONG>can_change_color()</STRONG>  and <STRONG>has_colors()</STRONG> return
250        <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
251
252        All other routines return the integer <STRONG>ERR</STRONG> upon failure and
253        an  <STRONG>OK</STRONG>  (SVr4  specifies only "an integer value other than
254        <STRONG>ERR</STRONG>") upon successful completion.
255
256        X/Open defines no error conditions.   This  implementation
257        will  return  <STRONG>ERR</STRONG>  on attempts to use color values outside
258        the range <STRONG>0</STRONG> to COLORS-1 (except for the default colors ex-
259        tension),  or  use color pairs outside the range <STRONG>0</STRONG> to <STRONG>COL-</STRONG>
260        <STRONG>OR_PAIRS-1</STRONG>.  Color values used in <STRONG>init_color</STRONG>  must  be  in
261        the  range <STRONG>0</STRONG> to <STRONG>1000</STRONG>.  An error is returned from all func-
262        tions if the terminal has not been initialized.  An  error
263        is  returned from secondary functions such as <STRONG>init_pair</STRONG> if
264        <STRONG>start_color</STRONG> was not called.
265
266           <STRONG>init_color</STRONG>
267                returns an error if the terminal does not  support
268                this  feature, e.g., if the <EM>initialize</EM><STRONG>_</STRONG><EM>color</EM> capa-
269                bility is absent from the terminal description.
270
271           <STRONG>start_color</STRONG>
272                returns an error if the color table cannot be  al-
273                located.
274
275
276 </PRE>
277 <H2><a name="h2-NOTES">NOTES</a></H2><PRE>
278        In  the  <EM>ncurses</EM> implementation, there is a separate color
279        activation flag, color palette, color pairs table, and as-
280        sociated  COLORS  and  COLOR_PAIRS counts for each screen;
281        the <STRONG>start_color</STRONG> function only affects the current  screen.
282        The SVr4/XSI interface is not really designed with this in
283        mind, and historical  implementations  may  use  a  single
284        shared color palette.
285
286        Note that setting an implicit background color via a color
287        pair affects only character cells that a  character  write
288        operation  explicitly  touches.   To change the background
289        color used when parts of a window are blanked  by  erasing
290        or scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
291
292        Several  caveats  apply  on 386 and 486 machines with VGA-
293        compatible graphics:
294
295        <STRONG>o</STRONG>   COLOR_YELLOW is actually brown.  To  get  yellow,  use
296            COLOR_YELLOW combined with the <STRONG>A_BOLD</STRONG> attribute.
297
298        <STRONG>o</STRONG>   The A_BLINK attribute should in theory cause the back-
299            ground to go bright.  This often fails  to  work,  and
300            even some cards for which it mostly works (such as the
301            Paradise and compatibles) do the wrong thing when  you
302            try  to  set  a  bright "yellow" background (you get a
303            blinking yellow foreground instead).
304
305        <STRONG>o</STRONG>   Color RGB values are not settable.
306
307
308 </PRE>
309 <H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
310        This implementation satisfies XSI Curses's  minimum  maxi-
311        mums for <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG>.
312
313        The  <STRONG>init_pair</STRONG>  routine  accepts  negative values of fore-
314        ground  and  background  color  to  support  the   <STRONG>use_de-</STRONG>
315        <STRONG>fault_colors</STRONG>  extension, but only if that routine has been
316        first invoked.
317
318        The assumption that <STRONG>COLOR_BLACK</STRONG> is the default  background
319        color  for  all  terminals  can  be modified using the <STRONG>as-</STRONG>
320        <STRONG>sume_default_colors</STRONG> extension.
321
322        This implementation checks the  pointers,  e.g.,  for  the
323        values  returned  by  <STRONG>color_content</STRONG>  and <STRONG>pair_content</STRONG>, and
324        will treat those as optional parameters when null.
325
326
327 </PRE>
328 <H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
329        <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>
330        <STRONG><A HREF="curs_variables.3x.html">ables(3x)</A></STRONG>, <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>
331
332
333
334                                                          <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
335 </PRE>
336 <div class="nav">
337 <ul>
338 <li><a href="#h2-NAME">NAME</a></li>
339 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
340 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
341 <ul>
342 <li><a href="#h3-Overview">Overview</a></li>
343 <li><a href="#h3-Routine-Descriptions">Routine Descriptions</a></li>
344 <li><a href="#h3-Colors">Colors</a></li>
345 </ul>
346 </li>
347 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
348 <li><a href="#h2-NOTES">NOTES</a></li>
349 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
350 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
351 </ul>
352 </div>
353 </BODY>
354 </HTML>