X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_bkgd.3x.html;h=9632a9e1f6fead0679277a9329f0eb4c2a3f4d1f;hb=09ed0227b324243f636e31d876e3dc30dfc7a778;hp=81cdf90cf26111ceb7303bca27359d3f441f91d7;hpb=6208c89f98f1cf9fe0980bd8e791846ce007a13d;p=ncurses.git diff --git a/doc/html/man/curs_bkgd.3x.html b/doc/html/man/curs_bkgd.3x.html index 81cdf90c..9632a9e1 100644 --- a/doc/html/man/curs_bkgd.3x.html +++ b/doc/html/man/curs_bkgd.3x.html @@ -1,6 +1,7 @@ - - -curs_bkgd 3x - - + +curs_bkgd 3x 2023-12-02 ncurses 6.4 Library calls + + -

curs_bkgd 3x

curs_bkgd 3x 2023-12-02 ncurses 6.4 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);
+       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  manipulate  the  back-
-       ground  of  the  named window.  The window background is a
-       chtype consisting of any combination of attributes  (i.e.,
-       rendition)  and  a  character.   The attribute part of the
-       background is combined (OR'ed) with all non-blank  charac-
-       ters  that  are written into the window with waddch.  Both
-       the character and attribute parts of  the  background  are
-       combined   with  the  blank  characters.   The  background
-       becomes a property of the 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 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:
+       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.
 
-       o   The rendition of every  character  on  the  screen  is
-           changed to the new background rendition.
+       ncurses,  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   Wherever  the  former background character appears, it
-           is changed to the new background character.
+       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.
+       The  getbkgd  function  returns  the  given window's current background
+       character/attribute pair.

RETURN VALUE

-       The  routines  bkgd  and wbkgd return the integer OK.  The
-       SVr4.0 manual says "or a non-negative integer  if  immedok
-       is set", but this appears to be an error.
+       Functions returning an int return OK on success.  bkgd returns  ERR  if
+       the  library has not been initialized.  wbkgd and getbkgd return ERR if
+       the WINDOW pointer argument is null.
+
+       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).  SVr4
+       curses  wrefresh returns the number of characters written to the screen
+       during the refresh.  ncurses does not do that.

NOTES

+       Unusually, there is no wgetbkgd function; getbkgd behaves as one  would
+       expect wgetbkgd to, accepting a WINDOW pointer argument.
+
        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.  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.  It specifies that bkgd and wbkgd return  ERR  on
-       failure, but gives no failure conditions.
+       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.