X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_bkgd.3x.html;h=d47f7b5e771685b1c1c9a3746b92640243eb853d;hp=f48decaf5b10b214d77e3edf0c5c674b61001392;hb=a6eb34d7fec8170a8715f9e53ca2f96452dd30dd;hpb=06078d3fa68db669ed37178c01873546b4b28745 diff --git a/doc/html/man/curs_bkgd.3x.html b/doc/html/man/curs_bkgd.3x.html index f48decaf..d47f7b5e 100644 --- a/doc/html/man/curs_bkgd.3x.html +++ b/doc/html/man/curs_bkgd.3x.html @@ -1,6 +1,7 @@
- +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 @@
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. +
The getbkgd function returns the given window's current background @@ -96,19 +137,32 @@
- 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.
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. +
- 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).