.\"
.\" Author: Thomas E. Dickey
.\"
-.\" $Id: new_pair.3x,v 1.30 2023/09/16 23:38:39 tom Exp $
-.TH new_pair 3X 2023-09-16 "ncurses 6.4" "Library calls"
+.\" $Id: new_pair.3x,v 1.36 2023/09/23 22:37:46 tom Exp $
+.TH new_pair 3X 2023-09-23 "ncurses 6.4" "Library calls"
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
\fB\%free_pair\fP \-
dynamically allocate \fIcurses\fR color pairs
.SH SYNOPSIS
+.nf
\fB#include <curses.h>\fP
-.sp
+.PP
\fBint alloc_pair(int \fIfg\fB, int \fIbg\fB);\fR
-.br
\fBint find_pair(int \fIfg\fB, int \fIbg\fB);\fR
-.br
\fBint free_pair(int \fIpair\fB);\fR
+.fi
.SH DESCRIPTION
-These functions are an extension to the curses library.
+These functions are an extension to the \fIcurses\fP library.
They permit an application to dynamically allocate a color pair using
the foreground/background colors rather than assign a fixed color pair number,
and return an unused pair to the pool.
of a given character cell without rewriting it.
That is, the foreground and background colors are applied as a pair.
.bP
-Color pairs are the curses library's way of managing a color palette
+Color pairs are the \fIcurses\fP library's way of managing a color palette
on a terminal.
If the library does not keep track of the \fIcombinations\fP of
colors which are displayed, it will be inefficient.
The size of the table is determined by the terminfo \fBpairs\fP capability.
The table is shared with \fBinit_pair\fP;
in fact \fBalloc_pair\fP calls \fBinit_pair\fP after
-updating the ncurses library's fast index to the colors versus color pairs.
+updating the \fIncurses\fP library's fast index to the colors versus color pairs.
.SS find_pair
The \fBfind_pair\fP function accepts parameters for
foreground and background color, and
Likewise, \fBfree_pair\fP returns \fBOK\fP unless it encounters an
error updating the fast index or if no such color pair is in use.
.SH PORTABILITY
-These routines are specific to ncurses.
+These routines are specific to \fIncurses\fP.
They were not supported on
Version 7, BSD or System V implementations.
It is recommended that
-any code depending on them be conditioned using NCURSES_VERSION.
+any code depending on them be conditioned using \fB\%NCURSES_VERSION\fP.
.SH SEE ALSO
-\fBcurs_color\fP(3X).
+\fBcurs_color\fP(3X)
.SH AUTHOR
-Thomas Dickey.
+Thomas Dickey