ncurses 5.7 - patch 20100515
[ncurses.git] / man / curs_color.3x
index 7ca76907b59f0781c619bfe331a392d69a353f24..801ac9fa6b0029f3e8a09939a5ed554a2729880c 100644 (file)
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2004,2005 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2005,2009 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.27 2005/05/15 16:55:36 tom Exp $
+.\" $Id: curs_color.3x,v 1.29 2009/01/24 23:10:02 tom Exp $
 .TH curs_color 3X ""
 .na
 .hy 0
@@ -68,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.
-.SP
+.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,
@@ -88,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.
-.SP
+.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,7 +96,10 @@ For portable applications:
 .TP 5
 -
 The value of the first argument
-must be between \fB1\fR and \fBCOLOR_PAIRS-1\fR.
+must be between \fB1\fR and \fBCOLOR_PAIRS-1\fR,
+except that if default colors are used (see \fBuse_default_colors\fP)
+the upper limit is adjusted to allow for extra pairs which use
+a default color in foreground and/or background.
 .TP 5
 -
 The value of the second and
@@ -108,12 +111,12 @@ 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.
-.SP
+.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.
-.SP
+.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
@@ -122,18 +125,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.
-.SP
+.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.
-.SP
+.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.
-.SP
+.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
@@ -142,7 +145,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).
-.SP
+.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
@@ -153,7 +156,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.
-.SP
+.PP
 .nf
       \fBCOLOR_BLACK\fR
       \fBCOLOR_RED\fR
@@ -167,7 +170,7 @@ background color for all terminals.
 .SH RETURN VALUE
 The routines \fBcan_change_color()\fR and \fBhas_colors()\fR return \fBTRUE\fR
 or \fBFALSE\fR.
-.SP
+.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.
@@ -199,12 +202,12 @@ 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.
-.SP
+.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).
-.SP
+.PP
 Several caveats apply on 386 and 486 machines with VGA-compatible graphics:
 .TP 5
 -