ncurses 6.2 - patch 20210213

[ncurses.git] / man / curs_color.3x

diff --git a/man/curs_color.3x b/man/curs_color.3x
index f5604e03b414e78f1de2a99ff02b3ab0692a3a76..02defb6a793c58f1de8cd966e030fe21678d7c64 100644 (file)
--- 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            *
 .\"                                                                          *
 .\" 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.                                                           *
 .\"***************************************************************************
 .\"
 .\" 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 `` ``
 .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,
 \fBcan_change_color\fR,
 \fBinit_pair\fR,
 \fBinit_color\fR,

+\fBinit_extended_pair\fR,
+\fBinit_extended_color\fR,

 \fBcolor_content\fR,
 \fBpair_content\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
 \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
 .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
 .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
 .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
 .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
 .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
 .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
 .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
 .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
 .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
 .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
 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),
 .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.
 .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
 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,
 .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.
 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 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.
 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
 .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.
 .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.
 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
 .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.
 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
 .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.
 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
 .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.
 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.
 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.
 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.
 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.
 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
 .RS 3
 .TP 5
 \fBinit_color\fP