<!--
****************************************************************************
- * Copyright (c) 1998-2010,2015 Free Software Foundation, Inc. *
+ * Copyright (c) 1998-2015,2016 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 *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_color.3x,v 1.40 2015/12/05 20:09:42 tom Exp @
+ * @Id: curs_color.3x,v 1.42 2016/07/24 00:02:15 tom Exp @
+ * .br
+ * .br
+ * .br
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
<STRONG>start_color</STRONG>, <STRONG>init_pair</STRONG>, <STRONG>init_color</STRONG>, <STRONG>has_colors</STRONG>,
- <STRONG>can_change_color</STRONG>, <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>, <STRONG>COLOR_PAIR</STRONG>
- - <STRONG>curses</STRONG> color manipulation routines
+ <STRONG>can_change_color</STRONG>, <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>, <STRONG>COLOR_PAIR</STRONG>,
+ <STRONG>PAIR_NUMBER</STRONG> - <STRONG>curses</STRONG> color manipulation routines
</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
- <STRONG>#</STRONG> <STRONG>include</STRONG> <STRONG><curses.h></STRONG>
+ <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
<STRONG>int</STRONG> <STRONG>start_color(void);</STRONG>
<STRONG>int</STRONG> <STRONG>init_pair(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>f,</STRONG> <STRONG>short</STRONG> <STRONG>b);</STRONG>
<STRONG>int</STRONG> <STRONG>init_color(short</STRONG> <STRONG>color,</STRONG> <STRONG>short</STRONG> <STRONG>r,</STRONG> <STRONG>short</STRONG> <STRONG>g,</STRONG> <STRONG>short</STRONG> <STRONG>b);</STRONG>
+
<STRONG>bool</STRONG> <STRONG>has_colors(void);</STRONG>
<STRONG>bool</STRONG> <STRONG>can_change_color(void);</STRONG>
+
<STRONG>int</STRONG> <STRONG>color_content(short</STRONG> <STRONG>color,</STRONG> <STRONG>short</STRONG> <STRONG>*r,</STRONG> <STRONG>short</STRONG> <STRONG>*g,</STRONG> <STRONG>short</STRONG>
<STRONG>*b);</STRONG>
<STRONG>int</STRONG> <STRONG>pair_content(short</STRONG> <STRONG>pair,</STRONG> <STRONG>short</STRONG> <STRONG>*f,</STRONG> <STRONG>short</STRONG> <STRONG>*b);</STRONG>
+
<STRONG>int</STRONG> <STRONG>COLOR_PAIR(int</STRONG> <STRONG>n);</STRONG>
+ <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM><STRONG>);</STRONG>
</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
background color (for the blank field on which the charac-
ters are displayed). A programmer initializes a color-
pair with the routine <STRONG>init_pair</STRONG>. After it has been ini-
- tialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>), a macro defined in <STRONG><curses.h></STRONG>,
- can be used as a new video attribute.
+ tialized, <STRONG>COLOR_PAIR</STRONG>(<EM>n</EM>) can be used to convert the pair to
+ a video attribute.
If a terminal is capable of redefining colors, the pro-
grammer can use the routine <STRONG>init_color</STRONG> to change the defi-
<STRONG>o</STRONG> the background character (e.g., <STRONG>wbkgdset</STRONG>).
Per-character and window attributes are usually set by a
- parameter containing video attributes including a <STRONG>COL-</STRONG>
- <STRONG>OR_PAIR</STRONG> value. Some functions such as <STRONG>wattr_set</STRONG> use a
- separate parameter which is the color pair number.
+ parameter containing video attributes including a color
+ pair value. Some functions such as <STRONG>wattr_set</STRONG> use a sepa-
+ rate parameter which is the color pair number.
The background character is a special case: it includes a
character value, just as if it were passed to <STRONG>waddch</STRONG>.
to by the second and third arguments are in the range <STRONG>0</STRONG>
through <STRONG>COLORS</STRONG>, inclusive.
+ <STRONG>PAIR_NUMBER(</STRONG><EM>attrs</EM>) extracts the color value from its <EM>attrs</EM>
+ parameter and returns it as a color pair number. Its in-
+ verse <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number to an at-
+ tribute. Attributes can hold color pairs in the range 0
+ to 255. If you need a color pair larger than that, you
+ must use functions such as <STRONG>attr_set</STRONG> (which pass the color
+ pair as a separate parameter) rather than the legacy func-
+ tions such as <STRONG>attrset</STRONG>.
+
</PRE><H3><a name="h3-Colors">Colors</a></H3><PRE>
In <STRONG><curses.h></STRONG> the following macros are defined. These are
- the standard colors (ISO-6429). <STRONG>curses</STRONG> also assumes that
+ the standard colors (ISO-6429). <STRONG>curses</STRONG> also assumes that
<STRONG>COLOR_BLACK</STRONG> is the default background color for all termi-
nals.
</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- The routines <STRONG>can_change_color()</STRONG> and <STRONG>has_colors()</STRONG> return
+ The routines <STRONG>can_change_color()</STRONG> and <STRONG>has_colors()</STRONG> return
<STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>.
All other routines return the integer <STRONG>ERR</STRONG> upon failure and
- an <STRONG>OK</STRONG> (SVr4 specifies only "an integer value other than
+ an <STRONG>OK</STRONG> (SVr4 specifies only "an integer value other than
<STRONG>ERR</STRONG>") upon successful completion.
- X/Open defines no error conditions. This implementation
- will return <STRONG>ERR</STRONG> on attempts to use color values outside
+ X/Open defines no error conditions. This implementation
+ will return <STRONG>ERR</STRONG> on attempts to use color values outside
the range <STRONG>0</STRONG> to COLORS-1 (except for the default colors ex-
- tension), or use color pairs outside the range <STRONG>0</STRONG> to <STRONG>COL-</STRONG>
- <STRONG>OR_PAIRS-1</STRONG>. Color values used in <STRONG>init_color</STRONG> must be in
- the range <STRONG>0</STRONG> to <STRONG>1000</STRONG>. An error is returned from all func-
- tions if the terminal has not been initialized. An error
- is returned from secondary functions such as <STRONG>init_pair</STRONG> if
+ tension), or use color pairs outside the range <STRONG>0</STRONG> to <STRONG>COL-</STRONG>
+ <STRONG>OR_PAIRS-1</STRONG>. Color values used in <STRONG>init_color</STRONG> must be in
+ the range <STRONG>0</STRONG> to <STRONG>1000</STRONG>. An error is returned from all func-
+ tions if the terminal has not been initialized. An error
+ is returned from secondary functions such as <STRONG>init_pair</STRONG> if
<STRONG>start_color</STRONG> was not called.
<STRONG>init_color</STRONG>
- returns an error if the terminal does not support
- this feature, e.g., if the <EM>initialize</EM><STRONG>_</STRONG><EM>color</EM> capa-
+ returns an error if the terminal does not support
+ this feature, e.g., if the <EM>initialize</EM><STRONG>_</STRONG><EM>color</EM> capa-
bility is absent from the terminal description.
<STRONG>start_color</STRONG>
- returns an error if the color table cannot be al-
+ returns an error if the color table cannot be al-
located.
</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- In the <EM>ncurses</EM> implementation, there is a separate color
+ In the <EM>ncurses</EM> 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 <STRONG>start_color</STRONG> function only affects the current screen.
+ sociated COLORS and COLOR_PAIRS counts for each screen;
+ the <STRONG>start_color</STRONG> 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
+ 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
+ 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 <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>.
- Several caveats apply on 386 and 486 machines with VGA-
+ Several caveats apply on 386 and 486 machines with VGA-
compatible graphics:
- <STRONG>o</STRONG> COLOR_YELLOW is actually brown. To get yellow, use
+ <STRONG>o</STRONG> COLOR_YELLOW is actually brown. To get yellow, use
COLOR_YELLOW combined with the <STRONG>A_BOLD</STRONG> attribute.
<STRONG>o</STRONG> The A_BLINK attribute should in theory cause the back-
- ground to go bright. This often fails to work, and
+ 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
+ Paradise and compatibles) do the wrong thing when you
+ try to set a bright "yellow" background (you get a
blinking yellow foreground instead).
<STRONG>o</STRONG> Color RGB values are not settable.
</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- This implementation satisfies XSI Curses's minimum maxi-
+ This implementation satisfies XSI Curses's minimum maxi-
mums for <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG>.
- The <STRONG>init_pair</STRONG> routine accepts negative values of fore-
- ground and background color to support the <STRONG>use_de-</STRONG>
- <STRONG>fault_colors</STRONG> extension, but only if that routine has been
+ The <STRONG>init_pair</STRONG> routine accepts negative values of fore-
+ ground and background color to support the <STRONG>use_de-</STRONG>
+ <STRONG>fault_colors</STRONG> extension, but only if that routine has been
first invoked.
- The assumption that <STRONG>COLOR_BLACK</STRONG> is the default background
- color for all terminals can be modified using the <STRONG>as-</STRONG>
+ The assumption that <STRONG>COLOR_BLACK</STRONG> is the default background
+ color for all terminals can be modified using the <STRONG>as-</STRONG>
<STRONG>sume_default_colors</STRONG> extension.
- This implementation checks the pointers, e.g., for the
- values returned by <STRONG>color_content</STRONG> and <STRONG>pair_content</STRONG>, and
+ This implementation checks the pointers, e.g., for the
+ values returned by <STRONG>color_content</STRONG> and <STRONG>pair_content</STRONG>, and
will treat those as optional parameters when null.
projects / ncurses.git / blobdiff