ncurses 6.4 - patch 20230701

[ncurses.git] / man / curs_bkgd.3x

diff --git a/man/curs_bkgd.3x b/man/curs_bkgd.3x
index 2c3d3d4fee93d8663cfa031a4c06927e3d14107e..927b009ea83b7370791d0d1a122da55050b98c10 100644 (file)
--- a/man/curs_bkgd.3x
+++ b/man/curs_bkgd.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright 2018-2021,2022 Thomas E. Dickey                                *
+.\" Copyright 2018-2022,2023 Thomas E. Dickey                                *
 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
@@ -27,12 +27,12 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_bkgd.3x,v 1.34 2022/02/12 20:06:41 tom Exp $
+.\" $Id: curs_bkgd.3x,v 1.39 2023/07/01 15:43:20 tom Exp $
 .de bP
 .ie n  .IP \(bu 4
 .el    .IP \(bu 2
 ..
-.TH curs_bkgd 3X ""
+.TH curs_bkgd 3X 2023-07-01 "ncurses 6.4" "Library calls"
 .SH NAME
 \fBbkgdset\fP, \fBwbkgdset\fP,
 \fBbkgd\fP, \fBwbkgd\fP,
@@ -52,15 +52,18 @@
 .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
@@ -68,12 +71,10 @@ 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 bkgd
-.PP
 The \fBbkgd\fP and \fBwbkgd\fP 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:
-.PP
 .bP
 The rendition of every character on the screen is changed to
 the new background rendition.
@@ -94,6 +95,11 @@ For each cell in the window, whether or not it is blank:
 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.
@@ -114,17 +120,15 @@ 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.
 .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,
 the new background character's color attribute will be ignored.
 .SS getbkgd
-.PP
 The \fBgetbkgd\fP function returns the given window's current background
 character/attribute pair.
 .SH RETURN VALUE
-.PP
 These functions are described in the XSI Curses standard, Issue 4.
 It specifies that \fBbkgd\fP and \fBwbkgd\fP return \fBERR\fP on failure,
 but gives no failure conditions.
@@ -141,7 +145,6 @@ The SVr4 curses \fBwrefresh\fP returns the number of characters
 written to the screen during the refresh.
 This implementation does not do that.
 .SH NOTES
-.PP
 Note that \fBbkgdset\fP and \fBbkgd\fP may be macros.
 .PP
 X/Open Curses mentions that the character part of the background must
@@ -149,12 +152,10 @@ be a single-byte value.
 This implementation, like SVr4, checks to ensure that,
 and will reuse the old background character if the check fails.
 .SH PORTABILITY
-.PP
 These functions are described in the XSI Curses standard, Issue 4
 (X/Open Curses).
 .SH SEE ALSO
 .na
-.PP
 \fBcurses\fP(3X),
 \fBcurs_addch\fP(3X),
 \fBcurs_attr\fP(3X),