doc/html/man/curs_bkgd.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2021,2022 Thomas E. Dickey                                *
   4   * Copyright 1998-2015,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   * @Id: curs_bkgd.3x,v 1.35 2022/06/25 21:55:45 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 https://invisible-island.net/scripts/readme.html#others_scripts">
  37 <TITLE>curs_bkgd 3x</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">curs_bkgd 3x</H1>
  43 <PRE>
  44 <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>                                                    <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>
  45
  46
  47
  48
  49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  50        <STRONG>bkgdset</STRONG>,  <STRONG>wbkgdset</STRONG>,  <STRONG>bkgd</STRONG>,  <STRONG>wbkgd</STRONG>,  <STRONG>getbkgd</STRONG>  - <STRONG>curses</STRONG> window background
  51        manipulation routines
  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>void</STRONG> <STRONG>bkgdset(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
  58        <STRONG>void</STRONG> <STRONG>wbkgdset(WINDOW</STRONG> <STRONG>*</STRONG><EM>win,</EM> <EM>chtype</EM> <EM>ch</EM><STRONG>);</STRONG>
  59
  60        <STRONG>int</STRONG> <STRONG>bkgd(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
  61        <STRONG>int</STRONG> <STRONG>wbkgd(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
  62
  63        <STRONG>chtype</STRONG> <STRONG>getbkgd(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG>
  64
  65
  66 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  67
  68 </PRE><H3><a name="h3-bkgdset">bkgdset</a></H3><PRE>
  69        The <STRONG>bkgdset</STRONG> and <STRONG>wbkgdset</STRONG> routines set the <EM>background</EM> for a  window.   A
  70        window's  background  is  a  <STRONG>chtype</STRONG>  consisting  of  any combination of
  71        attributes (i.e., rendition) and a character:
  72
  73        <STRONG>o</STRONG>   The attribute part of the background is combined (OR'ed)  with  all
  74            non-blank characters that are written into the window with <STRONG>waddch</STRONG>.
  75
  76        <STRONG>o</STRONG>   Both  the  character  and  attribute  parts  of  the background are
  77            combined with blank characters that are written into the window.
  78
  79        The background becomes a property of each character and moves with  the
  80        character   through  any  scrolling  and  insert/delete  line/character
  81        operations.
  82
  83        To the extent possible on a particular terminal, the attribute part  of
  84        the  background  is displayed as the graphic rendition of the character
  85        put on the screen.
  86
  87
  88 </PRE><H3><a name="h3-bkgd">bkgd</a></H3><PRE>
  89        The <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> functions set the background property of the current
  90        or  specified  window  and  then  apply this setting to every character
  91        position in that window.  According to  X/Open  Curses,  it  should  do
  92        this:
  93
  94        <STRONG>o</STRONG>   The  rendition  of  every character on the screen is changed to the
  95            new background rendition.
  96
  97        <STRONG>o</STRONG>   Wherever the former background character appears, it is changed  to
  98            the new background character.
  99
 100        Neither  X/Open Curses nor the SVr4 manual pages give details about the
 101        way the rendition of characters on the screen is updated when  <STRONG>bkgd</STRONG>  or
 102        <STRONG>wbkgd</STRONG> is used to change the background character.
 103
 104        This  implementation,  like  SVr4 curses, does not store the background
 105        and window attribute contributions to each cell separately.  It updates
 106        the  rendition  by  comparing  the  character, non-color attributes and
 107        colors contained in the background.   For  each  cell  in  the  window,
 108        whether or not it is blank:
 109
 110        <STRONG>o</STRONG>   The  library  first  compares  the <EM>character</EM>, and if it matches the
 111            current character part of the background, it replaces that with the
 112            new background character.
 113
 114            When <STRONG>bkgdset</STRONG> is used to set the background character, that does not
 115            update each cell in the window.  A subsequent  call  to  <STRONG>bkgd</STRONG>  will
 116            only  modify  the  <EM>character</EM>  in  cells  which  match  the  current
 117            background character.
 118
 119        <STRONG>o</STRONG>   The library then checks if the cell uses  color,  i.e.,  its  color
 120            pair  value  is nonzero.  If not, it simply replaces the attributes
 121            and color pair in the cell  with  those  from  the  new  background
 122            character.
 123
 124        <STRONG>o</STRONG>   If  the  cell uses color, and that matches the color in the current
 125            background, the library removes attributes which may have come from
 126            the current background and adds attributes from the new background.
 127            It finishes by setting the cell to  use  the  color  from  the  new
 128            background.
 129
 130        <STRONG>o</STRONG>   If  the  cell  uses color, and that does not match the color in the
 131            current  background,  the  library  updates  only   the   non-color
 132            attributes,  first  removing  those  which  may  have come from the
 133            current  background,  and  then  adding  attributes  from  the  new
 134            background.
 135
 136        If the background's character value is zero (0), a space is assumed.
 137
 138        If  the  terminal  does  not  support  color,  or if color has not been
 139        started  with  <STRONG>start_color</STRONG>,  the  new  background   character's   color
 140        attribute will be ignored.
 141
 142
 143 </PRE><H3><a name="h3-getbkgd">getbkgd</a></H3><PRE>
 144        The  <STRONG>getbkgd</STRONG>  function  returns  the  given window's current background
 145        character/attribute pair.
 146
 147
 148 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 149        These functions are described in the XSI Curses standard, Issue 4.   It
 150        specifies  that  <STRONG>bkgd</STRONG>  and  <STRONG>wbkgd</STRONG>  return  <STRONG>ERR</STRONG> on failure, but gives no
 151        failure conditions.
 152
 153        The routines <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> return the integer <STRONG>OK</STRONG>, unless  the  library
 154        has not been initialized.
 155
 156        In  contrast, the SVr4.0 manual says <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> may return <STRONG>OK</STRONG> "or a
 157        non-negative integer if <STRONG>immedok</STRONG> is set", which  refers  to  the  return
 158        value  from <STRONG>wrefresh</STRONG> (used to implement the immediate repainting).  The
 159        SVr4 curses <STRONG>wrefresh</STRONG> returns the number of characters  written  to  the
 160        screen during the refresh.  This implementation does not do that.
 161
 162
 163 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 164        Note that <STRONG>bkgdset</STRONG> and <STRONG>bkgd</STRONG> may be macros.
 165
 166        X/Open  Curses  mentions that the character part of the background must
 167        be a single-byte value.  This  implementation,  like  SVr4,  checks  to
 168        ensure  that,  and will reuse the old background character if the check
 169        fails.
 170
 171
 172 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 173        These functions are described in  the  XSI  Curses  standard,  Issue  4
 174        (X/Open Curses).
 175
 176
 177 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 178        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>
 179
 180
 181
 182                                                                  <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>
 183 </PRE>
 184 <div class="nav">
 185 <ul>
 186 <li><a href="#h2-NAME">NAME</a></li>
 187 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 188 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 189 <ul>
 190 <li><a href="#h3-bkgdset">bkgdset</a></li>
 191 <li><a href="#h3-bkgd">bkgd</a></li>
 192 <li><a href="#h3-getbkgd">getbkgd</a></li>
 193 </ul>
 194 </li>
 195 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 196 <li><a href="#h2-NOTES">NOTES</a></li>
 197 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 198 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 199 </ul>
 200 </div>
 201 </BODY>
 202 </HTML>