X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fnew_pair.3x.html;h=12214bec7c0a5aa7c600823cf07b7ead4b63b32d;hp=fa487adc7fcb1bb68814ce94ea68635a890b0d0b;hb=81304798ee736c467839c779c9ca5dca48db7bea;hpb=5eb177874dea59107a1a2ea44f5d8f5bb99550b2 diff --git a/doc/html/man/new_pair.3x.html b/doc/html/man/new_pair.3x.html index fa487adc..12214bec 100644 --- a/doc/html/man/new_pair.3x.html +++ b/doc/html/man/new_pair.3x.html @@ -1,6 +1,7 @@ -
- +-new_pair(3x) new_pair(3x) +new_pair(3x) new_pair(3x)
- alloc_pair, find_pair, free_pair - new curses color-pair - functions + alloc_pair, find_pair, free_pair - new curses color-pair functions
#include <curses.h> - int alloc_pair(int fg, int bg); - int find_pair(int fg, int bg); - int free_pair(int pair); + 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 pos- - sible 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 + 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 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 maxi- - mum number of combinations as the limit on color - pairs: + 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 + COLORS * COLORS - o Terminals which support default colors distinct from - "ANSI colors" add to the possible combinations, pro- - ducing this total: + o Terminals which support default colors distinct from "ANSI colors" + add to the possible combinations, producing this total: - ( COLORS + 1 ) * ( COLORS + 1 ) + ( COLORS + 1 ) * ( COLORS + 1 ) - o An application might use up to a few dozen color pairs - to implement a predefined color scheme. + 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). + 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. + 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. + 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. + 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 already exists, alloc_pair returns the existing + pair. - o If the combination does not exist, alloc_pair allo- - cates a new color pair and returns that. + 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. + 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 pos- - sible 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 updat- - ing the ncurses library's fast index to the colors versus - color pairs. + 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. + 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. + 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 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. + 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. + 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 con- - ditioned using NCURSES_VERSION. + 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.
- init_pair(3x). + curs_color(3x).
@@ -177,7 +164,7 @@ - new_pair(3x) + new_pair(3x)