NAME

       bkgdset,  wbkgdset,  bkgd,  wbkgd,  getbkgd  - manipulate background of a curses window of
       characters

SYNOPSIS

       #include <curses.h>

       int bkgd(chtype ch);
       int wbkgd(WINDOW *win, chtype ch);

       void bkgdset(chtype ch);
       void wbkgdset(WINDOW *win, chtype ch);

       chtype getbkgd(WINDOW *win);

DESCRIPTION

       The background of a curses window (in the library's non-“wide” configuration) is a  chtype
       combining  a  set  of  attributes  (see  attr(3NCURSES)) with a 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  waddch(3NCURSES)  and
       winsch(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.

   bkgd, wbkgd
       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.

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

   bkgdset, wbkgdset
       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.

   getbkgd
       getbkgd obtains the given window's background character and attribute combination.

RETURN VALUE

       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.

NOTES

       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.

PORTABILITY

       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(3NCURSES),  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.

SEE ALSO

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

       ncurses(3NCURSES), addch(3NCURSES), attr(3NCURSES)