# new_pair 3x

    new_pair(3x)                                                      new_pair(3x)

## NAME

           alloc_pair, find_pair, free_pair - new curses color-pair functions

## SYNOPSIS

           #include <curses.h>

           int alloc_pair(int fg, int bg);
           int find_pair(int fg, int bg);
           int free_pair(int pair);

## DESCRIPTION

           These functions are an extension to the curses library.  They permit an
           application to dynamically  allocate  a  color  pair  using  the  fore-
           ground/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  possible  color
           pairs for a given terminal, or it may not:

           o   While almost all terminals allow setting the color attributes inde-
               pendently, 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 pal-
               ette on a terminal.  If the library does not keep track of the com-
               binations of colors which are displayed, it will be inefficient.

           o   For  simple terminal emulators with only a few dozen color combina-
               tions, it is convenient to use the maximum 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, producing 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 appli-
               cation).

               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.

### alloc_pair

           The alloc_pair function accepts parameters  for  foreground  and  back-
           ground  color,  and checks if that color combination is already associ-
           ated 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 allocates a new color
               pair and returns that.

           o   If the table fills up, alloc_pair discards the least-recently allo-
               cated entry using free_pair and allocates a new color pair.

           All  of  the  color  pairs are allocated from a table of possible color
           pairs.  The size of the table is determined by the terminfo pairs capa-
           bility.   The  table is shared with init_pair; in fact alloc_pair calls
           init_pair after updating the ncurses library's fast index to the colors
           versus color pairs.

### find_pair

           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.  Oth-
           erwise it returns -1.

### free_pair

           Marks the given color pair as unused, i.e., like color pair 0.

## RETURN VALUE

           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.

## 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.

## SEE ALSO

           init_pair(3x).

## AUTHOR

           Thomas Dickey.

                                                                      new_pair(3x)