- The bkgdset and wbkgdset routines manipulate the back-
- ground of the named window. The window background is a
- chtype consisting of any combination of attributes (i.e.,
- rendition) and a character. The attribute part of the
- background is combined (OR'ed) with all non-blank charac-
- ters that are written into the window with waddch. Both
- the character and attribute parts of the background are
- combined with the blank characters. The background
- becomes a property of the character and moves with the
- character through any scrolling and insert/delete
- line/character operations.
+ chtypegetbkgd(WINDOW*win);
- To the extent possible on a particular terminal, the
- attribute part of the background is displayed as the
- graphic rendition of the character put on the screen.
- The bkgd and wbkgd functions set the background property
- of the current or specified window and then apply this
- setting to every character position in that window:
+
+ The background of a curses window (in the library's non-"wide"
+ configuration) is a chtype combining a set of attributes (see
+ curs_attr(3x)) with a character called the blankcharacter.
- The rendition of every character on the screen is
- changed to the new background rendition.
+ The blank character is a spacing character that populates a window's
+ character cells when their contents are erased without replacement.
+ The background's attributes are combined with all non-blank characters
+ written to the window, as with the waddch(3x) and winsch(3x) families
+ of functions.
- Wherever the former background character appears,
- it is changed to the new background character.
+ The blank character and attributes of the background combine with
+ characters written to the window as described below. The background
+ becomes a property of the character and moves with it through any
+ scrolling and insert/delete line/character operations.
- The getbkgd function returns the given window's current
- background character/attribute pair.
+ To the extent possible on a given terminal, the attribute part of the
+ background is displayed as the graphic rendition of the character put
+ on the screen.
-
-
RETURN VALUE
- The routines bkgd and wbkgd return the integer OK. The
- SVr4.0 manual says "or a non-negative integer if immedok
- is set", but this appears to be an error.
+
+ bkgd and wbkgd set the background property of stdscr or the specified
+ window and then apply this setting to every character cell in that
+ window.
+ o The rendition of every character in the window changes to the new
+ background rendition.
-
-
NOTES
- Note that bkgdset and bkgd may be macros.
+ o Wherever the former background character appears, it changes to the
+ new background character.
+ ncurses updates the rendition of each character cell by comparing the
+ character, non-color attributes, and colors. The library applies to
+ following procedure to each cell in the window, whether or not it is
+ blank.
-
-
PORTABILITY
- These functions are described in the XSI Curses standard,
- Issue 4. It specifies that bkgd and wbkgd return ERR on
- failure, but gives no failure conditions.
+ oncurses first compares the cell's character to the previously
+ specified blank character; if they match, ncurses writes the new
+ blank character to the cell.
+ oncurses then checks if the cell uses color, that is, its color pair
+ value is nonzero. If not, it simply replaces the attributes and
+ color pair in the cell with those from the new background
+ character.
-
-
SEE ALSO
- curses(3x), curs_addch(3x), curs_attr(3x), curs_out-
- opts(3x)
+ o If the cell uses color, and its background color matches that of
+ the current window background, ncurses removes attributes that may
+ have come from the current background and adds those from the new
+ background. It finishes by setting the cell's background to use
+ the new window background color.
+
+ o If the cell uses color, and its background color does not match
+ that of the current window background, ncurses updates only the
+ non-color attributes, first removing those that may have come from
+ the current background, and then adding attributes from the new
+ background.
+
+ ncurses treats a background character value of zero (0) as a blank
+ character.
+
+ If the terminal does not support color, or if color has not been
+ initialized with start_color(3x), ncurses ignores the new background
+ character's color attribute.
+
+
+
+ bkgdset and wbkgdset manipulate the background of the applicable
+ window, without updating the character cells as bkgd and wbkgd do; only
+ future writes reflect the updated background.
+
+
+
+ Functions returning an int return OK on success. bkgd returns ERR if
+ the library has not been initialized. wbkgd and getbkgd return ERR if
+ a WINDOW pointer argument is null.
+
+ bkgdset and wbkgdset do not return a value.
+
+ getbkgd returns a window's background character and attribute
+ combination.
+
+
+
+ Unusually, there is no wgetbkgd function; getbkgd behaves as one would
+ expect wgetbkgd to, accepting a WINDOW pointer argument.
+
+ bkgd and bkgdset may be implemented as macros.
+
+ X/Open Curses mentions that the character part of the background must
+ be a single-byte value. ncurses, like SVr4 curses, checks to ensure
+ that, and will reuse the old background character if the check fails.
+
+
+
+ X/Open Curses, Issue 4 describes these functions. It specifies that
+ bkgd, wbkgd, and getbkgd return ERR on failure (in the case of the
+ last, this value is cast to chtype), but describes no failure
+ conditions.
+
+ The SVr4.0 manual says that bkgd and wbkgd may return OK "or a non-
+ negative integer if immedok is set", which refers to the return value
+ from wrefresh(3x), used to implement the immediate repainting. SVr4
+ curses's wrefresh returns the number of characters written to the
+ screen during the refresh. ncurses does not do that.
+
+ Neither X/Open Curses nor the SVr4 manual pages detail how the
+ rendition of characters on the screen updates when bkgd or wbkgd
+ changes the background character. ncurses, like SVr4 curses, does not
+ (in its non-"wide" configuration) store the background and window
+ attribute contributions to each character cell separately.
+
+
+