.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
.\" Copyright 2002-2015,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_bkgrnd.3x,v 1.34 2023/12/02 21:30:00 tom Exp $
-.TH curs_bkgrnd 3X 2023-12-02 "ncurses 6.4" "Library calls"
+.\" $Id: curs_bkgrnd.3x,v 1.46 2024/09/22 18:23:50 tom Exp $
+.TH curs_bkgrnd 3X 2024-09-22 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
\fBint wgetbkgrnd(WINDOW *\fIwin\fP, cchar_t *\fIwch\fP);
.fi
.SH DESCRIPTION
-.SS bkgrndset
-The \fBbkgrndset\fP and \fBwbkgrndset\fP routines manipulate the
-background of the named window.
-The window background is a \fBcchar_t\fP consisting of
-any combination of attributes (i.e., rendition) and a complex character.
+Every
+.I curses
+window has a background property.
+In the library's wide configuration,
+this property is a
+.I \%cchar_t
+which combines a set of attributes with the
+.I "background character"
+(see \fB\%curs_attr\fP(3X))
+The background character is a spacing character.
+.PP
+When erasing parts of the screen,
+.I curses
+fills the cells with the background character.
+.I curses
+also uses the window background when writing characters to the screen:
.bP
-The attribute part of the background is combined (OR'ed) with all non-blank
-characters that are written into the window with \fBwaddch\fP.
+The attribute part of the background is combined with all
+non-blank characters that are written into the window,
+as with the \fB\%wadd_wch\fP(3X) and \fB\%wins_wch\fP(3X) families of
+functions.
.bP
-Both
-the character and attribute parts of the background are combined with
-the blank characters.
+Both the character and attribute parts of the background are combined with
+blank characters that are written into the window.
+.PP
+The background becomes a property of the character and moves with it
+through any scrolling and insert/delete line/character operations.
.PP
-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 given terminal,
+the attribute part of the background is displayed as the graphic
+rendition of the character put on the screen.
+.SS "bkgrnd, wbkgrnd"
+\fB\%bkgrnd\fP and \fB\%wbkgrnd\fP set the background property of
+\fB\%stdscr\fP or the specified window and then apply this setting to
+every character cell in that window.
+.bP
+The rendition of every character in the window changes to the new
+background rendition.
+.bP
+Wherever the former background character appears,
+it changes to the new background character.
.PP
-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.
-.SS bkgrnd
-The \fBbkgrnd\fP and \fBwbkgrnd\fP functions
-set the background property of the current or specified window
-and then apply this setting to every character position in that window:
+.I \%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.
+.bP
+.I \%ncurses
+first compares the cell's character to the previously specified
+background character;
+if they match,
+.I \%ncurses
+writes the new background character to the cell.
+.bP
+.I \%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.
.bP
-The rendition of every character on the screen is changed to
-the new background rendition.
+If the cell uses color,
+and its background color matches that of the current window background,
+.I \%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.
.bP
-Wherever the former background character
-appears, it is changed to the new background character.
-.SS getbkgrnd
-The \fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP functions obtain the given
-or specified window's current background character and attribute pair
-and store it via the
+If the cell uses color,
+and its background color does not match that of the current window
+background,
+.I \%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.
+.PP
+If the new background's character is nonspacing,
+.I \%ncurses
+reuses the old background character,
+except for one special case:
+.I \%ncurses
+treats a background character value of zero (0) as a space.
+.PP
+If the terminal does not support color,
+or if color has not been initialized with \fB\%start_color\fP(3X),
+.I \%ncurses
+ignores the new background character's color attribute.
+.SS "bkgrndset, wbkgrndset"
+\fB\%bkgrndset\fP and \fB\%wbkgrndset\fP manipulate the background of
+the applicable window,
+without updating the character cells as \fB\%bkgrnd\fP and
+\fB\%wbkgrnd\fP do;
+only future writes reflect the updated background.
+.SS "getbkgrnd, wgetbkgrnd"
+The \fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP functions obtain the
+background character and attribute pair of \fB\%stdscr\fP or the
+specified window and store it via the
.I wch
pointer.
.SH RETURN VALUE
-The \fBbkgrndset\fP and \fBwbkgrndset\fP routines do not return a value.
+\fBbkgrndset\fP and \fBwbkgrndset\fP do not return a value.
.PP
-Upon successful completion, the other functions return \fBOK\fP.
-Otherwise, they return \fBERR\fP:
+The other functions return
+.B ERR
+upon failure and
+.B OK
+upon success.
+In
+.IR \%ncurses ,
+failure occurs if
.bP
-A null \fI\%WINDOW\fP pointer is treated as an error.
+a
+.I \%WINDOW
+pointer
+.I win
+is null, or
.bP
-A null \fI\%cchar_t\fP pointer is treated as an error.
+a
+.I \%cchar_t
+pointer
+.I wch
+is null.
.SH NOTES
\fB\%bkgrnd\fP,
\fB\%bkgrndset\fP, and
\fB\%getbkgrnd\fP
-may be available as macros.
+may be implemented as macros.
.PP
-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 \fBwbkgd\fP.
+Unlike their counterparts in the non-wide configuration of
+.IR \%ncurses ,
+\fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP supply the background character
+and attribute in a modifiable
+.I \%cchar_t
+parameter,
+not as the return value.
.SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+X/Open Curses does not provide details of how the rendition is updated.
+This implementation follows the approach used in SVr4
+.IR curses .
.SH SEE ALSO
+\fB\%curs_bkgd\fP(3X) describes the corresponding functions in the
+non-wide configuration of
+.IR \%ncurses .
+.PP
\fB\%curses\fP(3X),
-\fB\%curs_bkgd\fP(3X)
+\fB\%curs_add_wch\fP(3X),
+\fB\%curs_attr\fP(3X)
projects / ncurses.git / blobdiff