te
Copyright (c) 1990, 1995 by Mortice Kern Systems Inc. All Rights Reserved Portions Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
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

cc [ flag... ] file... -I /usr/xpg4/include  -L  /usr/xpg4/lib \e
 -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;

These functions manipulate color on terminals that support color.

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.

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:

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.

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

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.

color red green blue n pair f b 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 is able to change their definitions. Otherwise, it returns FALSE.

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

No errors are defined.

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.

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Standard

MT-Level Unsafe

attroff(3XCURSES), delscreen(3XCURSES), initscr(3XCURSES), libcurses(3XCURSES), attributes(5), standards(5)