man/curs_bkgd.3x

   1 .\"***************************************************************************
   2 .\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
   3 .\" Copyright 1998-2015,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 .\"
  30 .\" $Id: curs_bkgd.3x,v 1.61 2024/04/20 18:54:36 tom Exp $
  31 .TH curs_bkgd 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
  32 .ie \n(.g \{\
  33 .ds `` \(lq
  34 .ds '' \(rq
  35 .\}
  36 .el \{\
  37 .ie t .ds `` ``
  38 .el   .ds `` ""
  39 .ie t .ds '' ''
  40 .el   .ds '' ""
  41 .\}
  42 .
  43 .de bP
  44 .ie n  .IP \(bu 4
  45 .el    .IP \(bu 2
  46 ..
  47 .SH NAME
  48 \fB\%bkgdset\fP,
  49 \fB\%wbkgdset\fP,
  50 \fB\%bkgd\fP,
  51 \fB\%wbkgd\fP,
  52 \fB\%getbkgd\fP \-
  53 manipulate background of a \fIcurses\fR window of characters
  54 .SH SYNOPSIS
  55 .nf
  56 \fB#include <curses.h>
  57 .PP
  58 \fBint bkgd(chtype \fIch\fP);
  59 \fBint wbkgd(WINDOW *\fIwin\fP, chtype \fIch\fP);
  60 .PP
  61 \fBvoid bkgdset(chtype \fIch\fP);
  62 \fBvoid wbkgdset(WINDOW *\fIwin\fP, chtype \fIch\fP);
  63 .PP
  64 \fBchtype getbkgd(WINDOW *\fIwin\fP);
  65 .fi
  66 .SH DESCRIPTION
  67 The
  68 .I background
  69 of a
  70 .I curses
  71 window
  72 (in the library's non-\*(``wide\*('' configuration)
  73 is a
  74 .I \%chtype
  75 combining a set of attributes
  76 (see \fB\%curs_attr\fP(3X))
  77 with a character called the
  78 .I "blank character."
  79 .PP
  80 The blank character is a spacing character that populates a window's
  81 character cells when their contents are erased without replacement.
  82 The background's attributes are combined with all non-blank characters
  83 written to the window,
  84 as with the \fB\%waddch\fP(3X) and \fB\%winsch\fP(3X) families of
  85 functions.
  86 .PP
  87 The blank character and attributes of the background combine with
  88 characters written to the window as described below.
  89 The background becomes a property of the character and moves with it
  90 through any scrolling and insert/delete line/character operations.
  91 .PP
  92 To the extent possible on a given terminal,
  93 the attribute part of the background is displayed as the graphic
  94 rendition of the character put on the screen.
  95 .SS "bkgd, wbkgd"
  96 \fB\%bkgd\fP and \fB\%wbkgd\fP set the background property of
  97 \fB\%stdscr\fP or the specified window and then apply this setting to
  98 every character cell in that window.
  99 .bP
 100 The rendition of every character in the window changes to the new
 101 background rendition.
 102 .bP
 103 Wherever the former background character appears,
 104 it changes to the new background character.
 105 .PP
 106 .I \%ncurses
 107 updates the rendition of each character cell by comparing the character,
 108 non-color attributes,
 109 and colors.
 110 The library applies to following procedure to each cell in the window,
 111 whether or not it is blank.
 112 .bP
 113 .I \%ncurses
 114 first compares the cell's character to the previously specified blank
 115 character;
 116 if they match,
 117 .I \%ncurses
 118 writes the new blank character to the cell.
 119 .bP
 120 .I \%ncurses
 121 then checks if the cell uses color,
 122 that is,
 123 its color pair value is nonzero.
 124 If not,
 125 it simply replaces the attributes and color pair in the cell with those
 126 from the new background character.
 127 .bP
 128 If the cell uses color,
 129 and its background color matches that of the current window background,
 130 .I \%ncurses
 131 removes attributes that may have come from the current background and
 132 adds those from the new background.
 133 It finishes by setting the cell's background to use the new window
 134 background color.
 135 .bP
 136 If the cell uses color,
 137 and its background color does not match that of the current window
 138 background,
 139 .I \%ncurses
 140 updates only the non-color attributes,
 141 first removing those that may have come from the current background,
 142 and then adding attributes from the new background.
 143 .PP
 144 .I \%ncurses
 145 treats a background character value of zero (0) as a blank character.
 146 .PP
 147 If the terminal does not support color,
 148 or if color has not been initialized with \fB\%start_color\fP(3X),
 149 .I \%ncurses
 150 ignores the new background character's color attribute.
 151 .SS "bkgdset, wbkgdset"
 152 \fB\%bkgdset\fP and \fB\%wbkgdset\fP manipulate the background of
 153 the applicable window,
 154 without updating the character cells as \fB\%bkgd\fP and
 155 \fB\%wbkgd\fP do;
 156 only future writes reflect the updated background.
 157 .SS getbkgd
 158 \fB\%getbkgd\fP obtains the given window's background character and
 159 attribute combination.
 160 .SH RETURN VALUE
 161 Functions returning an \fIint\fP return \fBOK\fP on success.
 162 \fB\%bkgd\fP returns \fBERR\fP if the library has not been initialized.
 163 \fB\%wbkgd\fP and \fB\%getbkgd\fP return \fBERR\fP if a \fI\%WINDOW\fP
 164 pointer argument is null.
 165 .PP
 166 \fB\%bkgdset\fP and \fBwbkgdset\fP do not return a value.
 167 .PP
 168 \fB\%getbkgd\fP returns a window's background character and attribute
 169 combination.
 170 .SH NOTES
 171 Unusually,
 172 there is no \fB\%wgetbkgd\fP function;
 173 \fB\%getbkgd\fP behaves as one would expect \fB\%wgetbkgd\fP to,
 174 accepting a \fI\%WINDOW\fP pointer argument.
 175 .PP
 176 \fB\%bkgd\fP and
 177 \fB\%bkgdset\fP
 178 may be implemented as macros.
 179 .PP
 180 X/Open Curses mentions that the character part of the background must
 181 be a single-byte value.
 182 \fI\%ncurses\fP,
 183 like SVr4 \fIcurses\fP,
 184 checks to ensure that,
 185 and will reuse the old background character if the check fails.
 186 .SH PORTABILITY
 187 X/Open Curses,
 188 Issue 4 describes these functions.
 189 It specifies that
 190 \fB\%bkgd\fP,
 191 \fB\%wbkgd\fP,
 192 and
 193 \fB\%getbkgd\fP
 194 return \fBERR\fP on failure
 195 (in the case of the last,
 196 this value is cast to
 197 .IR \%chtype ),
 198 but describes no failure conditions.
 199 .PP
 200 The SVr4.0 manual says that \fB\%bkgd\fP and \fB\%wbkgd\fP may return
 201 \fBOK\fP
 202 \*(``or a non-negative integer if \fB\%immedok\fP is set\*('',
 203 which refers to the return value from \fB\%wrefresh\fP(3X),
 204 used to implement the immediate repainting.
 205 SVr4 \fIcurses\fP's \fB\%wrefresh\fP returns the number of characters
 206 written to the screen during the refresh.
 207 \fI\%ncurses\fP does not do that.
 208 .PP
 209 Neither X/Open Curses nor the SVr4 manual pages detail how the rendition
 210 of characters on the screen updates when \fB\%bkgd\fP or \fB\%wbkgd\fP
 211 changes the background character.
 212 .IR \%ncurses ,
 213 like SVr4
 214 .IR curses ,
 215 does not
 216 (in its non-\*(``wide\*('' configuration)
 217 store the background and window attribute contributions to each
 218 character cell separately.
 219 .SH SEE ALSO
 220 \fB\%curs_bkgrnd\fP(3X) describes the corresponding functions in the
 221 \*(``wide\*('' configuration of
 222 .IR \%ncurses .
 223 .PP
 224 \fB\%curses\fP(3X),
 225 \fB\%curs_addch\fP(3X),
 226 \fB\%curs_attr\fP(3X)