ncurses 6.0 - patch 20161224

[ncurses.git] / man / curs_color.3x

diff --git a/man/curs_color.3x b/man/curs_color.3x
index 46af844e9ecdfe4e3e29a9da4f9307a11e1b2b2a..05288b5d835b5c9a5c955ecddb7f632e43129863 100644 (file)
--- a/man/curs_color.3x
+++ b/man/curs_color.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" 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            *
@@ -26,7 +26,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_color.3x,v 1.39 2015/06/06 23:29:02 tom Exp $
+.\" $Id: curs_color.3x,v 1.45 2016/10/15 17:10:19 tom Exp $
 .TH curs_color 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``
@@ -42,29 +42,37 @@
 \fBstart_color\fR,
 \fBinit_pair\fR,
 \fBinit_color\fR,
+.\" .br
 \fBhas_colors\fR,
 \fBcan_change_color\fR,
+.\" .br
 \fBcolor_content\fR,
 \fBpair_content\fR,
-\fBCOLOR_PAIR\fR \- \fBcurses\fR color manipulation routines
+.\" .br
+\fBCOLOR_PAIR\fR,
+\fBPAIR_NUMBER\fR \- \fBcurses\fR color manipulation routines
 .ad
 .hy
 .SH SYNOPSIS
-\fB# include <curses.h>\fR
+\fB#include <curses.h>\fR
 .sp
 \fBint start_color(void);\fR
 .br
 \fBint init_pair(short pair, short f, short b);\fR
 .br
 \fBint init_color(short color, short r, short g, short b);\fR
-.br
+.sp
 \fBbool has_colors(void);\fR
 .br
 \fBbool can_change_color(void);\fR
-.br
+.sp
 \fBint color_content(short color, short *r, short *g, short *b);\fR
 .br
 \fBint pair_content(short pair, short *f, short *b);\fR
+.sp
+\fBint COLOR_PAIR(int n);\fR
+.br
+\fBPAIR_NUMBER(\fR\fIattrs\fR\fB);\fP
 .br
 .SH DESCRIPTION
 .SS Overview
@@ -75,8 +83,8 @@ Colors are always used in pairs (referred to as color-pairs).
 A color-pair consists of a foreground color (for characters) and a background
 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.
+After it has been initialized, \fBCOLOR_PAIR\fR(\fIn\fR)
+can be used to convert the pair to a 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.
@@ -100,7 +108,7 @@ the window attribute (e.g., by \fBwattrset\fP), and
 the background character (e.g., \fBwbkgdset\fP).
 .PP
 Per-character and window attributes are usually set by a parameter containing
-video attributes including a \fBCOLOR_PAIR\fP value.
+video attributes including a color pair value.
 Some functions such as \fBwattr_set\fP use a separate parameter which
 is the color pair number.
 .PP
@@ -157,7 +165,7 @@ initializes its internal table representing the
 red, green and blue components of the color palette.
 .IP
 The components depend on whether the terminal uses
-CGA (aka "ANSI") or
+CGA (aka \*(lqANSI\*(rq) 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),
@@ -261,6 +269,15 @@ 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.
+.PP
+\fBPAIR_NUMBER(\fR\fIattrs\fR) extracts the color
+value from its \fIattrs\fP parameter and returns it as a color pair number.
+Its inverse \fBCOLOR_PAIR(\fR\fIn\fR\fB)\fR converts a color pair number
+to an attribute.
+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 \fBattr_set\fP (which pass the color pair as a separate parameter)
+rather than the legacy functions such as \fBattrset\fP.
 .SS Colors
 In \fB<curses.h>\fR the following macros are defined.
 These are the standard colors (ISO-6429).
@@ -278,11 +295,11 @@ background color for all terminals.
       \fBCOLOR_WHITE\fR
 .fi
 .SH RETURN VALUE
-The routines \fBcan_change_color()\fR and \fBhas_colors()\fR return \fBTRUE\fR
+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
+(SVr4 specifies only \*(lqan integer value other than \fBERR\fR\*(rq) upon successful
 completion.
 .PP
 X/Open defines no error conditions.
@@ -299,7 +316,7 @@ if \fBstart_color\fP was not called.
 .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
+this feature, e.g., if the \fBinitialize_color\fP capability is absent
 from the terminal description.
 .TP 5
 \fBstart_color\fP
@@ -328,7 +345,7 @@ 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).
+\*(lqyellow\*(rq background (you get a blinking yellow foreground instead).
 .bP
 Color RGB values are not settable.
 .SH PORTABILITY