X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_color.3x;h=bbb2e3f03d1270c2762c66ebf61a38317898c663;hp=47f596594b5edb61664870662ee2637962f42191;hb=3eda6f30a84d53844d2ebceadb457e2e7e9cfbf3;hpb=2e68dc325852af56f2ec6c315b323a4f9c3d62c9

diff --git a/man/curs_color.3x b/man/curs_color.3x
index 47f59659..bbb2e3f0 100644
--- a/man/curs_color.3x
+++ b/man/curs_color.3x
@@ -26,7 +26,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_color.3x,v 1.47 2017/03/13 21:49:37 tom Exp $
+.\" $Id: curs_color.3x,v 1.50 2017/04/01 19:57:19 tom Exp $
 .TH curs_color 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -40,15 +40,12 @@
 .hy 0
 .SH NAME
 \fBstart_color\fR,
+\fBhas_colors\fR,
+\fBcan_change_color\fR,
 \fBinit_pair\fR,
 \fBinit_color\fR,
-.\" .br
 \fBcolor_content\fR,
 \fBpair_content\fR,
-.\" .br
-\fBhas_colors\fR,
-\fBcan_change_color\fR,
-.\" .br
 \fBCOLOR_PAIR\fR,
 \fBPAIR_NUMBER\fR \- \fBcurses\fR color manipulation routines
 .ad
@@ -58,17 +55,29 @@
 .sp
 \fBint start_color(void);\fR
 .sp
+\fBbool has_colors(void);\fR
+.br
+\fBbool can_change_color(void);\fR
+.sp
 \fBint init_pair(short pair, short f, short b);\fR
 .br
 \fBint init_color(short color, short r, short g, short b);\fR
+.br
+/* extensions */
+.br
+\fBint init_extended_pair(int pair, int f, int b);\fR
+.br
+\fBint init_extended_color(int color, int r, int g, int b);\fR
 .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
-\fBbool has_colors(void);\fR
 .br
-\fBbool can_change_color(void);\fR
+/* extensions */
+.br
+\fBint extended_color_content(int color, int *r, int *g, int *b);\fR
+.br
+\fBint extended_pair_content(int pair, int *f, int *b);\fR
 .sp
 \fBint COLOR_PAIR(int n);\fR
 .br
@@ -141,7 +150,35 @@ 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
+.SH CONSTANTS
+.PP
+In \fB<curses.h>\fR the following macros are defined.
+These are the standard colors (ISO-6429).
+\fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
+background color for all terminals.
+.PP
+.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
+.PP
+Some terminals support more than the eight (8) \*(lqANSI\*(rq 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
+the terminal can support.
+.SS COLOR_PAIRS
+is initialized by \fBstart_color\fP to the maximum number of color pairs
+the terminal can support.
+.SH FUNCTIONS
+.SS start_color
 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.
@@ -180,8 +217,8 @@ along with the terminal's color.
 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)).
+\fBCOLORS\fP corresponds to the terminal database's \fBmax_colors\fR capability,
+(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).
@@ -190,7 +227,7 @@ 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)).
+(see \fBterminfo\fR(\*n)).
 .bP
 legal color pair values are in the range \fB1\fP to \fBCOLOR_PAIRS\-1\fP,
 inclusive.
@@ -200,6 +237,22 @@ color pair \fB0\fP is special; it denotes \*(``no color\*(''.
 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.
+.SS has_colors
+.PP
+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.
+.SS can_change_color
+.PP
+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.
+.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
@@ -218,34 +271,26 @@ 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
+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 routine.
+\fBuse_default_colors\fR(3X) routine.
+.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
 (for the amounts of red, green, and blue components).
+.bP
 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.)
+.bP
 Each of the last three arguments
 must be a value in the range \fB0\fP through \fB1000\fP.
+.PP
 When \fBinit_color\fR is used, all
 occurrences of that color on the screen immediately change to the new
 definition.
-.PP
-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.
-.PP
-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.
+.SS color_content
 .PP
 The \fBcolor_content\fR routine gives programmers a way to find the intensity
 of the red, green, and blue (RGB) components in a color.
@@ -253,47 +298,38 @@ 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.
+.bP
 The first argument must be a legal color value, i.e.,
 \fB0\fP through \fBCOLORS\-1\fP, inclusive.
+.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.
+.SS pair_content
 .PP
 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.
+.bP
 The first argument must be a legal color value,
 i.e., in the range \fB1\fP through \fBCOLOR_PAIRS\-1\fR, inclusive.
+.bP
 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 PAIR_NUMBER
 .PP
 \fBPAIR_NUMBER(\fR\fIattrs\fR) extracts the color
 value from its \fIattrs\fP parameter and returns it as a color pair number.
+.SS COLOR_PAIR
 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 standard colors (ISO-6429).
-\fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
-background color for all terminals.
-.PP
-.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
 The routines \fBcan_change_color\fR and \fBhas_colors\fR return \fBTRUE\fR
 or \fBFALSE\fR.
@@ -304,7 +340,7 @@ completion.
 .PP
 X/Open defines no error conditions.
 This implementation will return \fBERR\fR on attempts to
-use color values outside the range \fB0\fP to COLORS\-1
+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.
@@ -324,19 +360,19 @@ returns an error if the color table cannot be allocated.
 .RE
 .SH NOTES
 In the \fBncurses\fR implementation, there is a separate color activation flag,
-color palette, color pairs table, and associated COLORS and COLOR_PAIRS 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
 historical implementations may use a single shared color palette.
 .PP
-Note that setting an implicit background color via a color pair affects only
+Setting an implicit background color via a color pair affects only
 character cells that a character write operation explicitly touches.
 To change
 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 386 and 486 machines 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.
@@ -353,17 +389,26 @@ This implementation satisfies XSI Curses's minimum maximums
 for \fBCOLORS\fR and \fBCOLOR_PAIRS\fR.
 .PP
 The \fBinit_pair\fP routine accepts negative values of foreground
-and background color to support the \fBuse_default_colors\fP extension,
+and background color to support the \fBuse_default_colors\fR(3X) extension,
 but only if that routine has been first invoked.
 .PP
 The assumption that \fBCOLOR_BLACK\fR is the default
 background color for all terminals can be modified using the
-\fBassume_default_colors\fP extension.
+\fBassume_default_colors\fR(3X) extension.
 .PP
 This implementation checks the pointers,
 e.g., for the values returned by
 \fBcolor_content\fP and \fBpair_content\fP,
 and will treat those as optional parameters when null.
+.PP
+X/Open Curses does not specify a limit for the number of colors and
+color pairs which a terminal can support.
+However, in its use of \fBshort\fP for the parameters,
+it carries over SVr4's implementation detail for the compiled
+terminfo database, which uses signed 16-bit numbers.
+This implementation provides extended versions of those functions
+which use \fBshort\fP parameters,
+allowing applications to use larger color- and pair-numbers.
 .SH SEE ALSO
 \fBcurses\fR(3X),
 \fBcurs_initscr\fR(3X),