can_change_color(3X)

NAME

can_change_color, color_content, has_colors, init_color, init_pair, start_color, pair_content — color manipulation functions

SYNOPSIS

#include <curses.h>

bool can_change_color(void);

int color_content(short color, short *red, short *green, short *blue);

int COLOR_PAIR(int n);

bool has_colors(void);

int init_color(short color, short red, short green, short blue);

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

int pair_content(short pair, short *f, short *b);

int PAIR_NUMBER(int value);

int start_color(void);

extern int COLOR_PAIRS;

extern int COLORS;

DESCRIPTION

These functions manipulate colour on terminals that support colour.

Querying Capabilities

The has_colors() function indicates whether the terminal is a colour terminal. The can_change_color() function indicates whether the terminal is a colour terminal on which colours can be redefined.

Initialisation

The start_color() function must be called in order to enable use of colours and before any colour manipulation function is called. The function initialises eight basic colours (black, blue, green, cyan, red, magenta, yellow, and white) that can be specified by the colour macros (such as COLOR_BLACK) defined in <curses.h>. (See Colour-related Macros in <curses.h>.) The initial appearance of these eight colours is not specified.

The function also initialises two global external variables:

COLORS defines the number of colours that the terminal supports. (See Colour Identification below.) If COLORS is 0, the terminal does not support redefinition of colours (and can_change_colour() will return FALSE).
COLOR_PAIRS defines the maximum number of colour-pairs that the terminal supports. (See User-Defined Colour Pairs below.)

The start_color() function also restores the colours on the terminal to terminal-specific initial values. The initial background colour is assumed to be black for all terminals.

Colour Identification

The init_color() function redefines colour number color, on terminals that support the redefinition of colours, to have the red, green, and blue intensity components specified by red, green, and blue, respectively. Calling init_color() also changes all occurrences of the specified colour on the screen to the new definition.

The color_content() function identifies the intensity components of colour number color. It stores the red, green, and blue intensity components of this colour in the addresses pointed to by red, green, and blue, respectively.

For both functions, the color argument must be in the range from 0 to and including COLORS-1. Valid intensity values range from 0 (no intensity component) up to and including 1000 (maximum intensity in that component).

User-Defined Colour Pairs

Calling init_pair() defines or redefines colour-pair number pair to have foreground colour f and background colour b. Calling init_pair() changes any characters that were displayed in the colour pair's old definition to the new definition and refreshes the screen.

After defining the colour pair, the macro COLOR_PAIR(n) returns the value of colour pair n. This value is the colour attribute as it would be extracted from a chtype. Conversely, the macro PAIR_NUMBER(value) returns the colour pair number associated with the colour attribute value.

The pair_content() function retrieves the component colours of a colour-pair number pair. It stores the foreground and background colour numbers in the variables pointed to by f and b, respectively.

With init_pair() and pair_content(), the value of pair must be in a range from 0 to and including COLOR_PAIRS-1. (There may be an implementation-specific lower limit on the valid value of pair, but any such limit is at least 63.) Valid values for f and b are the range from 0 to and including COLORS-1.

RETURN VALUE

The has_colors() function returns TRUE if the terminal can manipulate colors; otherwise, it returns FALSE.

The can_change_color() function returns TRUE if the terminal supports colors and can change their definitions; otherwise, it returns FALSE.

Upon successful completion, the other functions return OK; otherwise, they return ERR.

ERRORS

No errors are defined.

APPLICATION USAGE

To use these functions, start_color() must be called, usually right after initscr().

The can_change_color() and has_colors() functions facilitate writing terminal-independent programs. For example, a programmer can use them to decide whether to use colour or some other video attribute.

On color terminals, a typical value of COLORS is 8 and the macros such as COLOR_BLACK return a value within the range from 0 to and including 7. However, applications cannot rely on this to be true.

CHANGE HISTORY

First released in X/Open Curses, Issue 4.