ncurses 6.1 - patch 20190121

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

diff --git a/man/curs_color.3x b/man/curs_color.3x
index f5604e03b414e78f1de2a99ff02b3ab0692a3a76..965af772af654de3b6b9f3ef1abceb2cf873332f 100644 (file)
--- a/man/curs_color.3x
+++ b/man/curs_color.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
 .\"***************************************************************************

-.\" Copyright (c) 1998-2017,2018 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            *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *


@@ -26,7 +26,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_color.3x,v 1.55 2018/07/28 22:15:59 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 `` ``
 .TH curs_color 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``


@@ -45,8 +45,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


@@ -205,15 +209,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 +243,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 +281,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 +295,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 +320,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 +345,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 +368,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 +402,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