1curs_color(3X) curs_color(3X)
2
6 start_color, has_colors, can_change_color, init_pair, init_color,
7 init_extended_pair, init_extended_color, color_content, pair_content,
8 extended_color_content, extended_pair_content, reset_color_pairs,
9 COLOR_PAIR, PAIR_NUMBER - curses color manipulation routines
10
12 #include <curses.h>
13 int start_color(void);
15 bool has_colors(void);
17 bool can_change_color(void);
18 int init_pair(short pair, short f, short b);
20 int init_color(short color, short r, short g, short b);
21 /* extensions */
22 int init_extended_pair(int pair, int f, int b);
23 int init_extended_color(int color, int r, int g, int b);
24 int color_content(short color, short *r, short *g, short *b);
26 int pair_content(short pair, short *f, short *b);
27 /* extensions */
28 int extended_color_content(int color, int *r, int *g, int *b);
29 int extended_pair_content(int pair, int *f, int *b);
30 /* extensions */
32 void reset_color_pairs(void);
33 int COLOR_PAIR(int n);
35 PAIR_NUMBER(attrs);
36
38 Overview
39 curses supports color attributes on terminals with that capability. To
40 use these routines start_color must be called, usually right after
41 initscr. Colors are always used in pairs (referred to as color-pairs).
42 A color-pair consists of a foreground color (for characters) and a
43 background color (for the blank field on which the characters are dis‐
44 played). A programmer initializes a color-pair with the routine
45 init_pair. After it has been initialized, COLOR_PAIR(n) can be used to
46 convert the pair to a video attribute.
47 If a terminal is capable of redefining colors, the programmer can use
49 the routine init_color to change the definition of a color. The rou‐
50 tines has_colors and can_change_color return TRUE or FALSE, depending
51 on whether the terminal has color capabilities and whether the program‐
52 mer can change the colors. The routine color_content allows a program‐
53 mer to extract the amounts of red, green, and blue components in an
54 initialized color. The routine pair_content allows a programmer to
55 find out how a given color-pair is currently defined.
56 Color Rendering
58 The curses library combines these inputs to produce the actual fore‐
59 ground and background colors shown on the screen:
60 · per-character video attributes (e.g., via waddch),
62 · the window attribute (e.g., by wattrset), and
64 · the background character (e.g., wbkgdset).
66 Per-character and window attributes are usually set by a parameter con‐
68 taining video attributes including a color pair value. Some functions
69 such as wattr_set use a separate parameter which is the color pair num‐
70 ber.
71 The background character is a special case: it includes a character
73 value, just as if it were passed to waddch.
74 The curses library does the actual work of combining these color pairs
76 in an internal function called from waddch:
77 · If the parameter passed to waddch is blank, and it uses the special
79 color pair 0,
80 · curses next checks the window attribute.
82 · If the window attribute does not use color pair 0, curses uses
84 the color pair from the window attribute.
85 · Otherwise, curses uses the background character.
87 · If the parameter passed to waddch is not blank, or it does not use
89 the special color pair 0, curses prefers the color pair from the
90 parameter, if it is nonzero. Otherwise, it tries the window at‐
91 tribute next, and finally the background character.
92 Some curses functions such as wprintw call waddch. Those do not com‐
94 bine its parameter with a color pair. Consequently those calls use on‐
95 ly the window attribute or the background character.
96
98 In <curses.h> the following macros are defined. These are the standard
99 colors (ISO-6429). curses also assumes that COLOR_BLACK is the default
100 background color for all terminals.
101 COLOR_BLACK
103 COLOR_RED
104 COLOR_GREEN
105 COLOR_YELLOW
106 COLOR_BLUE
107 COLOR_MAGENTA
108 COLOR_CYAN
109 COLOR_WHITE
110 Some terminals support more than the eight (8) “ANSI” colors. There
112 are no standard names for those additional colors.
113
115 COLORS
116 is initialized by start_color to the maximum number of colors the ter‐
117 minal can support.
118 COLOR_PAIRS
120 is initialized by start_color to the maximum number of color pairs the
121 terminal can support.
122
124 start_color
125 The start_color routine requires no arguments. It must be called if
126 the programmer wants to use colors, and before any other color manipu‐
127 lation routine is called. It is good practice to call this routine
128 right after initscr. start_color does this:
129 · It initializes two global variables, COLORS and COLOR_PAIRS (re‐
131 spectively defining the maximum number of colors and color-pairs
132 the terminal can support).
133 · It initializes the special color pair 0 to the default foreground
135 and background colors. No other color pairs are initialized.
136 · It restores the colors on the terminal to the values they had when
138 the terminal was just turned on.
139 · If the terminal supports the initc (initialize_color) capability,
141 start_color initializes its internal table representing the red,
142 green, and blue components of the color palette.
143 The components depend on whether the terminal uses CGA (aka “ANSI”)
145 or HLS (i.e., the hls (hue_lightness_saturation) capability is
146 set). The table is initialized first for eight basic colors
147 (black, red, green, yellow, blue, magenta, cyan, and white), using
148 weights that depend upon the CGA/HLS choice. For “ANSI” colors the
149 weights are 680 or 0 depending on whether the corresponding red,
150 green, or blue component is used or not. That permits using 1000
151 to represent bold/bright colors. After the initial eight colors
152 (if the terminal supports more than eight colors) the components
153 are initialized using the same pattern, but with weights of 1000.
154 SVr4 uses a similar scheme, but uses 1000 for the components of the
155 initial eight colors.
156 start_color does not attempt to set the terminal's color palette to
158 match its built-in table. An application may use init_color to al‐
159 ter the internal table along with the terminal's color.
160 These limits apply to color values and color pairs. Values outside
162 these limits are not legal, and may result in a runtime error:
163 · COLORS corresponds to the terminal database's max_colors capabili‐
165 ty, (see terminfo(5)).
166 · color values are expected to be in the range 0 to COLORS-1, inclu‐
168 sive (including 0 and COLORS-1).
169 · a special color value -1 is used in certain extended functions to
171 denote the default color (see use_default_colors(3X)).
172 · COLOR_PAIRS corresponds to the terminal database's max_pairs capa‐
174 bility, (see terminfo(5)).
175 · legal color pair values are in the range 1 to COLOR_PAIRS-1, inclu‐
177 sive.
178 · color pair 0 is special; it denotes “no color”.
180 Color pair 0 is assumed to be white on black, but is actually what‐
182 ever the terminal implements before color is initialized. It can‐
183 not be modified by the application.
184 has_colors
186 The has_colors routine requires no arguments. It returns TRUE if the
187 terminal can manipulate colors; otherwise, it returns FALSE. This rou‐
188 tine facilitates writing terminal-independent programs. For example, a
189 programmer can use it to decide whether to use color or some other
190 video attribute.
191 can_change_color
193 The can_change_color routine requires no arguments. It returns TRUE if
194 the terminal supports colors and can change their definitions; other,
195 it returns FALSE. This routine facilitates writing terminal-indepen‐
196 dent programs.
197 init_pair
199 The init_pair routine changes the definition of a color-pair. It takes
200 three arguments: the number of the color-pair to be changed, the fore‐
201 ground color number, and the background color number. For portable ap‐
202 plications:
203 · The first argument must be a legal color pair value. If default
205 colors are used (see use_default_colors(3X)) the upper limit is ad‐
206 justed to allow for extra pairs which use a default color in fore‐
207 ground and/or background.
208 · The second and third arguments must be legal color values.
210 If the color-pair was previously initialized, the screen is refreshed
212 and all occurrences of that color-pair are changed to the new defini‐
213 tion.
214 As an extension, ncurses allows you to set color pair 0 via the as‐
216 sume_default_colors(3X) routine, or to specify the use of default col‐
217 ors (color number -1) if you first invoke the use_default_colors(3X)
218 routine.
219 init_extended_pair
221 Because init_pair uses signed shorts for its parameters, that limits
222 color-pairs and color-values to 32767 on modern hardware. The exten‐
223 sion init_extended_pair uses ints for the color-pair and color-value,
224 allowing a larger number of colors to be supported.
225 init_color
227 The init_color routine changes the definition of a color. It takes
228 four arguments: the number of the color to be changed followed by three
229 RGB values (for the amounts of red, green, and blue components).
230 · The first argument must be a legal color value; default colors are
232 not allowed here. (See the section Colors for the default color
233 index.)
234 · Each of the last three arguments must be a value in the range 0
236 through 1000.
237 When init_color is used, all occurrences of that color on the screen
239 immediately change to the new definition.
240 init_extended_color
242 Because init_color uses signed shorts for its parameters, that limits
243 color-values and their red, green, and blue components to 32767 on mod‐
244 ern hardware. The extension init_extended_color uses ints for the col‐
245 or value and for setting the red, green, and blue components, allowing
246 a larger number of colors to be supported.
247 color_content
249 The color_content routine gives programmers a way to find the intensity
250 of the red, green, and blue (RGB) components in a color. It requires
251 four arguments: the color number, and three addresses of shorts for
252 storing the information about the amounts of red, green, and blue com‐
253 ponents in the given color.
254 · The first argument must be a legal color value, i.e., 0 through
256 COLORS-1, inclusive.
257 · The values that are stored at the addresses pointed to by the last
259 three arguments are in the range 0 (no component) through 1000
260 (maximum amount of component), inclusive.
261 extended_color_content
263 Because color_content uses signed shorts for its parameters, that lim‐
264 its color-values and their red, green, and blue components to 32767 on
265 modern hardware. The extension extended_color_content uses ints for
266 the color value and for returning the red, green, and blue components,
267 allowing a larger number of colors to be supported.
268 pair_content
270 The pair_content routine allows programmers to find out what colors a
271 given color-pair consists of. It requires three arguments: the color-
272 pair number, and two addresses of shorts for storing the foreground and
273 the background color numbers.
274 · The first argument must be a legal color value, i.e., in the range
276 1 through COLOR_PAIRS-1, inclusive.
277 · The values that are stored at the addresses pointed to by the sec‐
279 ond and third arguments are in the range 0 through COLORS, inclu‐
280 sive.
281 extended_pair_content
283 Because pair_content uses signed shorts for its parameters, that limits
284 color-pair and color-values to 32767 on modern hardware. The extension
285 extended_pair_content uses ints for the color pair and for returning
286 the foreground and background colors, allowing a larger number of col‐
287 ors to be supported.
288 reset_color_pairs
290 The extension reset_color_pairs tells ncurses to discard all of the
291 color-pair information which was set with init_pair. It also touches
292 the current- and standard-screens, allowing an application to switch
293 color palettes rapidly.
294 PAIR_NUMBER
296 PAIR_NUMBER(attrs) extracts the color value from its attrs parameter
297 and returns it as a color pair number.
298 COLOR_PAIR
300 Its inverse COLOR_PAIR(n) converts a color pair number to an attribute.
301 Attributes can hold color pairs in the range 0 to 255. If you need a
302 color pair larger than that, you must use functions such as attr_set
303 (which pass the color pair as a separate parameter) rather than the
304 legacy functions such as attrset.
305
307 The routines can_change_color and has_colors return TRUE or FALSE.
308 All other routines return the integer ERR upon failure and an OK (SVr4
310 specifies only “an integer value other than ERR”) upon successful com‐
311 pletion.
312 X/Open defines no error conditions. SVr4 does document some error con‐
314 ditions which apply in general:
315 · This implementation will return ERR on attempts to use color values
317 outside the range 0 to COLORS-1 (except for the default colors ex‐
318 tension), or use color pairs outside the range 0 to COLOR_PAIRS-1.
319 Color values used in init_color must be in the range 0 to 1000.
321 An error is returned from all functions if the terminal has not
323 been initialized.
324 An error is returned from secondary functions such as init_pair if
326 start_color was not called.
327 · SVr4 does much the same, except that it returns ERR from pair_con‐
329 tent if the pair was not initialized using init_pairs and it re‐
330 turns ERR from color_content if the terminal does not support
331 changing colors.
332 This implementation does not return ERR for either case.
334 Specific functions make additional checks:
336 init_color
338 returns an error if the terminal does not support this feature,
339 e.g., if the initialize_color capability is absent from the
340 terminal description.
341 start_color
343 returns an error if the color table cannot be allocated.
344
346 In the ncurses implementation, there is a separate color activation
347 flag, color palette, color pairs table, and associated COLORS and COL‐
348 OR_PAIRS counts for each screen; the start_color function only affects
349 the current screen. The SVr4/XSI interface is not really designed with
350 this in mind, and historical implementations may use a single shared
351 color palette.
352 Setting an implicit background color via a color pair affects only
354 character cells that a character write operation explicitly touches.
355 To change the background color used when parts of a window are blanked
356 by erasing or scrolling operations, see curs_bkgd(3X).
357 Several caveats apply on older x86 machines (e.g., i386, i486) with
359 VGA-compatible graphics:
360 · COLOR_YELLOW is actually brown. To get yellow, use COLOR_YELLOW
362 combined with the A_BOLD attribute.
363 · The A_BLINK attribute should in theory cause the background to go
365 bright. This often fails to work, and even some cards for which it
366 mostly works (such as the Paradise and compatibles) do the wrong
367 thing when you try to set a bright “yellow” background (you get a
368 blinking yellow foreground instead).
369 · Color RGB values are not settable.
371
373 This implementation satisfies XSI Curses's minimum maximums for COLORS
374 and COLOR_PAIRS.
375 The init_pair routine accepts negative values of foreground and back‐
377 ground color to support the use_default_colors(3X) extension, but only
378 if that routine has been first invoked.
379 The assumption that COLOR_BLACK is the default background color for all
381 terminals can be modified using the assume_default_colors(3X) exten‐
382 sion.
383 This implementation checks the pointers, e.g., for the values returned
385 by color_content and pair_content, and will treat those as optional pa‐
386 rameters when null.
387 X/Open Curses does not specify a limit for the number of colors and
389 color pairs which a terminal can support. However, in its use of short
390 for the parameters, it carries over SVr4's implementation detail for
391 the compiled terminfo database, which uses signed 16-bit numbers. This
392 implementation provides extended versions of those functions which use
393 short parameters, allowing applications to use larger color- and pair-
394 numbers.
395 The reset_color_pairs function is an extension of ncurses.
397
399 curses(3X), curs_initscr(3X), curs_attr(3X), curs_variables(3X), de‐
400 fault_colors(3X)
401 curs_color(3X)