X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_color.3x;h=02defb6a793c58f1de8cd966e030fe21678d7c64;hp=f5604e03b414e78f1de2a99ff02b3ab0692a3a76;hb=42259b594b5dabd37fe2bc294051d2db82e873a2;hpb=17c5992a16be94247b83f2bbb9accdd9b7e7bb72

diff --git a/man/curs_color.3x b/man/curs_color.3x
index f5604e03..02defb6a 100644
--- a/man/curs_color.3x
+++ b/man/curs_color.3x
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2017,2018 Free Software Foundation, Inc.              *
+.\" Copyright 2018-2019,2020 Thomas E. Dickey                                *
+.\" Copyright 1998-2016,2017 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            *
@@ -26,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_color.3x,v 1.55 2018/07/28 22:15:59 tom Exp $
+.\" $Id: curs_color.3x,v 1.63 2020/10/24 09:35:23 tom Exp $
 .TH curs_color 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -45,8 +46,12 @@
 \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
@@ -61,31 +66,31 @@
 .br
 \fBbool can_change_color(void);\fR
 .sp
-\fBint init_pair(short pair, short f, short b);\fR
+\fBint init_pair(short \fP\fIpair\fP\fB, short \fP\fIf\fP\fB, short \fP\fIb\fP\fB);\fR
 .br
-\fBint init_color(short color, short r, short g, short b);\fR
+\fBint init_color(short \fP\fIcolor\fP\fB, short \fP\fIr\fP\fB, short \fP\fIg\fP\fB, short \fP\fIb\fP\fB);\fR
 .br
 /* extensions */
 .br
-\fBint init_extended_pair(int pair, int f, int b);\fR
+\fBint init_extended_pair(int \fP\fIpair\fP\fB, int \fP\fIf\fP\fB, int \fP\fIb\fP\fB);\fR
 .br
-\fBint init_extended_color(int color, int r, int g, int b);\fR
+\fBint init_extended_color(int \fP\fIcolor\fP\fB, int \fP\fIr\fP\fB, int \fP\fIg\fP\fB, int \fP\fIb\fP\fB);\fR
 .sp
-\fBint color_content(short color, short *r, short *g, short *b);\fR
+\fBint color_content(short \fP\fIcolor\fP\fB, short *\fP\fIr\fP\fB, short *\fP\fIg\fP\fB, short *\fP\fIb\fP\fB);\fR
 .br
-\fBint pair_content(short pair, short *f, short *b);\fR
+\fBint pair_content(short \fP\fIpair\fP\fB, short *\fP\fIf\fP\fB, short *\fP\fIb\fP\fB);\fR
 .br
 /* extensions */
 .br
-\fBint extended_color_content(int color, int *r, int *g, int *b);\fR
+\fBint extended_color_content(int \fP\fIcolor\fP\fB, int *\fP\fIr\fP\fB, int *\fP\fIg\fP\fB, int *\fP\fIb\fP\fB);\fR
 .br
-\fBint extended_pair_content(int pair, int *f, int *b);\fR
+\fBint extended_pair_content(int \fP\fIpair\fP\fB, int *\fP\fIf\fP\fB, int *\fP\fIb\fP\fB);\fR
 .sp
 /* extensions */
 .br
 \fBvoid reset_color_pairs(void);\fR
 .sp
-\fBint COLOR_PAIR(int n);\fR
+\fBint COLOR_PAIR(int \fP\fIn\fP\fB);\fR
 .br
 \fBPAIR_NUMBER(\fR\fIattrs\fR\fB);\fP
 .br
@@ -205,15 +210,24 @@ they had when the terminal was just turned on.
 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.
@@ -230,7 +244,7 @@ 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).
+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,
@@ -268,7 +282,7 @@ 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
@@ -282,11 +296,14 @@ As an extension, ncurses allows you to set color pair \fB0\fP via
 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.
@@ -304,6 +321,15 @@ must be a value in the range \fB0\fP through \fB1000\fP.
 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
@@ -320,6 +346,15 @@ 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 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
@@ -334,6 +369,20 @@ i.e., in the range \fB1\fP through \fBCOLOR_PAIRS\-1\fR, inclusive.
 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
@@ -354,16 +403,32 @@ All other routines return the integer \fBERR\fR upon failure and an \fBOK\fR
 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.
+.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