ncurses 6.0 - patch 20160723

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

diff --git a/man/curs_color.3x b/man/curs_color.3x
index 21cdd133771ddfbe0fae613f8f02916b30312663..bb0a14ce6d2bec7504a6086e44e0b67accc76190 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            *
 .\"                                                                          *
 .\" 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.                                                           *
 .\"***************************************************************************
 .\"
 .\" 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 `` ``
 .TH curs_color 3X ""
 .ie \n(.g .ds `` \(lq
 .el       .ds `` ``


@@ -42,32 +42,38 @@
 \fBstart_color\fR,
 \fBinit_pair\fR,
 \fBinit_color\fR,
 \fBstart_color\fR,
 \fBinit_pair\fR,
 \fBinit_color\fR,

+.\" .br

 \fBhas_colors\fR,
 \fBcan_change_color\fR,
 \fBhas_colors\fR,
 \fBcan_change_color\fR,

+.\" .br

 \fBcolor_content\fR,
 \fBpair_content\fR,
 \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
 .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
 .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
 \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
 \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
 \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.
 .SH DESCRIPTION
 .SS Overview
 \fBcurses\fR supports color attributes on terminals with that capability.


@@ -77,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.
 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.
 .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.


@@ -102,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
 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
 Some functions such as \fBwattr_set\fP use a separate parameter which
 is the color pair number.
 .PP


@@ -263,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.
 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).
 .SS Colors
 In \fB<curses.h>\fR the following macros are defined.
 These are the standard colors (ISO-6429).