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)

ncurses 6.4                                        2023-12-23                                     bkgd(3NCURSES)