.\"***************************************************************************
-.\" Copyright (c) 1998-2009,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2010,2015 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.39 2015/06/06 23:29:02 tom Exp $
.TH curs_color 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.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).
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 \fBCOLOR_PAIR\fP 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 "ANSI") 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:
range \fB0\fP through \fBCOLORS\fR, inclusive.
.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
projects / ncurses.git / blobdiff