X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_bkgd.3x.html;h=be9dc1e11fb04c4f3d28545e22e0b4982930ddcc;hp=b5637820dcdf809674ddd1caa0a456e83d82209f;hb=81304798ee736c467839c779c9ca5dca48db7bea;hpb=17c5992a16be94247b83f2bbb9accdd9b7e7bb72 diff --git a/doc/html/man/curs_bkgd.3x.html b/doc/html/man/curs_bkgd.3x.html index b5637820..be9dc1e1 100644 --- a/doc/html/man/curs_bkgd.3x.html +++ b/doc/html/man/curs_bkgd.3x.html @@ -1,6 +1,7 @@ - @@ -34,7 +35,7 @@ curs_bkgd 3x - + @@ -55,8 +56,10 @@ void bkgdset(chtype ch); void wbkgdset(WINDOW *win, chtype ch); + int bkgd(chtype ch); int wbkgd(WINDOW *win, chtype ch); + chtype getbkgd(WINDOW *win); @@ -64,8 +67,8 @@

bkgdset

        The bkgdset and wbkgdset routines  manipulate  the  background  of  the
-       named window.  The window background is a chtype consisting of any com-
-       bination  of  attributes  (i.e.,  rendition)  and  a  character.    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
        characters that are written into the  window  with  waddch.   Both  the
        character  and  attribute parts of the background are combined with the
@@ -81,14 +84,52 @@

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:
+       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
+       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
+       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.
+
+       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, 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
@@ -96,19 +137,32 @@

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.
+       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.  It
-       specifies that bkgd and wbkgd return ERR on failure, but gives no fail-
-       ure conditions.
+       These  functions  are  described  in  the  XSI Curses standard, Issue 4
+       (X/Open Curses).

SEE ALSO