.\"***************************************************************************
-.\" 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 *
.\" 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 $
.TH curs_color 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
\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
-.br
+.sp
\fBint COLOR_PAIR(int n);\fR
.br
+\fBPAIR_NUMBER(\fR\fIattrs\fR\fB);\fP
+.br
.SH DESCRIPTION
.SS Overview
\fBcurses\fR supports color attributes on terminals with that capability.
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.
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
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).