.\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey *
+.\" Copyright 2018-2021,2022 Thomas E. Dickey *
.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_bkgd.3x,v 1.33 2021/12/25 17:39:16 tom Exp $
+.\" $Id: curs_bkgd.3x,v 1.35 2022/06/25 21:55:45 tom Exp $
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
.SH SYNOPSIS
\fB#include <curses.h>\fP
.PP
-\fBvoid bkgdset(chtype \fP\fIch\fP\fB);\fP
+\fBvoid bkgdset(chtype \fIch\fB);\fR
.br
-\fBvoid wbkgdset(WINDOW *\fP\fIwin, chtype \fP\fIch\fP\fB);\fP
+\fBvoid wbkgdset(WINDOW *\fIwin, chtype \fIch\fB);\fR
.sp
-\fBint bkgd(chtype \fP\fIch\fP\fB);\fP
+\fBint bkgd(chtype \fIch\fB);\fR
.br
-\fBint wbkgd(WINDOW *\fP\fIwin\fP\fB, chtype \fP\fIch\fP\fB);\fP
+\fBint wbkgd(WINDOW *\fIwin\fB, chtype \fIch\fB);\fR
.sp
-\fBchtype getbkgd(WINDOW *\fP\fIwin\fP\fB);\fP
+\fBchtype getbkgd(WINDOW *\fIwin\fB);\fR
.br
.SH DESCRIPTION
.SS bkgdset
-The \fBbkgdset\fP and \fBwbkgdset\fP routines manipulate the
-background of the named window.
-The window background is a \fBchtype\fP consisting of
-any combination of attributes (i.e., rendition) and a character.
+The \fBbkgdset\fP and \fBwbkgdset\fP routines
+set the \fIbackground\fP for a window.
+A window's background is a \fBchtype\fP consisting of
+any combination of attributes (i.e., rendition) and a character:
+.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.
+.bP
Both the character and attribute parts of the background are combined with
-the blank characters.
-The background becomes a property of the
+blank characters that are written into the window.
+.PP
+The background becomes a property of each
character and moves with the character through any scrolling and
insert/delete line/character operations.
.PP
The library first compares the \fIcharacter\fP,
and if it matches the current character part of the background,
it replaces that with the new background character.
+.IP
+When \fBbkgdset\fP is used to set the background character,
+that does not update each cell in the window.
+A subsequent call to \fBbkgd\fP will only modify the \fIcharacter\fP in
+cells which match the current background character.
.bP
The library then checks if the cell uses color,
i.e., its color pair value is nonzero.
first removing those which may have come from the current background,
and then adding attributes from the new background.
.PP
-If the background's character value is zero, a space is assumed.
+If the background's character value is zero (0), a space is assumed.
.PP
If the terminal does not support color,
or if color has not been started with \fBstart_color\fP,