# curs_bkgd 3x

    curs_bkgd(3x)                                                    curs_bkgd(3x)

## NAME

           bkgdset,  wbkgdset,  bkgd,  wbkgd,  getbkgd  - curses window background
           manipulation routines

## SYNOPSIS

           #include <curses.h>

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

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

           chtype getbkgd(WINDOW *win);

## DESCRIPTION

### bkgdset

           The bkgdset and wbkgdset routines set the background for a  window.   A
           window's  background  is  a  chtype  consisting  of  any combination of
           attributes (i.e., rendition) and a character:

           o   The attribute part of the background is combined (OR'ed)  with  all
               non-blank characters that are written into the window with waddch.

           o   Both  the  character  and  attribute  parts  of  the background are
               combined with blank characters that are written into the window.

           The background becomes a property of each character and moves with  the
           character   through  any  scrolling  and  insert/delete  line/character
           operations.

           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.

### bkgd

           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.  According to  X/Open  Curses,  it  should  do
           this:

           o   The  rendition  of  every character on the screen is changed to the
               new background rendition.

           o   Wherever the former background character appears, it is changed  to
               the new background character.

           Neither  X/Open Curses nor the SVr4 manual pages give details about the
           way the rendition of characters on the screen is updated when  bkgd  or
           wbkgd is used to change the background character.

           This  implementation,  like  SVr4 curses, does not store the background
           and window attribute contributions to each cell separately.  It updates
           the  rendition  by  comparing  the  character, non-color attributes and
           colors contained in the background.   For  each  cell  in  the  window,
           whether or not it is blank:

           o   The  library  first  compares  the character, and if it matches the
               current character part of the background, it replaces that with the
               new background character.

               When bkgdset is used to set the background character, that does not
               update each cell in the window.  A subsequent  call  to  bkgd  will
               only  modify  the  character  in  cells  which  match  the  current
               background character.

           o   The library then checks if the cell uses  color,  i.e.,  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 that matches the color in the current
               background, the library removes attributes which may have come from
               the current background and adds attributes from the new background.
               It finishes by setting the cell to  use  the  color  from  the  new
               background.

           o   If  the  cell  uses color, and that does not match the color in the
               current  background,  the  library  updates  only   the   non-color
               attributes,  first  removing  those  which  may  have come from the
               current  background,  and  then  adding  attributes  from  the  new
               background.

           If the background's character value is zero (0), a space is assumed.

           If  the  terminal  does  not  support  color,  or if color has not been
           started  with  start_color,  the  new  background   character's   color
           attribute will be ignored.

### getbkgd

           The  getbkgd  function  returns  the  given window's current background
           character/attribute pair.

## RETURN VALUE

           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.

           The routines bkgd and wbkgd return the integer OK, unless  the  library
           has not been initialized.

           In  contrast, the SVr4.0 manual says bkgd and wbkgd may return OK "or a
           non-negative integer if immedok is set", which  refers  to  the  return
           value  from wrefresh (used to implement the immediate repainting).  The
           SVr4 curses wrefresh returns the number of characters  written  to  the
           screen during the refresh.  This implementation does not do that.

## NOTES

           Note that bkgdset and bkgd may be macros.

           X/Open  Curses  mentions that the character part of the background must
           be a single-byte value.  This  implementation,  like  SVr4,  checks  to
           ensure  that,  and will reuse the old background character if the check
           fails.

## PORTABILITY

           These functions are described in  the  XSI  Curses  standard,  Issue  4
           (X/Open Curses).

## SEE ALSO

           curses(3x), curs_addch(3x), curs_attr(3x), curs_outopts(3x)

                                                                     curs_bkgd(3x)