ncurses 6.1 - patch 20190209

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

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

-.\" 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            *
 .\"                                                                          *
 .\" 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.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 `` ``
 .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


@@ -175,7 +179,7 @@ background color for all terminals.
 .fi
 .PP
 Some terminals support more than the eight (8) \*(``ANSI\*('' colors.
 .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
 .SH VARIABLES
 .SS COLORS
 is initialized by \fBstart_color\fP to the maximum number of colors


@@ -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,9 +243,10 @@ 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
 .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,
 (see \fBterminfo\fR(\*n)).
 .bP
 legal color pair values are in the range \fB1\fP to \fBCOLOR_PAIRS\-1\fP,


@@ -261,12 +275,13 @@ This routine facilitates writing terminal-independent programs.
 .SS init_pair
 .PP
 The \fBinit_pair\fR routine changes the definition of a color-pair.
 .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.
 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 upper limit is adjusted to allow for extra pairs which use
 a default color in foreground and/or background.
 .bP


@@ -280,15 +295,19 @@ 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.

-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;
 (for the amounts of red, green, and blue components).
 .bP
 The first argument must be a legal color value;


@@ -301,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


@@ -315,7 +343,17 @@ The first argument must be a legal color value, i.e.,
 .bP
 The values that are stored at the addresses pointed to by the
 last three arguments are in the range
 .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
 .SS pair_content
 .PP
 The \fBpair_content\fR routine allows programmers to find out what colors a


@@ -330,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


@@ -346,19 +398,36 @@ The routines \fBcan_change_color\fR and \fBhas_colors\fR return \fBTRUE\fR
 or \fBFALSE\fR.
 .PP
 All other routines return the integer \fBERR\fR upon failure and an \fBOK\fR
 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.
 .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.

-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.
 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


@@ -371,7 +440,8 @@ 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,
 .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
 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


@@ -383,7 +453,8 @@ To change
 the background color used when parts of a window are blanked by erasing or
 scrolling operations, see \fBcurs_bkgd\fR(3X).
 .PP
 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.
 .bP
 COLOR_YELLOW is actually brown.
 To get yellow, use COLOR_YELLOW combined with the \fBA_BOLD\fR attribute.