]> ncurses.scripts.mit.edu Git - ncurses.git/blob - doc/html/man/curs_bkgd.3x.html
ncurses 6.4 - patch 20230128
[ncurses.git] / 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>