| <!-- |
| **************************************************************************** |
| * 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 @ |
| --> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> |
| <HTML> |
| <HEAD> |
| <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
| <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> |
| <TITLE>new_pair 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> |
| <link rel="author" href="mailto:bug-ncurses@gnu.org"> |
| |
| </HEAD> |
| <BODY> |
| <H1 class="no-header">new_pair 3x 2024-03-16 ncurses 6.5 Library calls</H1> |
| <PRE> |
| <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG> Library calls <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG> |
| |
| |
| |
| |
| </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> |
| <STRONG>alloc_pair</STRONG>, <STRONG>find_pair</STRONG>, <STRONG>free_pair</STRONG> - dynamically allocate <EM>curses</EM> color |
| pairs |
| |
| |
| </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> |
| <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> |
| |
| <STRONG>int</STRONG> <STRONG>alloc_pair(int</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bg</EM><STRONG>);</STRONG> |
| <STRONG>int</STRONG> <STRONG>find_pair(int</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bg</EM><STRONG>);</STRONG> |
| <STRONG>int</STRONG> <STRONG>free_pair(int</STRONG> <EM>pair</EM><STRONG>);</STRONG> |
| |
| |
| </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> |
| These functions are an extension to the <EM>curses</EM> 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: |
| |
| <STRONG>o</STRONG> While almost all terminals allow setting the color <EM>attributes</EM> |
| 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. |
| |
| <STRONG>o</STRONG> Color pairs are the <EM>curses</EM> library's way of managing a color |
| palette on a terminal. If the library does not keep track of the |
| <EM>combinations</EM> of colors which are displayed, it will be inefficient. |
| |
| <STRONG>o</STRONG> 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: |
| |
| <STRONG>COLORS</STRONG> <EM>*</EM> <STRONG>COLORS</STRONG> |
| |
| <STRONG>o</STRONG> Terminals which support <EM>default</EM> <EM>colors</EM> distinct from "ANSI colors" |
| add to the possible combinations, producing this total: |
| |
| <EM>(</EM> <STRONG>COLORS</STRONG> <EM>+</EM> <EM>1</EM> <EM>)</EM> <EM>*</EM> <EM>(</EM> <STRONG>COLORS</STRONG> <EM>+</EM> <EM>1</EM> <EM>)</EM> |
| |
| <STRONG>o</STRONG> 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. |
| |
| |
| </PRE><H3><a name="h3-alloc_pair">alloc_pair</a></H3><PRE> |
| The <STRONG>alloc_pair</STRONG> function accepts parameters for foreground and |
| background color, and checks if that color combination is already |
| associated with a color pair. |
| |
| <STRONG>o</STRONG> If the combination already exists, <STRONG>alloc_pair</STRONG> returns the existing |
| pair. |
| |
| <STRONG>o</STRONG> If the combination does not exist, <STRONG>alloc_pair</STRONG> allocates a new color |
| pair and returns that. |
| |
| <STRONG>o</STRONG> If the table fills up, <STRONG>alloc_pair</STRONG> discards the least-recently |
| allocated entry using <STRONG>free_pair</STRONG> 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 <STRONG>pairs</STRONG> |
| capability. The table is shared with <STRONG>init_pair</STRONG>; in fact <STRONG>alloc_pair</STRONG> |
| calls <STRONG>init_pair</STRONG> after updating the <EM>ncurses</EM> library's fast index to the |
| colors versus color pairs. |
| |
| |
| </PRE><H3><a name="h3-find_pair">find_pair</a></H3><PRE> |
| The <STRONG>find_pair</STRONG> 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. |
| |
| |
| </PRE><H3><a name="h3-free_pair">free_pair</a></H3><PRE> |
| Marks the given color pair as unused, i.e., like color pair 0. |
| |
| |
| </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> |
| The <STRONG>alloc_pair</STRONG> function returns a color pair number in the range 1 |
| through <STRONG>COLOR_PAIRS</STRONG>-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 <STRONG>find_pair</STRONG> function returns a color pair number if the given color |
| combination has been associated with a color pair, or -1 if not. |
| |
| Likewise, <STRONG>free_pair</STRONG> returns <STRONG>OK</STRONG> unless it encounters an error updating |
| the fast index or if no such color pair is in use. |
| |
| |
| </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> |
| These routines are specific to <EM>ncurses</EM>. They were not supported on |
| Version 7, BSD or System V implementations. It is recommended that any |
| code depending on them be conditioned using <STRONG>NCURSES_VERSION</STRONG>. |
| |
| |
| </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> |
| Thomas Dickey |
| |
| |
| </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> |
| <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> |
| |
| |
| |
| ncurses 6.5 2024-03-16 <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG> |
| </PRE> |
| <div class="nav"> |
| <ul> |
| <li><a href="#h2-NAME">NAME</a></li> |
| <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> |
| <li><a href="#h2-DESCRIPTION">DESCRIPTION</a> |
| <ul> |
| <li><a href="#h3-alloc_pair">alloc_pair</a></li> |
| <li><a href="#h3-find_pair">find_pair</a></li> |
| <li><a href="#h3-free_pair">free_pair</a></li> |
| </ul> |
| </li> |
| <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> |
| <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> |
| <li><a href="#h2-AUTHORS">AUTHORS</a></li> |
| <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> |
| </ul> |
| </div> |
| </BODY> |
| </HTML> |