.\"***************************************************************************
-.\" Copyright (c) 1998-2016,2017 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2018,2019 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.53 2017/11/20 01:03:45 tom Exp $
+.\" $Id: curs_color.3x,v 1.61 2019/01/20 17:04:08 tom Exp $
.TH curs_color 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
\fBcan_change_color\fR,
\fBinit_pair\fR,
\fBinit_color\fR,
+\fBinit_extended_pair\fR,
+\fBinit_extended_color\fR,
\fBcolor_content\fR,
\fBpair_content\fR,
+\fBextended_color_content\fR,
+\fBextended_pair_content\fR,
\fBreset_color_pairs\fR,
\fBCOLOR_PAIR\fR,
\fBPAIR_NUMBER\fR \- \fBcurses\fR color manipulation routines
.fi
.PP
Some terminals support more than the eight (8) \*(``ANSI\*('' colors.
-There are no standard names for those additional colors.
+There are no standard names for those additional colors.
.SH VARIABLES
.SS COLORS
is initialized by \fBstart_color\fP to the maximum number of colors
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.
+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.
+using weights that depend upon the CGA/HLS choice.
+For \*(``ANSI\*('' colors the weights are \fB680\fP or \fB0\fP
+depending on whether the corresponding
+red, green, or blue component is used or not.
+That permits using \fB1000\fP to represent bold/bright colors.
+After the initial eight colors
+(if the terminal supports more than eight colors)
+the components are initialized using the same pattern,
+but with weights of \fB1000\fP.
+SVr4 uses a similar scheme, but uses \fB1000\fP
+for the components of the initial eight colors.
.IP
\fBstart_color\fP does not attempt to set the terminal's color palette
to match its built-in table.
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).
+to denote the \fIdefault color\fP (see \fBuse_default_colors\fP(3X)).
.bP
-\fBCOLOR_PAIRS\fP corresponds to the terminal database's \fBmax_pairs\fP capability,
+\fBCOLOR_PAIRS\fP corresponds to
+the terminal database's \fBmax_pairs\fP capability,
(see \fBterminfo\fR(\*n)).
.bP
legal color pair values are in the range \fB1\fP to \fBCOLOR_PAIRS\-1\fP,
.SS init_pair
.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
+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)
+If default colors are used (see \fBuse_default_colors\fP(3X))
the upper limit is adjusted to allow for extra pairs which use
a default color in foreground and/or background.
.bP
the \fBassume_default_colors\fR(3X) routine, or to specify the use of
default colors (color number \fB\-1\fR) if you first invoke the
\fBuse_default_colors\fR(3X) routine.
+.SS init_extended_pair
.PP
-The extension \fBreset_color_pairs\fP tells ncurses to discard all
-of the color-pair information which was set with \fBinit_pair\fP.
-It also touches the current- and standard-screens, allowing an application to
-switch color palettes rapidly.
+Because \fBinit_pair\fP uses signed \fBshort\fPs for its parameters,
+that limits color-pairs and color-values
+to 32767 on modern hardware.
+The extension \fBinit_extended_pair\fP uses \fBint\fPs
+for the color-pair and color-value,
+allowing a larger number of colors to be supported.
.SS init_color
.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
+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).
.bP
The first argument must be a legal color value;
When \fBinit_color\fR is used, all
occurrences of that color on the screen immediately change to the new
definition.
+.SS init_extended_color
+.PP
+Because \fBinit_color\fP uses signed \fBshort\fPs for its parameters,
+that limits color-values and their red, green, and blue components
+to 32767 on modern hardware.
+The extension \fBinit_extended_color\fP uses \fBint\fPs
+for the color value and
+for setting the red, green, and blue components,
+allowing a larger number of colors to be supported.
.SS color_content
.PP
The \fBcolor_content\fR routine gives programmers a way to find the intensity
.bP
The values that are stored at the addresses pointed to by the
last three arguments are in the range
-\fB0\fP (no component) through \fB1000\fP (maximum amount of component), inclusive.
+\fB0\fP (no component) through \fB1000\fP
+(maximum amount of component), inclusive.
+.SS extended_color_content
+.PP
+Because \fBcolor_content\fP uses signed \fBshort\fPs for its parameters,
+that limits color-values and their red, green, and blue components
+to 32767 on modern hardware.
+The extension \fBextended_color_content\fP uses \fBint\fPs
+for the color value and
+for returning the red, green, and blue components,
+allowing a larger number of colors to be supported.
.SS pair_content
.PP
The \fBpair_content\fR routine allows programmers to find out what colors a
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.
+.SS extended_pair_content
+.PP
+Because \fBpair_content\fP uses signed \fBshort\fPs for its parameters,
+that limits color-pair and color-values to 32767 on modern hardware.
+The extension \fBextended_pair_content\fP uses \fBint\fPs
+for the color pair and
+for returning the foreground and background colors,
+allowing a larger number of colors to be supported.
+.SS reset_color_pairs
+.PP
+The extension \fBreset_color_pairs\fP tells ncurses to discard all
+of the color-pair information which was set with \fBinit_pair\fP.
+It also touches the current- and standard-screens, allowing an application to
+switch color palettes rapidly.
.SS PAIR_NUMBER
.PP
\fBPAIR_NUMBER(\fR\fIattrs\fR) extracts the color
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
-completion.
+(SVr4 specifies only \*(``an integer value
+other than \fBERR\fR\*('') upon successful completion.
.PP
X/Open defines no error conditions.
+SVr4 does document some error conditions which apply in general:
+.bP
This implementation will return \fBERR\fR on attempts to
use color values outside the range \fB0\fP to \fBCOLORS\fP\-1
(except for the default colors extension),
or use color pairs outside the range \fB0\fP to \fBCOLOR_PAIRS\-1\fP.
-Color values used in \fBinit_color\fP must be in the range \fB0\fP to \fB1000\fP.
+.IP
+Color values used in \fBinit_color\fP must be
+in the range \fB0\fP to \fB1000\fP.
+.IP
An error is returned from all functions
if the terminal has not been initialized.
+.IP
An error is returned from secondary functions such as \fBinit_pair\fP
if \fBstart_color\fP was not called.
+.bP
+SVr4 does much the same, except that
+it returns \fBERR\fP from \fBpair_content\fP if the pair was not initialized
+using \fBinit_pairs\fP
+and
+it returns \fBERR\fP from \fBcolor_content\fP
+if the terminal does not support changing colors.
+.IP
+This implementation does not return \fBERR\fP for either case.
+.PP
+Specific functions make additional checks:
.RS 3
.TP 5
\fBinit_color\fP
.RE
.SH NOTES
In the \fBncurses\fR implementation, there is a separate color activation flag,
-color palette, color pairs table, and associated \fBCOLORS\fP and \fBCOLOR_PAIRS\fP counts
+color palette, color pairs table,
+and associated \fBCOLORS\fP and \fBCOLOR_PAIRS\fP counts
for each screen; the \fBstart_color\fR function only affects the current
screen.
The SVr4/XSI interface is not really designed with this in mind, and
the background color used when parts of a window are blanked by erasing or
scrolling operations, see \fBcurs_bkgd\fR(3X).
.PP
-Several caveats apply on older x86 machines (e.g., i386, i486) with VGA-compatible graphics:
+Several caveats apply on older x86 machines
+(e.g., i386, i486) with VGA-compatible graphics:
.bP
COLOR_YELLOW is actually brown.
To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fR attribute.
projects / ncurses.git / blobdiff