--- /dev/null
+.\"***************************************************************************
+.\" Copyright (c) 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 *
+.\" "Software"), to deal in the Software without restriction, including *
+.\" without limitation the rights to use, copy, modify, merge, publish, *
+.\" distribute, distribute with modifications, sublicense, and/or sell *
+.\" copies of the Software, and to permit persons to whom the Software is *
+.\" furnished to do so, subject to the following conditions: *
+.\" *
+.\" The above copyright notice and this permission notice shall be included *
+.\" in all copies or substantial portions of the Software. *
+.\" *
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
+.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
+.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
+.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
+.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
+.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
+.\" *
+.\" Except as contained in this notice, the name(s) of the above copyright *
+.\" holders shall not be used in advertising or otherwise to promote the *
+.\" sale, use or other dealings in this Software without prior written *
+.\" authorization. *
+.\"***************************************************************************
+.\"
+.\" Author: Thomas E. Dickey
+.\"
+.\" $Id: new_pair.3x,v 1.8 2017/03/09 09:59:11 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
+..
+.de NS
+.ie \n(.sp
+.el .sp .5
+.ie \n(.in +4
+.el .in +2
+.nf
+.ft C \" Courier
+..
+.de NE
+.fi
+.ft R
+.in -4
+..
+.SH NAME
+\fBalloc_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
+.br
+\fBint free_pair(int pair);\fP
+.SH DESCRIPTION
+These functions are an extension to the curses 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.
+.PP
+The number of colors may be related to the number of possible color
+pairs for a given terminal, or it may not:
+.bP
+While almost all terminals allow setting the color \fIattributes\fP
+independently,
+it is unlikely that your terminal allows you to modify the attributes
+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
+on a terminal.
+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
+with only a few dozen color combinations,
+it is convenient to use the maximum number of combinations
+as the limit on color pairs:
+.NS
+\fBCOLORS\fP\fI * \fP\fBCOLORS\fP
+.NE
+.bP
+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
+.NE
+.bP
+An application might use up to a few dozen color pairs to
+implement a predefined color scheme.
+.IP
+Beyond that lies in the realm of programs using the foreground
+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
+to represent the combinations grows rapidly with an increasing number of colors.
+.IP
+These functions allow a developer to let the screen library
+manage color pairs.
+.SS alloc_pair
+The \fBalloc_pair\fP function accepts parameters for
+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.
+.bP
+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.
+.PP
+All of the color pairs are allocated from a table of possible color pairs.
+The size of the table is determined by the terminfo \fIpairs\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.
+.SS find_pair
+The \fBfind_pair\fP function accepts parameters for
+foreground and background color, and
+checks if that color combination is already associated with a color pair,
+returning the pair number if it has been allocated.
+Otherwise it returns \-1.
+.SS free_pair
+Marks the given color pair as unused,
+i.e., like color pair 0.
+.SH RETURN VALUE
+.PP
+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.
+.PP
+The \fBfind_pair\fP function returns a color pair number if the
+given color combination has been associated with a color pair,
+or \-1 if not.
+.PP
+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
+any code depending on them be conditioned using NCURSES_VERSION.
+.SH SEE ALSO
+\fBinit_pair\fR(3X).
+.SH AUTHOR
+Thomas Dickey.
projects / ncurses.git / blobdiff