139 lines
6.4 KiB
Groff
139 lines
6.4 KiB
Groff
.TH curs_color 3X ""
|
|
.SH NAME
|
|
\fBcurs_color\fR: \fBstart_color\fR, \fBinit_pair\fR,
|
|
\fBinit_color\fR, \fBhas_colors\fR, \fBcan_change_color\fR,
|
|
\fBcolor_content\fR, \fBpair_content\fR - \fBncurses\fR color
|
|
manipulation routines
|
|
.SH SYNOPSIS
|
|
\fB# include <ncurses.h>\fR
|
|
.br
|
|
\fBint start_color(void);\fR
|
|
.br
|
|
\fBint init_pair(short pair, short f, short b);\fR
|
|
.br
|
|
\fBint init_color(short color, short r, short g, short b);\fR
|
|
.br
|
|
\fBbool has_colors(void);\fR
|
|
.br
|
|
\fBbool can_change_color(void);\fR
|
|
.br
|
|
\fBint color_content(short color, short *r, short *g, short *b);\fR
|
|
.br
|
|
\fBint pair_content(short pair, short *f, short *b);\fR
|
|
.br
|
|
.SH DESCRIPTION
|
|
.SS Overview
|
|
\fBncurses\fR support color attributes on terminals with that capability. To
|
|
use these routines \fBstart_color\fR must be called, usually right after
|
|
\fBinitscr\fR. Colors are always used in pairs (referred to as color-pairs).
|
|
A color-pair consists of a foreground color (for characters) and a background
|
|
color (for the blank field on which the characters are displayed). A
|
|
programmer initializes a color-pair with the routine \fBinit_pair\fR. After it
|
|
has been initialized, \fBCOLOR_PAIR\fR(\fIn\fR), a macro defined in
|
|
\fB<ncurses.h>\fR, can be used as a new video attribute.
|
|
|
|
If a terminal is capable of redefining colors, the programmer can use the
|
|
routine \fBinit_color\fR to change the definition of a color. The routines
|
|
\fBhas_colors\fR and \fBcan_change_color\fR return \fBTRUE\fR or \fBFALSE\fR,
|
|
depending on whether the terminal has color capabilities and whether the
|
|
programmer can change the colors. The routine \fBcolor_content\fR allows a
|
|
programmer to extract the amounts of red, green, and blue components in an
|
|
initialized color. The routine \fBpair_content\fR allows a programmer to find
|
|
out how a given color-pair is currently defined.
|
|
.SS Routine Descriptions
|
|
The \fBstart_color\fR routine requires no arguments. It must be
|
|
called if the programmer wants to use colors, and before any other
|
|
color manipulation routine is called. It is good practice to call
|
|
this routine right after \fBinitscr\fR. \fBstart_color\fR initializes
|
|
eight basic colors (black, red, green, yellow, blue, magenta, cyan,
|
|
and white), and two global variables, \fBCOLORS\fR and
|
|
\fBCOLOR_PAIRS\fR (respectively defining the maximum number of colors
|
|
and color-pairs the terminal can support). It also restores the
|
|
colors on the terminal to the values they had when the terminal was
|
|
just turned on.
|
|
|
|
The \fBinit_pair\fR routine changes the definition of a color-pair. It takes
|
|
three arguments: the number of the color-pair to be changed, the foreground
|
|
color number, and the background color number. The value of the first argument
|
|
must be between \fB1\fR and \fBCOLOR_PAIRS-1\fR. The value of the second and
|
|
third arguments must be between 0 and \fBCOLORS\fR (the 0 color pair is wired
|
|
to white on black and cannot be changed). If the color-pair was previously
|
|
initialized, the screen is refreshed and all occurrences of that color-pair is
|
|
changed to the new definition.
|
|
|
|
The \fBinit_color\fR routine changes the definition of a color. It takes four
|
|
arguments: the number of the color to be changed followed by three RGB values
|
|
(for the amounts of red, green, and blue components). The value of the first
|
|
argument must be between \fB0\fR and \fBCOLORS\fR. (See the section
|
|
\fBColors\fR for the default color index.) Each of the last three arguments
|
|
must be a value between 0 and 1000. When \fBinit_color\fR is used, all
|
|
occurrences of that color on the screen immediately change to the new
|
|
definition.
|
|
|
|
The \fBhas_colors\fR routine requires no arguments. It returns \fBTRUE\fR if
|
|
the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR. This
|
|
routine facilitates writing terminal-independent programs. For example, a
|
|
programmer can use it to decide whether to use color or some other video
|
|
attribute.
|
|
|
|
The \fBcan_change_color\fR routine requires no arguments. It returns
|
|
\fBTRUE\fR if the terminal supports colors and can change their definitions;
|
|
other, it returns \fBFALSE\fR. This routine facilitates writing
|
|
terminal-independent programs.
|
|
|
|
The \fBcolor_content\fR routine gives programmers a way to find the intensity
|
|
of the red, green, and blue (RGB) components in a color. It requires four
|
|
arguments: the color number, and three addresses of \fBshort\fRs for storing
|
|
the information about the amounts of red, green, and blue components in the
|
|
given color. The value of the first argument must be between 0 and
|
|
\fBCOLORS\fR. The values that are stored at the addresses pointed to by the
|
|
last three arguments are between 0 (no component) and 1000 (maximum amount of
|
|
component).
|
|
|
|
The \fBpair_content\fR routine allows programmers to find out what colors a
|
|
given color-pair consists of. It requires three arguments: the color-pair
|
|
number, and two addresses of \fBshort\fRs for storing the foreground and the
|
|
background color numbers. The value of the first argument must be between 1
|
|
and \fBCOLOR_PAIRS-1\fR. The values that are stored at the addresses pointed
|
|
to by the second and third arguments are between 0 and \fBCOLORS\fR.
|
|
.SS Colors
|
|
In \fB<ncurses.h>\fR the following macros are defined. These are the default
|
|
colors. \fBncurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
|
|
background color for all terminals.
|
|
|
|
.nf
|
|
\fBCOLOR_BLACK\fR
|
|
\fBCOLOR_RED\fR
|
|
\fBCOLOR_GREEN\fR
|
|
\fBCOLOR_YELLOW\fR
|
|
\fBCOLOR_BLUE\fR
|
|
\fBCOLOR_MAGENTA\fR
|
|
\fBCOLOR_CYAN\fR
|
|
\fBCOLOR_WHITE\fR
|
|
.fi
|
|
.SH RETURN VALUE
|
|
All routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
|
|
upon successful completion.
|
|
.SH NOTES
|
|
Several caveats apply onn 386 and 486 machines with VGA-compatible graphics:
|
|
|
|
COLOR_YELLOW is actually brown. To get yellow, use COLOR_YELLOW combined with
|
|
the \fBA_BOLD\fR attribute.
|
|
|
|
The A_BLINK attribute should in theory cause the background to go bright. This
|
|
often fails to work, and even some cards for which it mostly works (such as the
|
|
Paradise and compatibles) do the wrong thing when you try to set a bright
|
|
"yellow" background (you get a blinking yellow foreground instead).
|
|
|
|
Color RGB values are not settable.
|
|
.SH CAPABILITIES
|
|
\fBsetf\fR, \fBsetb\fR, \fBsetaf\fR, \fBsetab\fR. The ncurses library uses
|
|
the second pair by preference, falling back to the first.
|
|
.SH SEE ALSO
|
|
\fBncurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_attr\fR(3X)
|
|
.\"#
|
|
.\"# The following sets edit modes for GNU EMACS
|
|
.\"# Local Variables:
|
|
.\"# mode:nroff
|
|
.\"# fill-column:79
|