'\" 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]
.TH CAN_CHANGE_COLOR 3XCURSES "Jun 5, 2002"
.SH 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
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
\fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]

\fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]

#include <curses.h>

\fBbool\fR \fBcan_change_color\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBint\fR \fBcolor_content\fR(\fBshort\fR \fIcolor\fR, \fBshort *\fR\fIred\fR, \fBshort *\fR\fIgreen\fR, \fBshort *\fR\fIblue\fR);
.fi

.LP
.nf
\fBint\fR \fBCOLOR_PAIR\fR(\fBint\fR \fIn\fR);
.fi

.LP
.nf
\fBbool\fR \fBhas_colors\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBint\fR \fBinit_color\fR(\fBshort\fR \fIcolor\fR, \fBshort\fR \fIred\fR, \fBshort\fR \fIgreen\fR, \fBshort\fR \fIblue\fR);
.fi

.LP
.nf
\fBint\fR \fBinit_pair\fR(\fBshort\fR \fIpair\fR, \fBshort\fR \fIf\fR, \fBshort\fR \fIb\fR);
.fi

.LP
.nf
\fBint\fR \fBpair_content\fR(\fBshort\fR \fIpair\fR, \fBshort *\fR\fIf\fR, \fBshort *\fR\fIb\fR);
.fi

.LP
.nf
\fBint\fR \fBPAIR_NUMBER\fR(\fBint\fR \fIvalue\fR);
.fi

