X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_bkgrnd.3x.html;h=8ffea8a11a8e69add8fa98854832236236646163;hp=7d952f0c2a2f1ecb064484872ee1f941d54348d5;hb=HEAD;hpb=321b81e6b3fa425daddac02420d862100dc3aac8 diff --git a/doc/html/man/curs_bkgrnd.3x.html b/doc/html/man/curs_bkgrnd.3x.html index 7d952f0c..6f2742de 100644 --- a/doc/html/man/curs_bkgrnd.3x.html +++ b/doc/html/man/curs_bkgrnd.3x.html @@ -1,6 +1,7 @@ - -curs_bkgrnd 3x - - +curs_bkgrnd 3x 2024-04-20 ncurses 6.4 Library calls + + -

curs_bkgrnd 3x

curs_bkgrnd 3x 2024-04-20 ncurses 6.4 Library calls

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

NAME

-       bkgrnd,  wbkgrnd, bkgrndset, wbkgrndset, getbkgrnd, wgetbkgrnd - curses
-       window complex background manipulation routines
+       bkgrnd,   wbkgrnd,   bkgrndset,  wbkgrndset,  getbkgrnd,  wgetbkgrnd  -
+       manipulate background of a curses window of wide characters

SYNOPSIS

        #include <curses.h>
 
-       int bkgrnd( const cchar_t *wch);
-       int wbkgrnd( WINDOW *win, const cchar_t *wch);
-       void bkgrndset(const cchar_t *wch );
+       int bkgrnd(const cchar_t *wch);
+       int wbkgrnd(WINDOW *win, const cchar_t *wch);
+
+       void bkgrndset(const cchar_t *wch);
        void wbkgrndset(WINDOW *win, const cchar_t *wch);
+
        int getbkgrnd(cchar_t *wch);
        int wgetbkgrnd(WINDOW *win, cchar_t *wch);

DESCRIPTION

+       The  background  of  a  curses  window   (in   the   library's   "wide"
+       configuration)  is  a  cchar_t  combining  a  set  of  attributes  (see
+       curs_attr(3x)) with a complex character called the blank character.
 
-

bkgrndset

-       The bkgrndset and wbkgrndset routines manipulate the background of  the
-       named  window.   The  window  background is a cchar_t consisting of any
-       combination of attributes (i.e., rendition) and  a  complex  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 blank characters.  The background becomes a property of the charac-
-       ter   and   moves   with   the  character  through  any  scrolling  and
-       insert/delete line/character operations.
+       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  wadd_wch(3x) and wins_wch(3x)
+       families of functions.
 
-       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 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.
 
-

bkgrnd

-       The bkgrnd and wbkgrnd functions set the  background  property  of  the
-       current  or specified window and then apply this setting to every char-
-       acter position in that window:
 
-       o   The rendition of every character on the screen is  changed  to  the
-           new background rendition.
+

bkgrnd, wbkgrnd

+       bkgrnd  and  wbkgrnd  set  the  background  property  of  stdscr or the
+       specified window and then apply this setting to every character cell in
+       that window.
 
-       o   Wherever  the former background character appears, it is changed to
-           the new background character.
+       o   The  rendition  of every character in the window changes to the new
+           background rendition.
 
+       o   Wherever the former background character appears, it changes to the
+           new background character.
 
-

getbkgrnd

-       The getbkgrnd function returns the given  window's  current  background
-       character/attribute  pair  via  the  wch  pointer.  If the given window
-       pointer is null, the character is not updated (but no error returned).
+       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   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.
 
-

NOTES

-       Note that bkgrnd, bkgrndset, and getbkgrnd may be macros.
+       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 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 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(3x),  ncurses ignores the new background
+       character's color attribute.
+
+
+

bkgrndset, wbkgrndset

+       bkgrndset and wbkgrndset manipulate the background  of  the  applicable
+       window,  without updating the character cells as bkgrnd and wbkgrnd do;
+       only future writes reflect the updated background.
 
-       X/Open Curses does not provide details on how the rendition is changed.
-       This  implementation follows the approach used in SVr4 curses, which is
-       explained in the manual page for wbkgd.
+
+

getbkgrnd, wgetbkgrnd

+       The getbkgrnd and wgetbkgrnd functions obtain the background  character
+       and  attribute  pair of stdscr or the specified window and store it via
+       the wch pointer.

RETURN VALUE

-       The bkgrndset and wbkgrndset routines do not return a value.
+       bkgrndset and wbkgrndset do not return a value.
+
+       The other functions return ERR upon failure and OK  upon  success.   In
+       ncurses, failure occurs if
+
+       o   a WINDOW pointer win is null, or
 
-       Upon successful completion, the other functions return OK.   Otherwise,
-       they return ERR:
+       o   a cchar_t pointer wch is null.
 
-       o   A null window pointer is treated as an error.
 
-       o   A null character pointer is treated as an error.
+

NOTES

+       bkgrnd, bkgrndset, and getbkgrnd may be implemented as macros.
+
+       Unlike  their  counterparts in the non-"wide" configuration of ncurses,
+       getbkgrnd and wgetbkgrnd supply the background character and  attribute
+       in a modifiable cchar_t parameter, not as the return value.

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 no
+       error conditions for them.
+
+       X/Open Curses does not provide details of how the rendition is updated.
+       This implementation follows the approach used in SVr4 curses.