X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_bkgd.3x.html;h=c77f4f99a22604551702d10ea579e81375bac475;hb=HEAD;hp=d4a6a1d4c4bbde12219f1a931c8f3f9b3b5cb52b;hpb=80803f3a4a1fbdebb4de105cef9a10af36230f3c;p=ncurses.git diff --git a/doc/html/man/curs_bkgd.3x.html b/doc/html/man/curs_bkgd.3x.html index d4a6a1d4..47d2e13b 100644 --- a/doc/html/man/curs_bkgd.3x.html +++ b/doc/html/man/curs_bkgd.3x.html @@ -1,6 +1,6 @@ -curs_bkgd 3x +curs_bkgd 3x 2024-04-20 ncurses 6.5 Library calls -

curs_bkgd 3x

curs_bkgd 3x 2024-04-20 ncurses 6.5 Library calls

-curs_bkgd(3x)                                                    curs_bkgd(3x)
+curs_bkgd(3x)                    Library calls                   curs_bkgd(3x)

NAME

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

SYNOPSIS

        #include <curses.h>
 
-       void bkgdset(chtype ch);
-       void wbkgdset(WINDOW *win, chtype ch);
-
        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
+       curs_attr(3x)) with a character called the blank character.
 
-

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.
-
+       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(3x) and winsch(3x) families
+       of functions.
 
-

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:
+       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.
 
-       o   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.
 
-       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.
+

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.
 
-       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  rendition  of every character in the window changes to the new
+           background rendition.
 
-       o   The  library  first  compares  the character, and if it matches the
-           current character part of the background, it replaces that with the
+       o   Wherever the former background character appears, it changes to 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.
+       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.
 
-       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
+       o   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.
+
+       o   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.
 
-       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 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.
 
-       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
+       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.
 
-       If the background's character value is zero (0), a space is assumed.
+       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.
+
 
-       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.
+

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

-       The  getbkgd  function  returns  the  given window's current background
-       character/attribute pair.
+       getbkgd obtains the given window's background character  and  attribute
+       combination.

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.
+       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.
 
-       The routines bkgd and wbkgd return the integer OK, unless  the  library
-       has not been initialized.
+       bkgdset and wbkgdset do not return a value.
 
-       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.
+       getbkgd   returns   a   window's  background  character  and  attribute
+       combination.

NOTES

-       Note that bkgdset and bkgd may be macros.
+       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.  This  implementation,  like  SVr4,  checks  to
-       ensure  that,  and will reuse the old background character if the check
-       fails.
+       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

-       These functions are described in  the  XSI  Curses  standard,  Issue  4
-       (X/Open Curses).
+       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(3x), 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.