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.

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.

   COLOR_BLACK	0
   COLOR_RED	1
   COLOR_GREEN	2
   COLOR_YELLOW	3
   COLOR_BLUE	4
   COLOR_MAGENTA	5
   COLOR_CYAN	6
   COLOR_WHITE	7

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));

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

   attrset(A_BLINK|COLOR_PAIR(1));

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);

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:

• Use at most seven color-pairs made from at most eight colors.

  Programs that follow this guideline will run on most color terminals. Only seven, not eight, color-pairs should be used, even though many terminals support eight color-pairs, because curses reserves color-pair 0 for its own use.

• Do not use color 0 as a background color.

  This is recommended because on some terminals, no matter what color you have defined it to be, color 0 will always be converted to black when used for a background.

• Combine color and other video attributes.

  Programs that follow this guideline will provide some sort of highlighting, even if the terminal is monochrome. On color terminals, as many of the listed attributes as possible would be used. On monochrome terminals, only the video attributes would be used, and the color attribute would be ignored.

  Use the global variables COLORS and COLOR-PAIRS rather than constants when deciding how many colors or color-pairs your program should use.

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.

• A_COLOR is a bit mask to extract color-pair information. It can be used to clear the color-pair field, and to determine if any color-pair is being used.

• PAIR_NUMBER(attrs) is the reverse of COLOR_PAIR(n). It returns the color-pair number associated with the named attribute, attrs.

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.

start_color

SYNOPSIS

   #include <ocurses.h>
   

   int start_color()
   

• This routine must be called if you want to use colors, and before any other color manipulation routine is called. It is good practice to call it right after initscr.

• It initializes eight default colors (black, red, green, yellow, blue, magenta, cyan, and white), and the global variables COLORS and COLOR_PAIRS. If the value corresponding to COLOR_PAIRS in the terminfo database is greater than 64, COLOR_PAIRS will be set to 64.

• It restores the terminal's colors to the values they had when the terminal was just turned on.

• It returns ERR if the terminal does not support colors, COK otherwise.

See the example under init_pair.

init_pair

SYNOPSIS

   #include <ocurses.h>
   

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

• init_pair changes the definition of a color-pair.

• Color-pairs must be initialized with init_pair before they can be used as the argument to the attribute macro COLOR_PAIR(n).

• The value of the first argument, pair, is the number of a color-pair, and must be between 1 and COLOR_PAIRS-1.

• The value of the f (foreground) and b (background) arguments must be between 0 and COLORS-1.

• If the color-pair was previously initialized, the screen will be refreshed and all occurrences of that color-pair will change to the new definition.

• It returns COK if it was able to change the definition of the color-pair, ERR otherwise.

EXAMPLE

   #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''.

init_color

SYNOPSIS

   #include <ocurses.h>
   

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

• init_color changes the definition of a color.

• The first argument, color, is the number of the color to be changed. The value of color must be between 0 and COLORS-1.

• The last three arguments, r, g, and b, are the amounts of red, green, and blue (RGB) components in the new color. The values of these three arguments must be between 0 and 1000.

• When init_color is used to change the definition of an entry in the colors table, all places where the old color was used on the screen immediately change to the new color.

• It returns COK if it was able to change the definition of the color, ERR otherwise.

EXAMPLE

   #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();
   }