X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_bkgrnd.3x.html;h=8e60e213d1b8b6638a613e034acb8817a8b8f57b;hb=HEAD;hp=d5e9959a26235ae2b4f21e9c5b8bccd69f2eab08;hpb=6208c89f98f1cf9fe0980bd8e791846ce007a13d;p=ncurses.git diff --git a/doc/html/man/curs_bkgrnd.3x.html b/doc/html/man/curs_bkgrnd.3x.html index d5e9959a..a11a68c5 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) +curs_bkgrnd(3x) Library calls curs_bkgrnd(3x)
- bkgrnd, wbkgrnd, bkgrndset, wbkgrndset, getbkgrnd, wget- - bkgrnd - curses window complex background manipulation - routines + bkgrnd, wbkgrnd, bkgrndset, wbkgrndset, getbkgrnd, wgetbkgrnd - + manipulate background of a curses window of wide characters
#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);
+ 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. -
- The bkgrndset and wbkgrndset routines manipulate the back- - ground 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 character 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. -
- The bkgrnd and wbkgrnd functions set the background prop- - erty of the current or specified window and then apply - this setting to every character position in that window: - o The rendition of every character on the screen is - changed to the new background rendition. +
+ 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. -
- The getbkgrnd function returns the given window's current - background character/attribute pair via the wch pointer. + 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. -
- 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 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. + + +
+ 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.
- The bkgrndset and wbkgrndset routines do not return a - value. + bkgrndset and wbkgrndset do not return a value. - Upon successful completion, the other functions return OK. - Otherwise, they return ERR. A null window pointer is - treated as an error. + The other functions return ERR upon failure and OK upon success. In + ncurses, failure occurs if + + o a WINDOW pointer win is null, or + + o a cchar_t pointer wch is null. + + +
+ 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. + + +
+ 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.
- curses(3x), curs_bkgd(3x) + curs_bkgd(3x) describes the corresponding functions in the non-"wide" + configuration of ncurses. + curses(3x), curs_add_wch(3x), curs_attr(3x) - curs_bkgrnd(3x) + +ncurses 6.5 2024-04-20 curs_bkgrnd(3x)