Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
new_pair(3X)							  new_pair(3X)

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

       #include	<ncurses/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	 fore-
       ground/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 inde-
	   pendently, 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

       o   Color  pairs	 are the curses	library's way of managing a color pal-
	   ette	on a terminal.	If the library does not	keep track of the com-
	   binations of	colors which are displayed, it will be inefficient.

       o   For	simple terminal	emulators with only a few dozen	color combina-
	   tions, it is	convenient to use the maximum number  of  combinations
	   as the limit	on color pairs:


       o   Terminals  which support default colors distinct from "ANSI colors"
	   add to the possible combinations, producing this total:

	       ( COLORS	+ 1 ) *	( COLORS + 1 )

       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	appli-

	   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	 back-
       ground  color,  and checks if that color	combination is already associ-
       ated with a color pair.

       o   If the combination already exists, alloc_pair returns the  existing

       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 allo-
	   cated 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 capa-
       bility.	 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.  Oth-
       erwise 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.



Want to link to this manual page? Use this URL:

home | help