CURSES_COLOR(3)

CURSES_COLOR(3) | Library Functions Manual | CURSES_COLOR(3)

# NAME

`curses_color`, `has_colors`, `can_change_color`, `start_color`, `init_pair`, `pair_content`, `COLOR_PAIR`, `PAIR_NUMBER`, `init_color`, `color_content`, `no_color_attributes` —
curses color manipulation routines

# LIBRARY

Curses Library (libcurses, -lcurses)

# SYNOPSIS

`#include <curses.h>`

bool
`has_colors`(void);

bool
`can_change_color`(void);

int
`start_color`(void);

int
`init_pair`(short pair, short fore, short back);

int
`pair_content`(short pair, short *fore, short *back);

int
`COLOR_PAIR`(int n);

int
`PAIR_NUMBER`(int val);

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

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

attr_t
`no_color_attributes`(void);

extern int COLOR_PAIRS;

extern int COLORS;

# DESCRIPTION

These functions manipulate color on terminals that support color attributes.

The function `has_colors`() indicates whether a terminal is capable of displaying color attributes. It returns `TRUE` if the terminal is capable of displaying color attributes and `FALSE` otherwise.

The function `can_change_color`() indicates whether a terminal is capable of redefining colors. It returns `TRUE` if colors can be redefined and `FALSE` if they can not.

The function `start_color`() initializes the curses color support on a terminal. It must be called before any color manipulation functions are called on that terminal. The function initializes the eight basic colors (black, red, green, yellow, blue, magenta, cyan and white) that are specified using the color macros (such as `COLOR_BLACK`) defined in <curses.h>. `start_color`() also initializes the global external variables COLORS and COLOR_PAIRS. COLORS defines the number of colors that the terminal supports and COLOR_PAIRS defines the number of color-pairs that the terminal supports. These color-pairs are initialized to white foreground on black background. `start_color`() sets the colors on the terminal to the curses defaults of white foreground on black background unless the functions `assume_default_colors`() or `use_default_colors`() have been called previously.

The function `init_pair`(pair, fore, back) sets foreground color fore and background color back for color-pair number pair. The valid range for the color-pair pair is from 1 to COLOR_PAIRS - 1 and the valid range for the colors is any number less than COLORS. Specifying a negative number will set that color to the default foreground or background color. The 8 initial colors are defined as:

COLOR_BLACK
COLOR_RED
COLOR_GREEN
COLOR_YELLOW
COLOR_BLUE
COLOR_MAGENTA
COLOR_CYAN
COLOR_WHITE

Color-pair 0 is used as the default color pair, so changing this will have no effect. Use the function `assume_default_colors`() to change the default colors.

The function `pair_content`(pair, *fore, *back) stores the foreground and background color numbers of color-pair pair in the variables fore and back, respectively.

The macro `COLOR_PAIR`(n) gives the attribute value of color-pair number n. This is the value that is used to set the attribute of a character to this color-pair. For example,

`attrset(COLOR_PAIR(2))`
will display characters using color-pair 2.

The macro `PAIR_NUMBER`(val) gives the color-pair number associated with the attribute value val.

The function `init_color`(color, red, green, blue) sets the red, green and blue intensity components of color color to the values red, green and blue, respectively. The minimum intensity value is 0 and the maximum intensity value is 1000.

The function `color_content`(color, *red, *green, *blue) stores the red, green and blue intensity components of color color in the variables red, green, and blue, respectively.

The function `no_color_attributes`() returns those attributes that a terminal is unable to combine with color.

# RETURN VALUES

The functions `start_color`(), `init_pair`(), `pair_content`(), `init_color`() and `color_content`() return OK on success and ERR on failure.

# SEE ALSO

curses_attributes(3), curses_background(3), curses_default_colors(3)

# STANDARDS

The NetBSD Curses library complies with the X/Open Curses specification, part of the Single Unix Specification.

The function `no_color_attributes`() and the use of negative color numbers are extensions to the X/Open Curses specification.

# HISTORY

These functions first appeared in NetBSD 1.5.

July 20, 2009 | NetBSD 9.0