new_pair(3x) new_pair(3x)
alloc_pair, find_pair, free_pair - new curses color-pair
functions
#include <curses.h>
int alloc_pair(int fg, int bg);
int find_pair(int fg, int bg);
int free_pair(int pair);
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.
The number of colors may be related to the number of pos-
sible color pairs for a given terminal, or it may not:
o While almost all terminals allow setting the color
attributes 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.
o 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 combinations of colors which are
displayed, it will be inefficient.
o For simple terminal emulators with only a few dozen
color combinations, it is convenient to use the maxi-
mum number of combinations as the limit on color
pairs:
COLORS * COLORS
o Terminals which support default colors distinct from
"ANSI colors" add to the possible combinations, pro-
ducing this total:
( COLORS + 1 ) * ( COLORS + 1 )
o An application might use up to a few dozen color pairs
to implement a predefined color scheme.
Beyond that lies in the realm of programs using the
foreground and background colors for "ASCII art" (or
some other non-textual application).
Also beyond those few dozen pairs, the required size
for a table to represent the combinations grows
rapidly with an increasing number of colors.
These functions allow a developer to let the screen
library manage color pairs.
The alloc_pair function accepts parameters for foreground
and background color, and checks if that color combination
is already associated with a color pair.
o If the combination already exists, alloc_pair returns
the existing pair.
o If the combination does not exist, alloc_pair allo-
cates a new color pair and returns that.
o If the table fills up, alloc_pair discards the least-
recently allocated entry using free_pair and allocates
a new color pair.
All of the color pairs are allocated from a table of pos-
sible color pairs. The size of the table is determined by
the terminfo pairs capability. The table is shared with
init_pair; in fact alloc_pair calls init_pair after updat-
ing the ncurses library's fast index to the colors versus
color pairs.
The find_pair 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.
Marks the given color pair as unused, i.e., like color
pair 0.
The alloc_pair function returns a color pair number in the
range 1 through COLOR_PAIRS-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.
The find_pair function returns a color pair number if the
given color combination has been associated with a color
pair, or -1 if not.
Likewise, free_pair returns OK unless it encounters an
error updating the fast index or if no such color pair is
in use.
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 con-
ditioned using NCURSES_VERSION.
init_pair(3x).
Thomas Dickey.
new_pair(3x)