X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_bkgd.3x.html;h=c77f4f99a22604551702d10ea579e81375bac475;hp=d47f7b5e771685b1c1c9a3746b92640243eb853d;hb=HEAD;hpb=a6eb34d7fec8170a8715f9e53ca2f96452dd30dd diff --git a/doc/html/man/curs_bkgd.3x.html b/doc/html/man/curs_bkgd.3x.html index d47f7b5e..fca843e4 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) +curs_bkgd(3x) Library calls curs_bkgd(3x)
- bkgdset, wbkgdset, bkgd, wbkgd, getbkgd - curses window background - manipulation routines + bkgdset, wbkgdset, bkgd, wbkgd, getbkgd - manipulate background of a + curses window of characters
#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);
+ 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. + + 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. + + 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. + + +
+ 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. -
- The bkgdset and wbkgdset routines manipulate the background 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 - 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. - - 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 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. - - 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 + 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. - 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 + 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. + + 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, 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 - started with start_color, the new background character's color - attribute will be ignored. + initialized with start_color(3x), ncurses ignores the new background + character's color attribute. + + +
+ 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.
- The getbkgd function returns the given window's current background - character/attribute pair. + getbkgd obtains the given window's background character and attribute + combination.
- 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.
- 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. + 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.
- 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.
- curses(3x), curs_addch(3x), curs_attr(3x), curs_outopts(3x) + curs_bkgrnd(3x) describes the corresponding functions in the "wide" + configuration of ncurses. + + curses(3x), curs_addch(3x), curs_attr(3x) - curs_bkgd(3x) +ncurses 6.4 2024-04-20 curs_bkgd(3x)