Simple input and output

Color manipulation

The curses color manipulation routines allow you to use colors on an alphanumeric terminal as you would use any other video attribute. You can find out if the curses library on your system supports the color routines by checking the file /usr/include/ocurses.h to see if it defines the macro COLOR_PAIR(n).

This section begins with a description of the color feature at a general level. Then the use of color as an attribute is explained. Next, the ways to define color-pairs and change the definitions of colors is explained. Finally, there are guidelines for ensuring the portability of your program, and a section describing the color manipulation routines and macros, with examples.

How the color feature works

Colors are always used in pairs, consisting of a foreground color (used for the character) and a background color (used for the field the character is displayed on). curses uses this concept of color-pairs to manipulate colors. In order to use color in a curses program, you must first define (initialize) the individual colors, then create color-pairs using those colors, and finally, use the color-pairs as attributes.

Actually, the process is even simpler, since curses maintains a table of initialized colors for you. This table has as many entries as the number of colors your terminal can display at one time. Each entry in the table has three fields: one each for the intensity of the red, green, and blue components in that color.

NOTE: curses uses RGB (Red, Green, Blue) color notation. This notation allows you to specify directly the intensity of red, green, and blue light to be generated in an additive system. Some terminals use an alternative notation, known as HSL (Hue, Saturation, Luminosity) color notation. Terminals that use HSL can be identified in the terminfo database, and curses will make conversions to RGB notation automatically.

At the beginning of any curses program that uses color, all entries in the colors table are initialized with eight basic colors, as follows:

The default colors table

  Intensity of Component
  (R)ed (G)reen (B)lue
black: 0 0 0 0
red: 1 1000 0 0
green: 2 0 1000 0
yellow: 3 1000 1000 0
blue: 4 0 0 1000
magenta: 5 1000 0 1000
cyan: 6 0 1000 1000
white: 7 1000 1000 1000

Most color alphanumeric terminals can display eight colors at the same time, but if your terminal can display more than eight, then the table will have more than eight entries. The same eight colors will be used to initialize additional entries. If your terminal can display only N colors, where N is less than eight, then only the first N colors shown in the colors table will be used.

You can change these color definitions with the routine init_color, if your terminal is capable of redefining colors. (See the section ``Changing the definitions of colors'' for more information.)

The following color macros are defined in ocurses.h and have numeric values corresponding to their position in the colors table.

curses also maintains a table of color-pairs, which has space allocated for as many entries as the number of color-pairs that can be displayed on your terminal screen at the same time. Unlike the colors table, however, there are no
default entries in the pairs table: it is your responsibility to initialize any color-pair you want to use, with init_pair, before you use it as an attribute.

Each entry in the pairs table has two fields: the foreground color, and the background color. For each color-pair that you initialize, these two fields will each contain a number representing a color in the colors table. (Note that color-pairs can only be made from previously initialized colors.)

The following example pairs table shows that a programmer has used init_pair to initialize color-pair 1 as a red foreground (entry 1 in the default color table) on cyan background (entry 6 in the default color table). Similarly, the programmer has initialized color-pair 2 as a yellow foreground on a magenta background. Not-initialized entries in the pairs table would actually contain zeros, which corresponds to black on black.

Note that color-pair 0 is reserved for use by curses and should not be changed or used in application programs.

Example of a pairs table

Color-Pair number Foreground Background
0 (reserved) 0 0
1 1 6
2 3 5
3 0 0
4 0 0
5 0 0
. . .
. . .
. . .

Two global variables used by the color routines are defined in ocurses.h. They are COLORS, which contains the maximum number of colors the terminal supports, and COLOR_PAIRS, which contains the maximum number of color-pairs the terminal supports. Both are initialized by the start_color routine to values it gets from the terminfo database.

Upon termination of your curses program, all colors and/or color-pairs will be restored to the values they had when the terminal was just turned on.

Using the COLOR_PAIR(n) attribute

