***************************************************************************
Copyright 2018-2023,2024 Thomas E. Dickey *
Copyright 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.46 2024/03/16 15:35:01 tom Exp $
.\} .\} . .. \%alloc_pair, \%find_pair, \%free_pair - dynamically allocate curses color pairs

#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 possible color pairs for a given terminal, or it may not: .bP 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. .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 combinations of colors which are displayed, it will be inefficient.

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:

Terminals which support default colors distinct from \*(``ANSI colors\*('' add to the possible combinations, producing this total:

.bP 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. .bP If the combination already exists, alloc_pair returns the existing pair. .bP If the combination does not exist, alloc_pair allocates a new color pair and returns that. .bP 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.

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 conditioned using \%NCURSES_VERSION. Thomas Dickey \%curs_color(3X)