1new_pair(3X)                                                      new_pair(3X)
2
3
4

NAME

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

SYNOPSIS

9       #include <curses.h>
10
11       int alloc_pair(int fg, int bg);
12       int find_pair(int fg, int bg);
13       int free_pair(int pair);
14

DESCRIPTION

16       These functions are an extension to the curses library.  They permit an
17       application to dynamically  allocate  a  color  pair  using  the  fore‐
18       ground/background  colors rather than assign a fixed color pair number,
19       and return an unused pair to the pool.
20
21       The number of colors may be related to the  number  of  possible  color
22       pairs for a given terminal, or it may not:
23
24       ·   While almost all terminals allow setting the color attributes inde‐
25           pendently, it is unlikely that your terminal allows you  to  modify
26           the  attributes  of  a  given  character cell without rewriting it.
27           That is, the foreground and background  colors  are  applied  as  a
28           pair.
29
30       ·   Color  pairs  are the curses library's way of managing a color pal‐
31           ette on a terminal.  If the library does not keep track of the com‐
32           binations of colors which are displayed, it will be inefficient.
33
34       ·   For  simple terminal emulators with only a few dozen color combina‐
35           tions, it is convenient to use the maximum number  of  combinations
36           as the limit on color pairs:
37
38               COLORS * COLORS
39
40       ·   Terminals  which support default colors distinct from “ANSI colors”
41           add to the possible combinations, producing this total:
42
43               ( COLORS + 1 ) * ( COLORS + 1 )
44
45       ·   An application might use up to a few dozen color pairs to implement
46           a predefined color scheme.
47
48           Beyond  that lies in the realm of programs using the foreground and
49           background colors for “ASCII art” (or some other non-textual appli‐
50           cation).
51
52           Also beyond those few dozen pairs, the required size for a table to
53           represent the combinations grows rapidly with an increasing  number
54           of colors.
55
56           These  functions allow a developer to let the screen library manage
57           color pairs.
58
59   alloc_pair
60       The alloc_pair function accepts parameters  for  foreground  and  back‐
61       ground  color,  and checks if that color combination is already associ‐
62       ated with a color pair.
63
64       ·   If the combination already exists, alloc_pair returns the  existing
65           pair.
66
67       ·   If the combination does not exist, alloc_pair allocates a new color
68           pair and returns that.
69
70       ·   If the table fills up, alloc_pair discards the least-recently allo‐
71           cated entry using free_pair and allocates a new color pair.
72
73       All  of  the  color  pairs are allocated from a table of possible color
74       pairs.  The size of the table is determined by the terminfo pairs capa‐
75       bility.   The  table is shared with init_pair; in fact alloc_pair calls
76       init_pair after updating the ncurses library's fast index to the colors
77       versus color pairs.
78
79   find_pair
80       The find_pair function accepts parameters for foreground and background
81       color, and checks if that color combination is already associated  with
82       a color pair, returning the pair number if it has been allocated.  Oth‐
83       erwise it returns -1.
84
85   free_pair
86       Marks the given color pair as unused, i.e., like color pair 0.
87

RETURN VALUE

89       The alloc_pair function returns a color pair  number  in  the  range  1
90       through  COLOR_PAIRS-1, unless it encounters an error updating its fast
91       index to the color pair values, preventing it from allocating  a  color
92       pair.  In that case, it returns -1.
93
94       The  find_pair  function returns a color pair number if the given color
95       combination has been associated with a color pair, or -1 if not.
96
97       Likewise, free_pair returns OK unless it encounters an  error  updating
98       the fast index or if no such color pair is in use.
99

PORTABILITY

101       These  routines  are  specific  to ncurses.  They were not supported on
102       Version 7, BSD or System V implementations.  It is recommended that any
103       code depending on them be conditioned using NCURSES_VERSION.
104

SEE ALSO

106       curs_color(3X).
107

AUTHOR

109       Thomas Dickey.
110
111
112
113                                                                  new_pair(3X)
Impressum