If you choose to use the default color definitions, there are only two things you need to do before you can use the attribute COLOR_PAIR(n). First, you must call the routine start_color. Once you've done that, you can initialize color-pairs with the routine init_pair(pair, f, b). The first argument, pair, is the number of the color-pair to be initialized (or changed), and must be between 1 and COLOR_PAIRS-1. The arguments f and b are the foreground color number and the background color number. The value of these arguments must be between 0 and COLORS-1. For example, the two color-pairs in the pairs table described earlier can be initialized in the following way:

   init_pair (1, COLOR_RED, COLOR_CYAN);
   init_pair (2, COLOR_YELLOW, COLOR_MAGENTA);

Once you've initialized a color-pair, the attribute COLOR_PAIR(n) can be used as you would use any other attribute. COLOR_PAIR(n) is a macro, defined in ocurses.h. The argument, n, is the number of a previously initialized color-pair. For example, you can use the routine attron to turn on a color-pair in addition to any other attributes you may currently have turned on:

   attron (COLOR_PAIR(1));
If you had initialized color-pair 1 in the way shown in the example pairs table, then characters displayed after you turned on color-pair 1 with attron would be displayed as blue characters on a yellow background.

You can also combine COLOR_PAIR(n) with other attributes, for example:

would turn on blinking and whatever you have initialized color-pair 1 to be. (attron and attrset are described in ``attron, attrset, and attroff'' and also on the curses(3ocurses) manual page .

Changing the definitions of colors

If your terminal is capable of redefining colors, you can change the predefined colors with the routine init_color(color, r, g, b). The first argument, color, is the numeric value of the color you want to change, and the last three, r, g, and b, are the intensities of the red, green, and blue components, respectively, that the new color will contain. Once you change the definition of a color, all occurrences of that color on your screen change immediately.

So, for example, you could change the definition of color 4 (COLOR_BLUE by default), to be light blue, in the following way.

   init_color (COLOR_BLUE, 0, 700, 1000);
If your terminal is not able to change the definition of a color, use of init_color returns ERR.

Portability guidelines

Like the rest of curses, the color manipulation routines have been designed to be terminal independent. But it must be remembered that the capabilities of terminals vary. For example, if you write a program for a terminal that can support 64 color-pairs, that program would not be able to produce the same color effects on a terminal that supports at most eight color-pairs.

When you are writing a program that may be used on different terminals, you should follow these guidelines:

Other macros and routines

There are two other macros defined in ocurses.h that you can use to obtain information from the color-pair field in characters of type chtype.

There are two color routines that give you information about the terminal your program is running on. The routine has_colors returns a Boolean value: TRUE if the terminal supports colors, FALSE otherwise. The routine can_change_colors also returns a Boolean value: TRUE if the terminal supports colors and can change their definitions, FALSE otherwise.

There are two color routines that give you information about the colors and color-pairs that are currently defined on your terminal. The routine color_content gives you a way to find the intensity of the RGB components in an initialized color. It returns ERR if the color does not exist or if the terminal cannot change color definitions, COK otherwise. The routine pair_content allows you to find out what colors a given color-pair consists of. It returns ERR is the color-pair has not been initialized, COK otherwise.

These routines are explained in more detail on the curses(3ocurses) manual pages in this guide.

The routines start_color, init_color, and init_pair are described on the following pages, with examples of their use. You can also refer to ``The colors program'' for an example of using the attribute of color in windows.



   #include <ocurses.h>

int start_color()


See the example under init_pair.



   #include <ocurses.h>

int init_pair (pair, f, b) short pair, f, b;



   #include <ocurses.h>

main() { initscr (); if (start_color () == OK) { init_pair (1, COLOR_RED, COLOR_GREEN); attron (COLOR_PAIR (1)); addstr ("Red on Green"); getch(); } endwin(); }

Also see ``The colors program''.



   #include <ocurses.h>

int init_color(color, r, g, b) short color, r, g, b;



   #include <ocurses.h>

main() { initscr(); if (start_color() == OK) { init_pair (1, COLOR_RED, COLOR_GREEN); attron (COLOR_PAIR (1)); if (init_color (COLOR_RED, 0, 0, 1000) == OK) addstr ("BLUE ON GREEN"); else addstr ("RED ON GREEN"); getch (); } endwin(); }

Next topic: Bells, whistles, and flashing lights: beep and flash
Previous topic: standout and standend

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004