doc/html/man/new_pair.3x.html

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