diff options
Diffstat (limited to 'contrib/ncurses/man/curs_color.3x')
| -rw-r--r-- | contrib/ncurses/man/curs_color.3x | 68 |
1 files changed, 50 insertions, 18 deletions
diff --git a/contrib/ncurses/man/curs_color.3x b/contrib/ncurses/man/curs_color.3x index 18926d9..99e63ef 100644 --- a/contrib/ncurses/man/curs_color.3x +++ b/contrib/ncurses/man/curs_color.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2001,2002 Free Software Foundation, Inc. * +.\" Copyright (c) 1998-2004,2005 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,8 +26,10 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_color.3x,v 1.19 2002/02/16 22:38:32 tom Exp $ +.\" $Id: curs_color.3x,v 1.28 2005/12/18 00:00:37 tom Exp $ .TH curs_color 3X "" +.na +.hy 0 .SH NAME \fBstart_color\fR, \fBinit_pair\fR, @@ -37,6 +39,8 @@ \fBcolor_content\fR, \fBpair_content\fR, \fBCOLOR_PAIR\fR - \fBcurses\fR color manipulation routines +.ad +.hy .SH SYNOPSIS \fB# include <curses.h>\fR .br @@ -64,7 +68,7 @@ color (for the blank field on which the characters are displayed). A programmer initializes a color-pair with the routine \fBinit_pair\fR. After it has been initialized, \fBCOLOR_PAIR\fR(\fIn\fR), a macro defined in \fB<curses.h>\fR, can be used as a new video attribute. - +.PP If a terminal is capable of redefining colors, the programmer can use the routine \fBinit_color\fR to change the definition of a color. The routines \fBhas_colors\fR and \fBcan_change_color\fR return \fBTRUE\fR or \fBFALSE\fR, @@ -84,7 +88,7 @@ and white), and two global variables, \fBCOLORS\fR and and color-pairs the terminal can support). It also restores the colors on the terminal to the values they had when the terminal was just turned on. - +.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 color number, and the background color number. @@ -96,18 +100,20 @@ must be between \fB1\fR and \fBCOLOR_PAIRS-1\fR. .TP 5 - The value of the second and -third arguments must be between 0 and \fBCOLORS\fR (the 0 color pair is wired -to white on black and cannot be changed). +third arguments must be between 0 and \fBCOLORS\fR. +Color pair 0 is assumed to be white on black, +but is actually whatever the terminal implements before color is initialized. +It cannot be modified by the application. .PP If the color-pair was previously initialized, the screen is refreshed and all occurrences of that color-pair are changed to the new definition. - +.PP As an extension, ncurses allows you to set color pair 0 via the \fBassume_default_colors\fR routine, or to specify the use of default colors (color number \fB-1\fR) if you first invoke the \fBuse_default_colors\fR routine. - +.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 (for the amounts of red, green, and blue components). The value of the first @@ -116,18 +122,18 @@ argument must be between \fB0\fR and \fBCOLORS\fR. (See the section must be a value between 0 and 1000. When \fBinit_color\fR is used, all occurrences of that color on the screen immediately change to the new definition. - +.PP The \fBhas_colors\fR routine requires no arguments. It returns \fBTRUE\fR if the terminal can manipulate colors; otherwise, it returns \fBFALSE\fR. This routine facilitates writing terminal-independent programs. For example, a programmer can use it to decide whether to use color or some other video attribute. - +.PP The \fBcan_change_color\fR routine requires no arguments. It returns \fBTRUE\fR if the terminal supports colors and can change their definitions; other, it returns \fBFALSE\fR. This routine facilitates writing terminal-independent programs. - +.PP The \fBcolor_content\fR routine gives programmers a way to find the intensity of the red, green, and blue (RGB) components in a color. It requires four arguments: the color number, and three addresses of \fBshort\fRs for storing @@ -136,7 +142,7 @@ given color. The value of the first argument must be between 0 and \fBCOLORS\fR. The values that are stored at the addresses pointed to by the last three arguments are between 0 (no component) and 1000 (maximum amount of component). - +.PP The \fBpair_content\fR routine allows programmers to find out what colors a given color-pair consists of. It requires three arguments: the color-pair number, and two addresses of \fBshort\fRs for storing the foreground and the @@ -147,7 +153,7 @@ to by the second and third arguments are between 0 and \fBCOLORS\fR. In \fB<curses.h>\fR the following macros are defined. These are the default colors. \fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default background color for all terminals. - +.PP .nf \fBCOLOR_BLACK\fR \fBCOLOR_RED\fR @@ -161,22 +167,44 @@ background color for all terminals. .SH RETURN VALUE 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 (SVr4 specifies only "an integer value other than \fBERR\fR") upon successful completion. +.PP +X/Open defines no error conditions. +This implementation will return \fBERR\fR on attempts to +use color values outside the range 0 to COLORS-1 +(except for the default colors extension), +or use color pairs outside the range 0 to COLOR_PAIR-1. +Color values used in \fBinit_color\fP must be in the range 0 to 1000. +An error is returned from all functions +if the terminal has not been initialized. +An error is returned from secondary functions such as \fBinit_pair\fP +if \fBstart_color\fP was not called. +.RS +.TP 5 +\fBinit_color\fP +returns an error if the terminal does not support +this feature, e.g., if the \fIinitialize_color\fP capability is absent +from the terminal description. +.TP 5 +\fBstart_color\fP +returns an error +If the color table cannot be allocated. +.RE .SH NOTES In the \fIncurses\fR implementation, there is a separate color activation flag, color palette, color pairs table, and associated COLORS and COLOR_PAIRS 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 historical implementations may use a single shared color palette. - +.PP Note that setting an implicit background color via a color pair affects only character cells that a character write operation explicitly touches. To change 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 386 and 486 machines with VGA-compatible graphics: .TP 5 - @@ -201,8 +229,12 @@ but only if that routine has been first invoked. .PP The assumption that \fBCOLOR_BLACK\fR is the default background color for all terminals can be modified using the -\fBassume_default_colors\fP extension, - +\fBassume_default_colors\fP extension. +.PP +This implementation checks the pointers, +e.g., for the values returned by +\fBcolor_content\fP and \fBpair_content\fP, +and will treat those as optional parameters when null. .SH SEE ALSO \fBcurses\fR(3X), \fBcurs_initscr\fR(3X), |
