ncurses 6.0 - patch 20170401
[ncurses.git] / doc / html / man / new_pair.3x.html
1 <!-- 
2   ****************************************************************************
3   * Copyright (c) 2017 Free Software Foundation, Inc.                        *
4   *                                                                          *
5   * Permission is hereby granted, free of charge, to any person obtaining a  *
6   * copy of this software and associated documentation files (the            *
7   * "Software"), to deal in the Software without restriction, including      *
8   * without limitation the rights to use, copy, modify, merge, publish,      *
9   * distribute, distribute with modifications, sublicense, and/or sell       *
10   * copies of the Software, and to permit persons to whom the Software is    *
11   * furnished to do so, subject to the following conditions:                 *
12   *                                                                          *
13   * The above copyright notice and this permission notice shall be included  *
14   * in all copies or substantial portions of the Software.                   *
15   *                                                                          *
16   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
17   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
18   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
19   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
20   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
21   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
22   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
23   *                                                                          *
24   * Except as contained in this notice, the name(s) of the above copyright   *
25   * holders shall not be used in advertising or otherwise to promote the     *
26   * sale, use or other dealings in this Software without prior written       *
27   * authorization.                                                           *
28   ****************************************************************************
29   * Author: Thomas E. Dickey
30   * @Id: new_pair.3x,v 1.9 2017/03/13 21:21:34 tom Exp @
31 -->
32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
33 <HTML>
34 <HEAD>
35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
36 <meta name="generator" content="Manpage converted by man2html - see http://invisible-island.net/scripts/readme.html#others_scripts">
37 <TITLE>new_pair 3x</TITLE>
38 <link rev=made href="mailto:bug-ncurses@gnu.org">
39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
40 </HEAD>
41 <BODY>
42 <H1 class="no-header">new_pair 3x</H1>
43 <PRE>
44 <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG>                                               <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG>
45
46
47
48
49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
50        <STRONG>alloc_pair</STRONG>,  <STRONG>find_pair</STRONG>,  <STRONG>free_pair</STRONG> - new curses color-pair
51        functions
52
53
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
56
57        <STRONG>int</STRONG> <STRONG>alloc_pair(int</STRONG> <STRONG>fg,</STRONG> <STRONG>int</STRONG> <STRONG>bg);</STRONG>
58        <STRONG>int</STRONG> <STRONG>find_pair(int</STRONG> <STRONG>fg,</STRONG> <STRONG>int</STRONG> <STRONG>bg);</STRONG>
59        <STRONG>int</STRONG> <STRONG>free_pair(int</STRONG> <STRONG>pair);</STRONG>
60
61
62 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
63        These functions are an extension to  the  curses  library.
64        They permit an application to dynamically allocate a color
65        pair using the foreground/background  colors  rather  than
66        assign  a  fixed  color  pair number, and return an unused
67        pair to the pool.
68
69        The number of colors may be related to the number of  pos-
70        sible color pairs for a given terminal, or it may not:
71
72        <STRONG>o</STRONG>   While  almost  all  terminals  allow setting the color
73            <EM>attributes</EM> independently, it  is  unlikely  that  your
74            terminal  allows  you  to  modify  the attributes of a
75            given character cell without rewriting it.   That  is,
76            the  foreground and background colors are applied as a
77            pair.
78
79        <STRONG>o</STRONG>   Color pairs are the curses library's way of managing a
80            color  palette on a terminal.  If the library does not
81            keep track of the <EM>combinations</EM>  of  colors  which  are
82            displayed, it will be inefficient.
83
84        <STRONG>o</STRONG>   For  simple  terminal  emulators with only a few dozen
85            color combinations, it is convenient to use the  maxi-
86            mum  number  of  combinations  as  the  limit on color
87            pairs:
88
89              <STRONG>COLORS</STRONG> <EM>*</EM> <STRONG>COLORS</STRONG>
90
91        <STRONG>o</STRONG>   Terminals which support <EM>default</EM> <EM>colors</EM>  distinct  from
92            "ANSI  colors"  add to the possible combinations, pro-
93            ducing this total:
94
95              <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>
96
97        <STRONG>o</STRONG>   An application might use up to a few dozen color pairs
98            to implement a predefined color scheme.
99
100            Beyond  that  lies  in the realm of programs using the
101            foreground and background colors for "ASCII  art"  (or
102            some other non-textual application).
103
104            Also  beyond  those few dozen pairs, the required size
105            for  a  table  to  represent  the  combinations  grows
106            rapidly with an increasing number of colors.
107
108            These  functions  allow  a developer to let the screen
109            library manage color pairs.
110
111
112 </PRE><H3><a name="h3-alloc_pair">alloc_pair</a></H3><PRE>
113        The <STRONG>alloc_pair</STRONG> function accepts parameters for  foreground
114        and background color, and checks if that color combination
115        is already associated with a color pair.
116
117        <STRONG>o</STRONG>   If the combination already exists, <STRONG>alloc_pair</STRONG>  returns
118            the existing pair.
119
120        <STRONG>o</STRONG>   If  the  combination  does not exist, <STRONG>alloc_pair</STRONG> allo-
121            cates a new color pair and returns that.
122
123        <STRONG>o</STRONG>   If the table fills up, <STRONG>alloc_pair</STRONG> discards the  least-
124            recently allocated entry using <STRONG>free_pair</STRONG> and allocates
125            a new color pair.
126
127        All of the color pairs are allocated from a table of  pos-
128        sible color pairs.  The size of the table is determined by
129        the terminfo <EM>pairs</EM> capability.  The table is  shared  with
130        <STRONG>init_pair</STRONG>; in fact <STRONG>alloc_pair</STRONG> calls <STRONG>init_pair</STRONG> after updat-
131        ing the ncurses library's fast index to the colors  versus
132        color pairs.
133
134
135 </PRE><H3><a name="h3-find_pair">find_pair</a></H3><PRE>
136        The  <STRONG>find_pair</STRONG>  function accepts parameters for foreground
137        and background color, and checks if that color combination
138        is  already  associated  with  a color pair, returning the
139        pair number  if  it  has  been  allocated.   Otherwise  it
140        returns -1.
141
142
143 </PRE><H3><a name="h3-free_pair">free_pair</a></H3><PRE>
144        Marks  the  given  color  pair as unused, i.e., like color
145        pair 0.
146
147
148 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
149        The <STRONG>alloc_pair</STRONG> function returns a color pair number in the
150        range  1  through  <STRONG>COLOR_PAIRS</STRONG>-1,  unless it encounters an
151        error updating its fast index to the  color  pair  values,
152        preventing it from allocating a color pair.  In that case,
153        it returns -1.
154
155        The <STRONG>find_pair</STRONG> function returns a color pair number if  the
156        given  color  combination has been associated with a color
157        pair, or -1 if not.
158
159        Likewise, <STRONG>free_pair</STRONG> returns <STRONG>OK</STRONG>  unless  it  encounters  an
160        error  updating the fast index or if no such color pair is
161        in use.
162
163
164 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
165        These routines are specific to  ncurses.   They  were  not
166        supported  on  Version 7, BSD or System V implementations.
167        It is recommended that any code depending on them be  con-
168        ditioned using NCURSES_VERSION.
169
170
171 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
172        <STRONG><A HREF="init_pair.3x.html">init_pair(3x)</A></STRONG>.
173
174
175 </PRE><H2><a name="h2-AUTHOR">AUTHOR</a></H2><PRE>
176        Thomas Dickey.
177
178
179
180                                                            <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG>
181 </PRE>
182 <div class="nav">
183 <ul>
184 <li><a href="#h2-NAME">NAME</a></li>
185 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
186 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
187 <ul>
188 <li><a href="#h3-alloc_pair">alloc_pair</a></li>
189 <li><a href="#h3-find_pair">find_pair</a></li>
190 <li><a href="#h3-free_pair">free_pair</a></li>
191 </ul>
192 </li>
193 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
194 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
195 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
196 <li><a href="#h2-AUTHOR">AUTHOR</a></li>
197 </ul>
198 </div>
199 </BODY>
200 </HTML>