[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions , Volume 2


can_change_color, color_content, has_colors,init_color, init_pair, start_color or pair_content Subroutine

Purpose

Color manipulation functions and external variables for color support.

Library

Curses Library (libcurses.a)

Syntax

#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 color on terminals that support color.

Querying Capabilities

The has_colors subroutine indicates whether the terminal is a color terminal. The can_change_color subroutine indicates whether the terminal is a color terminal on which colors can be redefined.

Initialisation

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

The function also initialises two global external variables:

Color Identification

The init_color subroutine 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 subroutine also changes all occurrences of the specified color on the screen to the new definition.

The color_content subroutine 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 values 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. Conversely, the macro PAIR_NUMBER(value) returns the color pair number associated with the color attribute value.

The pair_content subroutine 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 subroutines, the value of pair must be in a range from 0 to and including COLOR_PAIRS -1. (There may be an implementation-specific upper 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.

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

Parameters


color  
*red  
*green  
*blue  
pair  
f  
b  
value  

Return Values

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

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

Examples

For the can_change_color subroutine:

To test whether or not a terminal can change its colors, enter the following and check the return for TRUE or FALSE:

can_change_color();

For the color_content subroutine:

To obtain the RGB component information for color 10 (assuming the terminal supports at least 11 colors), use:

short *r, *g, *b;
color_content(10,r,g,b);

For the has_color subroutine:

To determine whether or not a terminal supports color, use:

has_colors();

For the pair_content subroutine:

To obtain the foreground and background colors for color-pair 5, use:

short *f, *b;
pair_content(5,f,b);

For this subroutine to succeed, you must have already initialized the color pair. The foreground and background colors will be stored at the locations pointed to by f and b.

For the start_color subroutine:

To enable the color support for a terminal that supports color, use:

start_color();

For the init_pair subroutine:

To initialize the color definition for color-pair 2 to a black foreground (color 0) with a cyan background (color 3), use:

init_pair(2,COLOR_BLACK, COLOR_CYAN);

For the init_color subroutine:

To initialize the color definition for color 11 to violet on a terminal that supports at least 12 colors, use:

init_color(11,500,0,500);

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The attroff (attroff, attron, attrset, wattroff, wattron, or wattrset Subroutine) subroutine.

Curses Overview for Programming and Manipulating Video Attributes in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]