https://invisible-island.net/ncurses/man/


new_pair 3x 2023-12-16 ncurses 6.4 Library calls

new_pair(3x)                     Library calls                    new_pair(3x)




NAME

       alloc_pair,  find_pair,  free_pair  - dynamically allocate curses color
       pairs


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


alloc_pair

       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 allocates 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  possible  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 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.
       Otherwise 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.


AUTHORS

       Thomas Dickey


SEE ALSO

       curs_color(3x)



ncurses 6.4                       2023-12-16                      new_pair(3x)