X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_color.3x.html;h=4ebe0da04f4db20520b1216d40b66cfefe71c61b;hp=8840f1dfe6fc1bfe75813d2ff0b02c357051f7c5;hb=0948e2c7ac34642a1f8a3a85000933bcbb258cff;hpb=55ccd2b959766810cf7db8d1c4462f338ce0afc8
diff --git a/doc/html/man/curs_color.3x.html b/doc/html/man/curs_color.3x.html
index 8840f1df..4ebe0da0 100644
--- a/doc/html/man/curs_color.3x.html
+++ b/doc/html/man/curs_color.3x.html
@@ -1,7 +1,7 @@
-
+
@@ -55,6 +55,7 @@
SYNOPSIS
# include <curses.h>
+
int start_color(void);
int init_pair(short pair, short f, short b);
int init_color(short color, short r, short g, short b);
@@ -77,90 +78,105 @@
ters are displayed). A programmer initializes a color-
pair with the routine init_pair. After it has been ini-
tialized, COLOR_PAIR(n), a macro defined in <curses.h>,
- can be used as a new video attribute. If a terminal is
- capable of redefining colors, the programmer can use the
- routine init_color to change the definition of a color.
- The routines has_colors and can_change_color return TRUE
- or FALSE, depending on whether the terminal has color ca-
- pabilities and whether the programmer can change the col-
- ors. The routine color_content allows a programmer to ex-
- tract the amounts of red, green, and blue components in an
- initialized color. The routine pair_content allows a pro-
- grammer to find out how a given color-pair is currently
- defined.
+ can be used as a new video attribute.
+
+ If a terminal is capable of redefining colors, the pro-
+ grammer can use the routine init_color to change the defi-
+ nition of a color. The routines has_colors and
+ can_change_color return TRUE or FALSE, depending on
+ whether the terminal has color capabilities and whether
+ the programmer can change the colors. The routine col-
+ or_content allows a programmer to extract the amounts of
+ red, green, and blue components in an initialized color.
+ The routine pair_content allows a programmer to find out
+ how a given color-pair is currently defined.
Routine Descriptions
The start_color routine requires no arguments. It must be
- called if the programmer wants to use colors, and before
- any other color manipulation routine is called. It is
- good practice to call this routine right after initscr.
- start_color initializes eight basic colors (black, red,
- green, yellow, blue, magenta, cyan, and white), and two
- global variables, COLORS and COLOR_PAIRS (respectively
- defining the maximum number of colors and color-pairs the
+ called if the programmer wants to use colors, and before
+ any other color manipulation routine is called. It is
+ good practice to call this routine right after initscr.
+ start_color initializes eight basic colors (black, red,
+ green, yellow, blue, magenta, cyan, and white), and two
+ global variables, COLORS and COLOR_PAIRS (respectively
+ defining the maximum number of colors 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. The init_pair 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. For portable applica-
- tions:
-
- - The value of the first argument must be between 1 and
- COLOR_PAIRS-1.
-
- - The value of the second and third arguments must be
- between 0 and COLORS. 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.
-
- If the color-pair was previously initialized, the screen
- is refreshed and all occurrences of that color-pair are
- changed to the new definition. As an extension, ncurses
- allows you to set color pair 0 via the assume_default_col-
- ors routine, or to specify the use of default colors (col-
- or number -1) if you first invoke the use_default_colors
- routine. The init_color 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 argument must be between 0 and COLORS. (See the
- section Colors for the default color index.) Each of the
- last three arguments must be a value between 0 and 1000.
- When init_color is used, all occurrences of that color on
- the screen immediately change to the new definition. The
- has_colors routine requires no arguments. It returns TRUE
- if the terminal can manipulate colors; otherwise, it re-
- turns FALSE. This routine facilitates writing terminal-
- independent programs. For example, a programmer can use
- it to decide whether to use color or some other video at-
- tribute. The can_change_color routine requires no argu-
- ments. It returns TRUE if the terminal supports colors
- and can change their definitions; other, it returns FALSE.
- This routine facilitates writing terminal-independent pro-
- grams. The color_content 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 shorts for storing
- the information about the amounts of red, green, and blue
- components in the given color. The value of the first ar-
- gument must be between 0 and COLORS. The values that are
- stored at the addresses pointed to by the last three argu-
- ments are between 0 (no component) and 1000 (maximum
- amount of component). The pair_content 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 shorts for storing the fore-
- ground and the background color numbers. The value of the
- first argument must be between 1 and COLOR_PAIRS-1. The
- values that are stored at the addresses pointed to by the
- second and third arguments are between 0 and COLORS.
+ turned on.
+
+ The init_pair 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. For portable applications:
+
+ o The value of the first argument must be between 1 and
+ COLOR_PAIRS-1, except that if default colors are used
+ (see use_default_colors) the upper limit is adjusted
+ to allow for extra pairs which use a default color in
+ foreground and/or background.
+
+ o The value of the second and third arguments must be
+ between 0 and COLORS. 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.
+
+ If the color-pair was previously initialized, the screen
+ is refreshed and all occurrences of that color-pair are
+ changed to the new definition.
+
+ As an extension, ncurses allows you to set color pair 0
+ via the assume_default_colors routine, or to specify the
+ use of default colors (color number -1) if you first in-
+ voke the use_default_colors routine.
+
+ The init_color 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
+ argument must be between 0 and COLORS. (See the section
+ Colors for the default color index.) Each of the last
+ three arguments must be a value between 0 and 1000. When
+ init_color is used, all occurrences of that color on the
+ screen immediately change to the new definition.
+
+ The has_colors routine requires no arguments. It returns
+ TRUE if the terminal can manipulate colors; otherwise, it
+ returns FALSE. This routine facilitates writing terminal-
+ independent programs. For example, a programmer can use
+ it to decide whether to use color or some other video at-
+ tribute.
+
+ The can_change_color routine requires no arguments. It
+ returns TRUE if the terminal supports colors and can
+ change their definitions; other, it returns FALSE. This
+ routine facilitates writing terminal-independent programs.
+
+ The color_content 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 shorts for storing the information
+ about the amounts of red, green, and blue components in
+ the given color. The value of the first argument must be
+ between 0 and COLORS. The values that are stored at the
+ addresses pointed to by the last three arguments are be-
+ tween 0 (no component) and 1000 (maximum amount of compo-
+ nent).
+
+ The pair_content 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 shorts for storing the foreground and the background
+ color numbers. The value of the first argument must be
+ between 1 and COLOR_PAIRS-1. The values that are stored
+ at the addresses pointed to by the second and third argu-
+ ments are between 0 and COLORS.
Colors
In <curses.h> the following macros are defined. These are
the default colors. curses also assumes that COLOR_BLACK
is the default background color for all terminals.
+
COLOR_BLACK
COLOR_RED
COLOR_GREEN
@@ -174,58 +190,62 @@
RETURN VALUE
The routines can_change_color() and has_colors() return
- TRUE or FALSE. All other routines return the integer ERR
- upon failure and an OK (SVr4 specifies only "an integer
- value other than ERR") upon successful completion.
+ TRUE or FALSE.
+
+ All other routines return the integer ERR upon failure and
+ an OK (SVr4 specifies only "an integer value other than
+ ERR") upon successful completion.
X/Open defines no error conditions. This implementation
will return ERR on attempts to use color values outside
the range 0 to COLORS-1 (except for the default colors ex-
tension), or use color pairs outside the range 0 to COL-
- OR_PAIR-1. Color values used in init_color 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 re-
- turned from secondary functions such as init_pair if
+ OR_PAIRS-1. Color values used in init_color must be in
+ the range 0 to 1000. An error is returned from all func-
+ tions if the terminal has not been initialized. An error
+ is returned from secondary functions such as init_pair if
start_color was not called.
- init_color
- returns an error if the terminal does not sup-
- port this feature, e.g., if the initial-
- ize_color capability is absent from the termi-
- nal description.
+ init_color
+ returns an error if the terminal does not support
+ this feature, e.g., if the initialize_color capa-
+ bility is absent from the terminal description.
- start_color
- returns an error If the color table cannot be
- allocated.
+ start_color
+ returns an error if the color table cannot be al-
+ located.
NOTES
- In the ncurses implementation, there is a separate color
+ In the ncurses implementation, there is a separate color
activation flag, color palette, color pairs table, and as-
- sociated COLORS and COLOR_PAIRS counts for each screen;
- the start_color function only affects the current screen.
+ sociated COLORS and COLOR_PAIRS counts for each screen;
+ the start_color 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. Note that setting an implicit back-
- ground 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
- curs_bkgd(3x). Several caveats apply on 386 and 486 ma-
- chines with VGA-compatible graphics:
+ mind, and historical implementations may use a single
+ shared color palette.
+
+ 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 curs_bkgd(3x).
+
+ Several caveats apply on 386 and 486 machines with VGA-
+ compatible graphics:
- - COLOR_YELLOW is actually brown. To get yellow, use
- COLOR_YELLOW combined with the A_BOLD attribute.
+ o COLOR_YELLOW is actually brown. To get yellow, use
+ COLOR_YELLOW combined with the A_BOLD attribute.
- - The A_BLINK attribute should in theory cause the
- background to go bright. This often fails to work,
- and even some cards for which it mostly works (such
- as the Paradise and compatibles) do the wrong thing
- when you try to set a bright "yellow" background (you
- get a blinking yellow foreground instead).
+ o The A_BLINK attribute should in theory cause the back-
+ ground to go bright. This often fails to work, and
+ even some cards for which it mostly works (such as the
+ Paradise and compatibles) do the wrong thing when you
+ try to set a bright "yellow" background (you get a
+ blinking yellow foreground instead).
- - Color RGB values are not settable.
+ o Color RGB values are not settable.
@@ -249,8 +269,8 @@
SEE ALSO
- curses(3x), curs_initscr(3x), curs_attr(3x), default_col-
- ors(3x)
+ curses(3x), curs_initscr(3x), curs_attr(3x), curs_vari-
+ ables(3x), default_colors(3x)