ncurses 6.0 - patch 20161112

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

diff --git a/man/curs_color.3x b/man/curs_color.3x
index 2c99f8f981496c6bb2e3794f9fd1856995bb8f96..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.38 2015/05/23 21:36:35 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,9 +269,18 @@ 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 default colors.
+These are the standard colors (ISO-6429).
 \fBcurses\fR also assumes that \fBCOLOR_BLACK\fR is the default
 background color for all terminals.
 .PP
@@ -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