X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fnew_pair.3x.html;fp=doc%2Fhtml%2Fman%2Fnew_pair.3x.html;h=b2c0d2095152a1055309e23fa6b804bca3612d2f;hp=d55b3c7e75868ba865d8152d2d6a84c9c15ae8fd;hb=31c4bcf3307145fc5368b4aaf15e41bdd66a984b;hpb=2035f48ed0fc56ec4e5caf9b7c10e00ba43e160f diff --git a/doc/html/man/new_pair.3x.html b/doc/html/man/new_pair.3x.html index d55b3c7e..b2c0d209 100644 --- a/doc/html/man/new_pair.3x.html +++ b/doc/html/man/new_pair.3x.html @@ -28,19 +28,19 @@ * authorization. * **************************************************************************** * Author: Thomas E. Dickey - * @Id: new_pair.3x,v 1.26 2023/09/09 21:20:16 tom Exp @ + * @Id: new_pair.3x,v 1.30 2023/09/16 23:38:39 tom Exp @ -->
-new_pair(3x) Library calls new_pair(3x) @@ -48,7 +48,8 @@
- alloc_pair, find_pair, free_pair - new curses color-pair functions + alloc_pair, find_pair, free_pair - dynamically allocate curses color + pairs
@@ -61,30 +62,30 @@
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 + 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 + 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 + 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 + 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 + 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" + o Terminals which support default colors distinct from "ANSI colors" add to the possible combinations, producing this total: ( COLORS + 1 ) * ( COLORS + 1 ) @@ -92,43 +93,43 @@ 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 + 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 + represent the combinations grows rapidly with an increasing number of colors. - These functions allow a developer to let the screen library manage + 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 + 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 + 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 + 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 + 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. + 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. @@ -137,20 +138,20 @@
- 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 + 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 + 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 + 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 + 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. @@ -164,7 +165,7 @@ -ncurses 6.4 2023-09-09 new_pair(3x) +ncurses 6.4 2023-09-16 new_pair(3x)