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
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+
|MT-Level | Unsafe |
+--------------------+-----------------+
SEE ALSO
attroff(3XCURSES),
delscreen(3XCURSES),
initscr(3XCURSES),
libcurses(3XCURSES),
attributes(7),
standards(7) June 5, 2002
CAN_CHANGE_COLOR(3XCURSES)