-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
+and color-pairs the terminal can support).
+.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:
+.bP
+\fBCOLORS\fP corresponds to the terminal database's \fBmax_colors\fP capability,
+which is typically a signed 16-bit integer (see \fBterminfo\fR(\*n)).
+.bP
+color values are expected to be in the range \fB0\fP to \fBCOLORS\-1\fP,
+inclusive (including \fB0\fP and \fBCOLORS\-1\fP).
+.bP
+a special color value \fB\-1\fP is used in certain extended functions
+to denote the \fIdefault color\fP (see \fBuse_default_colors\fP).
+.bP
+\fBCOLOR_PAIRS\fP corresponds to the terminal database's \fBmax_pairs\fP capability,
+which is typically a signed 16-bit integer (see \fBterminfo\fR(\*n)).
+.bP
+legal color pair values are in the range \fB1\fP to \fBCOLOR_PAIRS\-1\fP,
+inclusive.
+.bP
+color pair \fB0\fP is special; it denotes \*(``no color\*(''.
+.IP
+Color pair \fB0\fP is assumed to be white on black,
+but is actually whatever the terminal implements before color is initialized.
+It cannot be modified by the application.
+.PP
+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.
+For portable applications:
+.bP
+The first argument must be a legal color pair value.
+If default colors are used (see \fBuse_default_colors\fP)
+the upper limit is adjusted to allow for extra pairs which use
+a default color in foreground and/or background.
+.bP
+The second and third arguments must be legal color values.
+.PP
+If the color-pair was previously initialized,
+the screen is refreshed and all occurrences of that color-pair
+are changed to the new definition.
+.PP
+As an extension, ncurses allows you to set color pair \fB0\fP via
+the \fBassume_default_colors\fR routine, or to specify the use of
+default colors (color number \fB\-1\fR) if you first invoke the
+\fBuse_default_colors\fR routine.
+.PP
+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 first argument must be a legal color value;
+default colors are not allowed here.
+(See the section \fBColors\fR for the default color index.)
+Each of the last three arguments
+must be a value in the range \fB0\fP through \fB1000\fP.
+When \fBinit_color\fR is used, all
projects / ncurses.git / blobdiff