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>