- The bkgrndset and wbkgrndset routines manipulate the back-
- ground of the named window. The window background is a
- cchar_t consisting of any combination of attributes (i.e.,
- rendition) and a complex character. The attribute part of
- the background is combined (OR'ed) with all non-blank
- characters 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.
+
+ The background of a curses window (in the library's "wide"
+ configuration) is a cchar_t combining a set of attributes (see
+ curs_attr(3x)) with a complex character called the blankcharacter.
- 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 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 wadd_wch(3x) and wins_wch(3x)
+ families of functions.
- The bkgrnd and wbkgrnd functions set the background prop-
- erty of the current or specified window and then apply
- this setting to every character position in that window:
+ 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 rendition of every character on the screen is
- changed to the new background rendition.
+ 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.
- Wherever the former background character appears,
- it is changed to the new background character.
- The getbkgrnd function returns the given window's current
- background character/attribute pair via the wch pointer.
+
+ bkgrnd and wbkgrnd 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 bkgrnd, bkgrndset, and getbkgrnd 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.
-
-
RETURN VALUES
- The bkgrndset and wbkgrndset routines do not return a
- value.
+ 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.
- Upon successful completion, the other functions return OK.
- Otherwise, they return ERR. A null window pointer is
- treated as an error.
+ 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.
+ 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.
-
-
SEE ALSO
- curses(3x), curs_bkgd(3x)
+ 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.
+
+
+
+ bkgrndset and wbkgrndset manipulate the background of the applicable
+ window, without updating the character cells as bkgrnd and wbkgrnd do;
+ only future writes reflect the updated background.
+
+
+
+ The getbkgrnd and wgetbkgrnd functions obtain the background character
+ and attribute pair of stdscr or the specified window and store it via
+ the wch pointer.
+
+
+
+ bkgrndset and wbkgrndset do not return a value.
+
+ The other functions return ERR upon failure and OK upon success. In
+ ncurses, failure occurs if
+
+ o a WINDOW pointer win is null, or
+
+ o a cchar_t pointer wch is null.
+
+
+
+ bkgrnd, bkgrndset, and getbkgrnd may be implemented as macros.
+
+ Unlike their counterparts in the non-"wide" configuration of ncurses,
+ getbkgrnd and wgetbkgrnd supply the background character and attribute
+ in a modifiable cchar_t parameter, not as the return value.
+
+
+
+ X/Open Curses, Issue 4 describes these functions. It specifies no
+ error conditions for them.
+
+ X/Open Curses does not provide details of how the rendition is updated.
+ This implementation follows the approach used in SVr4 curses.
+
+
+