.LP
.nf
\fBint\fR \fBstart_color\fR(\fBvoid\fRextern int COLOR_PAIRS;

extern int COLORS;
.fi

.SH DESCRIPTION
.sp
.LP
These functions manipulate color on terminals that support color.
.SS " Querying Capabilities"
.sp
.LP
The \fBhas_colors()\fR function indicates whether the terminal is a color
terminal. The \fBcan_change_color()\fR function indicates whether the terminal
is a color terminal on which colors can be redefined.
.SS "Initialization"
.sp
.LP
The \fBstart_color()\fR 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 \fBCOLOR_BLACK\fR) defined
in <\fBcurses.h\fR>. The initial appearance of these colors is unspecified.
.sp
.LP
The function also initializes two global external variables:
.RS +4
.TP
.ie t \(bu
.el o
\fBCOLORS\fR defines the number of colors that the terminal supports. See
\fBColor Identification\fR below. If \fBCOLORS\fR is 0, the terminal does not
support redefinition of colors and \fBcan_change_color()\fR will return
\fBFALSE\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBCOLOR_PAIRS\fR defines the maximum number of color-pairs that the terminal
supports. See \fBUser-defined Color Pairs\fR below.
.RE
.sp
.LP
The \fBstart_color()\fR 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.
.SS "Color Identification"
.sp
.LP
The \fBinit_color()\fR function redefines color number \fIcolor\fR, on
terminals that support the redefinition of colors, to have the red, green, and
blue intensity components specified by \fIred\fR, \fIgreen\fR, and \fIblue\fR,
respectively. Calling \fBinit_color()\fR also changes all occurrences of the
specified color on the screen to the new definition.
.sp
.LP
The \fBcolor_content()\fR function identifies the intensity components of color
number \fIcolor\fR. It stores the red, green, and blue intensity components of
this color in the addresses pointed to by \fIred\fR, \fIgreen\fR, and
\fIblue\fR, respectively.
.sp
.LP
For both functions, the \fIcolor\fR argument must be in the range from 0 to and
including \fBCOLORS\fR\(mi1. Valid intensity value range from 0 (no intensity
component) up to and including 1000 (maximum intensity in that component).
.SS "User-defined Color Pairs"
.sp
.LP
Calling \fBinit_pair()\fR defines or redefines color-pair number \fIpair\fR to
have foreground color \fIf\fR and background color \fIb\fR. Calling
\fBinit_pair()\fR changes any characters that were displayed in the color
pair's old definition to the new definition and refreshes the screen.
.sp
.LP
After defining the color pair, the macro \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR
returns the value of color pair \fIn\fR. This value is the color attribute as
it would be extracted from a \fBchtype\fR. Controversy, the macro
\fBCOLOR_NUMBER(\fR\fIvalue\fR\fB)\fR returns the color pair number associated
with the color attribute \fIvalue\fR.
.sp
.LP
The \fBpair_content()\fR retrieves the component colors of a color-pair number
\fIpair\fR. It stores the foreground and background color numbers in the
variables pointed to by \fIf\fR and \fIb\fR, respectively.
.sp
.LP
With \fBinit_pair()\fR and \fBpair_content()\fR, the value of \fIpair\fR must
be in a range from 0 to and including \fBCOLOR_PAIRS\fR\(mi1. Valid values for
\fIf\fR and \fIb\fR are the range from 0 to and including \fBCOLORS\fR\(mi1.
.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIcolor\fR\fR
.ad
.RS 9n
Is the number of the color for which to provide information (0 to
\fBCOLORS\fR\(mi1).
.RE

.sp
.ne 2
.na
\fB\fIred\fR\fR
.ad
.RS 9n
Is a pointer to the RGB value for the amount of red in \fIcolor\fR.
.RE

.sp
.ne 2
.na
\fB\fIgreen\fR\fR
.ad
.RS 9n
Is a pointer to the RGB value for the amount of green in \fIcolor\fR.
.RE

.sp
.ne 2
.na
\fB\fIblue\fR\fR
.ad
.RS 9n
Is a pointer to the RGB value for the amount of blue in \fIcolor\fR.
.RE

.sp
.ne 2
.na
\fB\fIn\fR\fR
.ad
.RS 9n
Is the number of a color pair.
.RE

.sp
.ne 2
.na
\fB\fIpair\fR\fR
.ad
.RS 9n
Is the number of the color pair for which to provide information (1 to
\fBCOLOR_PAIRS\fR\(mi1).
.RE

.sp
.ne 2
.na
\fB\fIf\fR\fR
.ad
.RS 9n
Is a pointer to the number of the foreground color (0 to \fBCOLORS\fR\(mi1) in
\fIpair\fR.
.RE

.sp
.ne 2
.na
\fB\fIb\fR\fR
.ad
.RS 9n
Is a pointer to the number of the background color (0 to \fBCOLORS\fR\(mi1) in
\fIpair\fR.
.RE

.sp
.ne 2
.na
\fB\fIvalue\fR\fR
.ad
.RS 9n
Is a color attribute value.
.RE

.SH RETURN VALUES
.sp
.LP
The \fBhas_colors()\fR function returns \fBTRUE\fR if the terminal can
manipulate colors. Otherwise, it returns \fBFALSE\fR.
.sp
.LP
The \fBcan_change_color()\fR function returns \fBTRUE\fR if the terminal
supports colors and is able to change their definitions. Otherwise, it returns
\fBFALSE\fR.
.sp
.LP
Upon successful completion, the other functions return \fBOK\fR. Otherwise,
they return \fBERR\fR.
.SH ERRORS
.sp
.LP
No errors are defined.
.SH  USAGE
.sp
.LP
To use these functions, \fBstart_color()\fR must be called, usually right after
\fBinitscr\fR(3XCURSES).
.sp
.LP
The \fBcan_change_color()\fR and \fBhas_colors()\fR functions facilitate
writing terminal-independent applications. For example, a programmer can use
them to decide whether to use color or some other video attribute.
.sp
.LP
On color terminals, a typical value of \fBCOLORS\fR is 8 and the macros such as
\fBCOLOR_BLACK\fR return a value within the range from 0 to and including 7.
However, applications cannot rely on this to be true.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
\fBattroff\fR(3XCURSES), \fBdelscreen\fR(3XCURSES), \fBinitscr\fR(3XCURSES),
\fBlibcurses\fR(3XCURSES), \fBattributes\fR(5), \fBstandards\fR(5)