.\"***************************************************************************
-.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2015,2016 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_color.3x,v 1.36 2014/11/16 00:44:29 tom Exp $
+.\" $Id: curs_color.3x,v 1.45 2016/10/15 17:10:19 tom Exp $
.TH curs_color 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
\fBstart_color\fR,
\fBinit_pair\fR,
\fBinit_color\fR,
+.\" .br
\fBhas_colors\fR,
\fBcan_change_color\fR,
+.\" .br
\fBcolor_content\fR,
\fBpair_content\fR,
-\fBCOLOR_PAIR\fR \- \fBcurses\fR color manipulation routines
+.\" .br
+\fBCOLOR_PAIR\fR,
+\fBPAIR_NUMBER\fR \- \fBcurses\fR color manipulation routines
.ad
.hy
.SH SYNOPSIS
-\fB# include <curses.h>\fR
+\fB#include <curses.h>\fR
.sp
\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
+.sp
\fBbool has_colors(void);\fR
.br
\fBbool can_change_color(void);\fR
-.br
+.sp
\fBint color_content(short color, short *r, short *g, short *b);\fR
.br
\fBint pair_content(short pair, short *f, short *b);\fR
+.sp
+\fBint COLOR_PAIR(int n);\fR
+.br
+\fBPAIR_NUMBER(\fR\fIattrs\fR\fB);\fP
.br
.SH DESCRIPTION
.SS Overview
-\fBcurses\fR support color attributes on terminals with that capability.
+\fBcurses\fR supports 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<curses.h>\fR, can be used as a new video attribute.
+After it has been initialized, \fBCOLOR_PAIR\fR(\fIn\fR)
+can be used to convert the pair to a video attribute.
.PP
If a terminal is capable of redefining colors, the programmer can use the
routine \fBinit_color\fR to change the definition of a color.
initialized color.
The routine \fBpair_content\fR allows a programmer to find
out how a given color-pair is currently defined.
+.SS Color Rendering
+The \fBcurses\fP library combines these inputs to produce the
+actual foreground and background colors shown on the screen:
+.bP
+per-character video attributes (e.g., via \fBwaddch\fP),
+.bP
+the window attribute (e.g., by \fBwattrset\fP), and
+.bP
+the background character (e.g., \fBwbkgdset\fP).
+.PP
+Per-character and window attributes are usually set by a parameter containing
+video attributes including a color pair value.
+Some functions such as \fBwattr_set\fP use a separate parameter which
+is the color pair number.
+.PP
+The background character is a special case: it includes a character value,
+just as if it were passed to \fBwaddch\fP.
+.PP
+The \fBcurses\fP library does the actual work of combining these color
+pairs in an internal function called from \fBwaddch\fP:
+.bP
+If the parameter passed to \fBwaddch\fP is \fIblank\fP,
+and it uses the special color pair 0,
+.RS
+.bP
+\fBcurses\fP next checks the window attribute.
+.bP
+If the window attribute does not use color pair 0,
+\fBcurses\fP uses the color pair from the window attribute.
+.bP
+Otherwise, \fBcurses\fP uses the background character.
+.RE
+.bP
+If the parameter passed to \fBwaddch\fP is \fInot blank\fP,
+or it does not use the special color pair 0,
+\fBcurses\fP prefers the color pair from the parameter,
+if it is nonzero.
+Otherwise, it tries the window attribute next, and finally the
+background character.
+.PP
+Some \fBcurses\fP functions such as \fBwprintw\fP call \fBwaddch\fP.
+Those do not combine its parameter with a color pair.
+Consequently those calls use only the window attribute or
+the background character.
.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
+\fBstart_color\fR does this:
+.bP
+It initializes 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.
+.bP
+It initializes the special color pair \fB0\fP to the default foreground
+and background colors.
+No other color pairs are initialized.
+.bP
+It restores the colors on the terminal to the values
+they had when the terminal was just turned on.
+.bP
+If the terminal supports the \fBinitc\fP (\fBinitialize_color\fP) capability,
+\fBstart_color\fP
+initializes its internal table representing the
+red, green and blue components of the color palette.
+.IP
+The components depend on whether the terminal uses
+CGA (aka \*(lqANSI\*(rq) or
+HLS (i.e., the \fBhls\fP (\fBhue_lightness_saturation\fP) capability is set).
+The table is initialized first for eight basic colors
+(black, red, green, yellow, blue, magenta, cyan, and white),
+and after that (if the terminal supports more than eight colors)
+the components are initialized to \fB1000\fP.
+.IP
+\fBstart_color\fP does not attempt to set the terminal's color palette
+to match its built-in table.
+An application may use \fBinit_color\fP to alter the internal table
+along with the terminal's color.
.PP
These limits apply to color values and color pairs.
Values outside these limits are not legal, and may result in a runtime error:
The values that are stored at the addresses pointed
to by the second and third arguments are in the
range \fB0\fP through \fBCOLORS\fR, inclusive.
+.PP
+\fBPAIR_NUMBER(\fR\fIattrs\fR) extracts the color
+value from its \fIattrs\fP parameter and returns it as a color pair number.
+Its inverse \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR converts a color pair number
+to an attribute.
+Attributes can hold color pairs in the range 0 to 255.
+If you need a color pair larger than that, you must use functions
+such as \fBattr_set\fP (which pass the color pair as a separate parameter)
+rather than the legacy functions such as \fBattrset\fP.
.SS Colors
In \fB<curses.h>\fR the following macros are defined.
-These are the default colors.
+These are the standard colors (ISO-6429).
\fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
background color for all terminals.
.PP
\fBCOLOR_WHITE\fR
.fi
.SH RETURN VALUE
-The routines \fBcan_change_color()\fR and \fBhas_colors()\fR return \fBTRUE\fR
+The routines \fBcan_change_color\fR and \fBhas_colors\fR return \fBTRUE\fR
or \fBFALSE\fR.
.PP
All other routines return the integer \fBERR\fR upon failure and an \fBOK\fR
-(SVr4 specifies only "an integer value other than \fBERR\fR") upon successful
+(SVr4 specifies only \*(lqan integer value other than \fBERR\fR\*(rq) upon successful
completion.
.PP
X/Open defines no error conditions.
.TP 5
\fBinit_color\fP
returns an error if the terminal does not support
-this feature, e.g., if the \fIinitialize_color\fP capability is absent
+this feature, e.g., if the \fBinitialize_color\fP capability is absent
from the terminal description.
.TP 5
\fBstart_color\fP
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).
+\*(lqyellow\*(rq background (you get a blinking yellow foreground instead).
.bP
Color RGB values are not settable.
.SH PORTABILITY
projects / ncurses.git / blobdiff