X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_color.3x;h=965af772af654de3b6b9f3ef1abceb2cf873332f;hp=f5604e03b414e78f1de2a99ff02b3ab0692a3a76;hb=b60a2772d9f149d8e900c1d5a09a53a56a0837a8;hpb=17c5992a16be94247b83f2bbb9accdd9b7e7bb72;ds=sidebyside diff --git a/man/curs_color.3x b/man/curs_color.3x index f5604e03..965af772 100644 --- 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 * @@ -26,7 +26,7 @@ .\" 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 `` `` @@ -45,8 +45,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 @@ -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 -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 +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 -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 +281,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 +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. +.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 +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. +.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 +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. +.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 +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. +.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 +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. +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