ncurses 5.5
[ncurses.git] / doc / html / man / curs_color.3x.html
1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
2 <!-- 
3   ****************************************************************************
4   * Copyright (c) 1998-2004,2005 Free Software Foundation, Inc.              *
5   *                                                                          *
6   * Permission is hereby granted, free of charge, to any person obtaining a  *
7   * copy of this software and associated documentation files (the            *
8   * "Software"), to deal in the Software without restriction, including      *
9   * without limitation the rights to use, copy, modify, merge, publish,      *
10   * distribute, distribute with modifications, sublicense, and/or sell       *
11   * copies of the Software, and to permit persons to whom the Software is    *
12   * furnished to do so, subject to the following conditions:                 *
13   *                                                                          *
14   * The above copyright notice and this permission notice shall be included  *
15   * in all copies or substantial portions of the Software.                   *
16   *                                                                          *
17   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
18   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
19   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
20   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
21   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
22   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
23   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
24   *                                                                          *
25   * Except as contained in this notice, the name(s) of the above copyright   *
26   * holders shall not be used in advertising or otherwise to promote the     *
27   * sale, use or other dealings in this Software without prior written       *
28   * authorization.                                                           *
29   ****************************************************************************
30   * @Id: curs_color.3x,v 1.27 2005/05/15 16:55:36 tom Exp @
31 -->
32 <HTML>
33 <HEAD>
34 <TITLE>curs_color 3x</TITLE>
35 <link rev=made href="mailto:bug-ncurses@gnu.org">
36 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
37 </HEAD>
38 <BODY>
39 <H1>curs_color 3x</H1>
40 <HR>
41 <PRE>
42 <!-- Manpage converted by man2html 3.0.1 -->
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>NAME</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>SYNOPSIS</H2><PRE>
57        <STRONG>#</STRONG> <STRONG>include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
58        <STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
59        <STRONG>int</STRONG> <STRONG>init_pair(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>f,</STRONG> <STRONG>short</STRONG> <STRONG>b);</STRONG>
60        <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>
61        <STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
62        <STRONG>bool</STRONG> <STRONG>can_change_color(void);</STRONG>
63        <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>
64        <STRONG>*b);</STRONG>
65        <STRONG>int</STRONG> <STRONG>pair_content(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>*f,</STRONG> <STRONG>short</STRONG> <STRONG>*b);</STRONG>
66
67
68 </PRE>
69 <H2>DESCRIPTION</H2><PRE>
70    <STRONG>Overview</STRONG>
71        <STRONG>curses</STRONG> support color attributes on terminals with that ca-
72        pability.   To  use  these  routines  <STRONG>start_color</STRONG>  must be
73        called, usually right after <STRONG>initscr</STRONG>.   Colors  are  always
74        used  in pairs (referred to as color-pairs).  A color-pair
75        consists of a foreground  color  (for  characters)  and  a
76        background color (for the blank field on which the charac-
77        ters are displayed).  A programmer  initializes  a  color-
78        pair  with  the routine <STRONG>init_pair</STRONG>.  After it has been ini-
79        tialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>), a macro  defined  in  <STRONG>&lt;curses.h&gt;</STRONG>,
80        can  be  used  as a new video attribute.  If a terminal is
81        capable of redefining colors, the programmer can  use  the
82        routine  <STRONG>init_color</STRONG>  to  change the definition of a color.
83        The routines <STRONG>has_colors</STRONG> and <STRONG>can_change_color</STRONG>  return  <STRONG>TRUE</STRONG>
84        or  <STRONG>FALSE</STRONG>, depending on whether the terminal has color ca-
85        pabilities and whether the programmer can change the  col-
86        ors.  The routine <STRONG>color_content</STRONG> allows a programmer to ex-
87        tract the amounts of red, green, and blue components in an
88        initialized color.  The routine <STRONG>pair_content</STRONG> allows a pro-
89        grammer to find out how a given  color-pair  is  currently
90        defined.
91
92    <STRONG>Routine</STRONG> <STRONG>Descriptions</STRONG>
93        The <STRONG>start_color</STRONG> routine requires no arguments.  It must be
94        called if the programmer wants to use colors,  and  before
95        any  other  color  manipulation  routine is called.  It is
96        good practice to call this routine  right  after  <STRONG>initscr</STRONG>.
97        <STRONG>start_color</STRONG>  initializes  eight  basic colors (black, red,
98        green, yellow, blue, magenta, cyan, and  white),  and  two
99        global  variables,  <STRONG>COLORS</STRONG>  and  <STRONG>COLOR_PAIRS</STRONG> (respectively
100        defining the maximum number of colors and color-pairs  the
101        terminal can support).  It also restores the colors on the
102        terminal to the values they had when the terminal was just
103        turned  on.   The <STRONG>init_pair</STRONG> routine changes the definition
104        of a color-pair.  It takes three arguments: the number  of
105        the color-pair to be changed, the foreground color number,
106        and the background color number.   For  portable  applica-
107        tions:
108
109        -    The value of the first argument must be between <STRONG>1</STRONG> and
110             <STRONG>COLOR_PAIRS-1</STRONG>.
111
112        -    The value of the second and third arguments  must  be
113             between  0 and <STRONG>COLORS</STRONG>.  Color pair 0 is assumed to be
114             white on black, but is actually whatever the terminal
115             implements before color is initialized.  It cannot be
116             modified by the application.
117
118        If the color-pair was previously initialized,  the  screen
119        is  refreshed  and  all occurrences of that color-pair are
120        changed to the new definition.  As an  extension,  ncurses
121        allows you to set color pair 0 via the <STRONG>assume_default_col-</STRONG>
122        <STRONG>ors</STRONG> routine, or to specify the use of default colors (col-
123        or  number  <STRONG>-1</STRONG>) if you first invoke the <STRONG>use_default_colors</STRONG>
124        routine.  The <STRONG>init_color</STRONG> routine changes the definition of
125        a color.  It takes four arguments: the number of the color
126        to be changed  followed  by  three  RGB  values  (for  the
127        amounts of red, green, and blue components).  The value of
128        the first argument must be between <STRONG>0</STRONG> and <STRONG>COLORS</STRONG>.  (See the
129        section  <STRONG>Colors</STRONG> for the default color index.)  Each of the
130        last three arguments must be a value between 0  and  1000.
131        When  <STRONG>init_color</STRONG> is used, all occurrences of that color on
132        the screen immediately change to the new definition.   The
133        <STRONG>has_colors</STRONG> routine requires no arguments.  It returns <STRONG>TRUE</STRONG>
134        if the terminal can manipulate colors; otherwise,  it  re-
135        turns  <STRONG>FALSE</STRONG>.   This routine facilitates writing terminal-
136        independent programs.  For example, a programmer  can  use
137        it  to decide whether to use color or some other video at-
138        tribute.  The <STRONG>can_change_color</STRONG> routine requires  no  argu-
139        ments.   It  returns  <STRONG>TRUE</STRONG> if the terminal supports colors
140        and can change their definitions; other, it returns <STRONG>FALSE</STRONG>.
141        This routine facilitates writing terminal-independent pro-
142        grams.  The <STRONG>color_content</STRONG> routine gives programmers a  way
143        to  find  the  intensity of the red, green, and blue (RGB)
144        components in a color.  It requires  four  arguments:  the
145        color  number,  and  three addresses of <STRONG>short</STRONG>s for storing
146        the information about the amounts of red, green, and  blue
147        components in the given color.  The value of the first ar-
148        gument must be between 0 and <STRONG>COLORS</STRONG>.  The values that  are
149        stored at the addresses pointed to by the last three argu-
150        ments are between  0  (no  component)  and  1000  (maximum
151        amount  of  component).   The  <STRONG>pair_content</STRONG> routine allows
152        programmers to find out what  colors  a  given  color-pair
153        consists  of.  It requires three arguments: the color-pair
154        number, and two addresses of <STRONG>short</STRONG>s for storing the  fore-
155        ground and the background color numbers.  The value of the
156        first argument must be between 1 and  <STRONG>COLOR_PAIRS-1</STRONG>.   The
157        values  that are stored at the addresses pointed to by the
158        second and third arguments are between 0 and <STRONG>COLORS</STRONG>.
159
160    <STRONG>Colors</STRONG>
161        In <STRONG>&lt;curses.h&gt;</STRONG> the following macros are defined.  These are
162        the  default colors.  <STRONG>curses</STRONG> also assumes that <STRONG>COLOR_BLACK</STRONG>
163        is the default background color for all terminals.
164              <STRONG>COLOR_BLACK</STRONG>
165              <STRONG>COLOR_RED</STRONG>
166              <STRONG>COLOR_GREEN</STRONG>
167              <STRONG>COLOR_YELLOW</STRONG>
168              <STRONG>COLOR_BLUE</STRONG>
169              <STRONG>COLOR_MAGENTA</STRONG>
170              <STRONG>COLOR_CYAN</STRONG>
171              <STRONG>COLOR_WHITE</STRONG>
172
173
174 </PRE>
175 <H2>RETURN VALUE</H2><PRE>
176        The routines <STRONG>can_change_color()</STRONG>  and  <STRONG>has_colors()</STRONG>  return
177        <STRONG>TRUE</STRONG>  or <STRONG>FALSE</STRONG>.  All other routines return the integer <STRONG>ERR</STRONG>
178        upon failure and an <STRONG>OK</STRONG> (SVr4 specifies  only  "an  integer
179        value other than <STRONG>ERR</STRONG>") upon successful completion.
180
181        X/Open  defines  no error conditions.  This implementation
182        will return <STRONG>ERR</STRONG> on attempts to use  color  values  outside
183        the range 0 to COLORS-1 (except for the default colors ex-
184        tension), or use color pairs outside the range 0  to  COL-
185        OR_PAIR-1.  Color values used in <STRONG>init_color</STRONG> must be in the
186        range 0 to 1000.  An error is returned from all  functions
187        if the terminal has not been initialized.  An error is re-
188        turned from  secondary  functions  such  as  <STRONG>init_pair</STRONG>  if
189        <STRONG>start_color</STRONG> was not called.
190
191               <STRONG>init_color</STRONG>
192                    returns an error if the terminal does not sup-
193                    port  this  feature,  e.g.,  if  the  <EM>initial-</EM>
194                    <EM>ize</EM><STRONG>_</STRONG><EM>color</EM> capability is absent from the termi-
195                    nal description.
196
197               <STRONG>start_color</STRONG>
198                    returns an error If the color table cannot  be
199                    allocated.
200
201
202 </PRE>
203 <H2>NOTES</H2><PRE>
204        In  the  <EM>ncurses</EM> implementation, there is a separate color
205        activation flag, color palette, color pairs table, and as-
206        sociated  COLORS  and  COLOR_PAIRS counts for each screen;
207        the <STRONG>start_color</STRONG> function only affects the current  screen.
208        The SVr4/XSI interface is not really designed with this in
209        mind, and historical  implementations  may  use  a  single
210        shared color palette.  Note that setting an implicit back-
211        ground color via a color pair affects only character cells
212        that  a  character write operation explicitly touches.  To
213        change the background color used when parts  of  a  window
214        are  blanked  by  erasing  or  scrolling  operations,  see
215        <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.  Several caveats apply on 386 and  486  ma-
216        chines with VGA-compatible graphics:
217
218        -    COLOR_YELLOW  is  actually brown.  To get yellow, use
219             COLOR_YELLOW combined with the <STRONG>A_BOLD</STRONG> attribute.
220
221        -    The A_BLINK attribute  should  in  theory  cause  the
222             background  to  go bright.  This often fails to work,
223             and even some cards for which it mostly  works  (such
224             as  the  Paradise and compatibles) do the wrong thing
225             when you try to set a bright "yellow" background (you
226             get a blinking yellow foreground instead).
227
228        -    Color RGB values are not settable.
229
230
231 </PRE>
232 <H2>PORTABILITY</H2><PRE>
233        This  implementation  satisfies XSI Curses's minimum maxi-
234        mums for <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG>.
235
236        The <STRONG>init_pair</STRONG> routine accepts  negative  values  of  fore-
237        ground   and  background  color  to  support  the  <STRONG>use_de-</STRONG>
238        <STRONG>fault_colors</STRONG> extension, but only if that routine has  been
239        first invoked.
240
241        The  assumption that <STRONG>COLOR_BLACK</STRONG> is the default background
242        color for all terminals can  be  modified  using  the  <STRONG>as-</STRONG>
243        <STRONG>sume_default_colors</STRONG> extension.
244
245        This  implementation  checks  the  pointers, e.g., for the
246        values returned by  <STRONG>color_content</STRONG>  and  <STRONG>pair_content</STRONG>,  and
247        will treat those as optional parameters when null.
248
249
250 </PRE>
251 <H2>SEE ALSO</H2><PRE>
252        <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>default_col-</STRONG>
253        <STRONG><A HREF="default_colors.3x.html">ors(3x)</A></STRONG>
254
255
256
257                                                          <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>
258 </PRE>
259 <HR>
260 <ADDRESS>
261 Man(1) output converted with
262 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
263 </ADDRESS>
264 </BODY>
265 </HTML>