Tribblix: manual page: can_change

CAN_CHANGE_COLOR(3XCURSES) X/Open Curses Library Functions

NAME

can_change_color, color_content, COLOR_PAIR, has_colors, init_color,
init_pair, pair_content, PAIR_NUMBER, start_color, COLOR_PAIRS,
COLORS - manipulate color information

SYNOPSIS

cc [ flag... ] file... -I /usr/xpg4/include -L /usr/xpg4/lib \
-R /usr/xpg4/lib -lcurses [ library... ]

c89 [ flag... ] file... -lcurses [ library... ]

#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(voidextern int COLOR_PAIRS;

extern int COLORS;

DESCRIPTION

These functions manipulate color on terminals that support color.

Querying Capabilities
The has_colors() function indicates whether the terminal is a color
terminal. The can_change_color() function indicates whether the
terminal is a color terminal on which colors can be redefined.

Initialization

The start_color() function must be called to enable use of colors and
before any color manipulation function is called. The function
initializes eight basic colors (black, red, green, yellow, blue,
magenta, cyan, and white) that can be specified by the color macros
(such as COLOR_BLACK) defined in <curses.h>. The initial appearance
of these colors is unspecified.

The function also initializes two global external variables:

o COLORS defines the number of colors that the terminal
supports. See Color Identification below. If COLORS is 0,
the terminal does not support redefinition of colors and
can_change_color() will return FALSE.

o COLOR_PAIRS defines the maximum number of color-pairs that
the terminal supports. See User-defined Color Pairs below.

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

Color Identification

The init_color() function redefines color number color, on terminals
that support the redefinition of colors, 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 color on the screen to the new definition.

The color_content() function identifies the intensity components of
color number color. It stores the red, green, and blue intensity
components of this color 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 value range from 0 (no
intensity component) up to and including 1000 (maximum intensity in
that component).

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

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

The pair_content() retrieves the component colors of a color-pair
number pair. It stores the foreground and background color 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. Valid values for f and b
are the range from 0 to and including COLORS-1.

PARAMETERS

color
Is the number of the color for which to provide information
(0 to COLORS-1).

red
Is a pointer to the RGB value for the amount of red in
color.

green
Is a pointer to the RGB value for the amount of green in
color.

blue
Is a pointer to the RGB value for the amount of blue in
color.

n
Is the number of a color pair.

pair
Is the number of the color pair for which to provide
information (1 to COLOR_PAIRS-1).

f
Is a pointer to the number of the foreground color (0 to
COLORS-1) in pair.

b
Is a pointer to the number of the background color (0 to
COLORS-1) in pair.

value
Is a color attribute value.

RETURN VALUES

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 is able to change their definitions. Otherwise, it returns
FALSE.

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

ERRORS

No errors are defined.

USAGE

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

The can_change_color() and has_colors() functions facilitate writing
terminal-independent applications. For example, a programmer can use
them to decide whether to use color 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.

ATTRIBUTES