.\"***************************************************************************
-.\" Copyright (c) 2017 Free Software Foundation, Inc. *
+.\" Copyright 2018-2020,2021 Thomas E. Dickey *
+.\" Copyright 2017 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 *
.\"
.\" Author: Thomas E. Dickey
.\"
-.\" $Id: new_pair.3x,v 1.8 2017/03/09 09:59:11 tom Exp $
+.\" $Id: new_pair.3x,v 1.16 2021/06/17 21:26:02 tom Exp $
.TH new_pair 3X ""
.ie \n(.g .ds `` \(lq
.el .ds `` ``
.ie \n(.g .ds '' \(rq
.el .ds '' ''
.de bP
-.IP \(bu 4
+.ie n .IP \(bu 4
+.el .IP \(bu 2
..
.de NS
-.ie \n(.sp
+.ie n .sp
.el .sp .5
-.ie \n(.in +4
+.ie n .in +4
.el .in +2
.nf
.ft C \" Courier
.de NE
.fi
.ft R
-.in -4
+.ie n .in -4
+.el .in -2
..
.SH NAME
\fBalloc_pair\fP,
+\fBfind_pair\fP,
\fBfree_pair\fP \- new curses color-pair functions
.SH SYNOPSIS
\fB#include <curses.h>\fP
.sp
-\fBint alloc_pair(int fg, int bg);\fP
+\fBint alloc_pair(int \fP\fIfg\fP\fB, int \fP\fIbg\fP\fB);\fP
.br
-\fBint free_pair(int pair);\fP
+\fBint find_pair(int \fP\fIfg\fP\fB, int \fP\fIbg\fP\fB);\fP
+.br
+\fBint free_pair(int \fP\fIpair\fP\fB);\fP
.SH DESCRIPTION
These functions are an extension to the curses library.
They permit an application to dynamically allocate a color pair using
.bP
Color pairs are the curses library's way of managing a color palette
on a terminal.
-If the library does not keep track of the \fIcombinations\fP of
+If the library does not keep track of the \fIcombinations\fP of
colors which are displayed, it will be inefficient.
.bP
For simple terminal emulators
\fBCOLORS\fP\fI * \fP\fBCOLORS\fP
.NE
.bP
-Terminals which support \fIdefault colors\fP distinct from \*(``ANSI colors\*(''
+Terminals which support \fIdefault colors\fP distinct
+from \*(``ANSI colors\*(''
add to the possible combinations, producing this total:
.NS
\fI( \fP\fBCOLORS\fP\fI + 1 ) * ( \fP\fBCOLORS\fP\fI + 1 )\fP
implement a predefined color scheme.
.IP
Beyond that lies in the realm of programs using the foreground
-and background colors for \*(``ASCII art\*(''
+and background colors for \*(``ASCII art\*(''
(or some other non-textual application).
.IP
Also beyond those few dozen pairs, the required size for a table
foreground and background color, and
checks if that color combination is already associated with a color pair.
.bP
-If the combination already exists, \fBalloc_pair\fP returns the existing pair.
+If the combination already exists,
+\fBalloc_pair\fP returns the existing pair.
.bP
-If the combination does not exist, \fBalloc_pair\fP allocates a new color pair and returns that.
+If the combination does not exist,
+\fBalloc_pair\fP allocates a new color pair and returns that.
.bP
If the table fills up, \fBalloc_pair\fP discards the least-recently
allocated entry using \fBfree_pair\fP and allocates a new color pair.
The \fBalloc_pair\fP function returns a color pair number in the range
1 through \fBCOLOR_PAIRS\fP\-1, unless it encounters an error updating
its fast index to the color pair values, preventing it from allocating
-a color pair. In that case, it returns \-1.
+a color pair.
+In that case, it returns \-1.
.PP
The \fBfind_pair\fP function returns a color pair number if the
given color combination has been associated with a color pair,
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. They were not supported on
-Version 7, BSD or System V implementations. It is recommended that
+These routines are specific to ncurses.
+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.
.SH SEE ALSO
-\fBinit_pair\fR(3X).
+\fBcurs_color\fR(3X).
.SH AUTHOR
Thomas Dickey.