NAME

       bkgrnd, wbkgrnd, bkgrndset, wbkgrndset, getbkgrnd, wgetbkgrnd - manipulate background of a
       curses window of wide characters

SYNOPSIS

       #include <curses.h>

       int bkgrnd(const cchar_t *wch);
       int wbkgrnd(WINDOW *win, const cchar_t *wch);

       void bkgrndset(const cchar_t *wch);
       void wbkgrndset(WINDOW *win, const cchar_t *wch);

       int getbkgrnd(cchar_t *wch);
       int wgetbkgrnd(WINDOW *win, cchar_t *wch);

DESCRIPTION

       The background of a curses window (in the library's “wide”  configuration)  is  a  cchar_t
       combining  a  set  of  attributes (see attr(3NCURSES)) with a complex character called the
       blank character.

       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(3NCURSES)  and
       wins_wch(3NCURSES) families of functions.

       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.

       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.

   bkgrnd, wbkgrnd
       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.

       •   The  rendition  of  every  character  in  the  window  changes  to  the new background
           rendition.

       •   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.

       •   ncurses  first  compares  the  cell's  character  to  the  previously  specified blank
           character; if they match, ncurses writes the new blank character to the cell.

       •   ncurses 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.

       •   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.

       •   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(3NCURSES), ncurses ignores the new background character's color attribute.

   bkgrndset, wbkgrndset
       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.

   getbkgrnd, wgetbkgrnd
       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.

RETURN VALUE

       bkgrndset and wbkgrndset do not return a value.

       The other functions return ERR upon failure and OK  upon  success.   In  ncurses,  failure
       occurs if

       •   a WINDOW pointer win is null, or

       •   a cchar_t pointer wch is null.

NOTES

       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.

PORTABILITY

       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.

SEE ALSO

       bkgd(3NCURSES)  describes  the  corresponding functions in the non-“wide” configuration of
       ncurses.

       ncurses(3NCURSES), add_wch(3NCURSES), attr(3NCURSES)