ncurses 6.5 - patch 20240922

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

diff --git a/man/curs_bkgrnd.3x b/man/curs_bkgrnd.3x
index 2551924c11a31eafe598d6d60cf93231e6934d82..41412b9b93b7d24f6d21e92c6d126beb2ad5f0ff 100644 (file)
--- a/man/curs_bkgrnd.3x
+++ b/man/curs_bkgrnd.3x
@@ -27,8 +27,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_bkgrnd.3x,v 1.42 2024/04/20 18:54:36 tom Exp $
-.TH curs_bkgrnd 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "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
@@ -66,28 +66,31 @@ manipulate background of a \fIcurses\fP window of wide characters
 \fBint wgetbkgrnd(WINDOW *\fIwin\fP, cchar_t *\fIwch\fP);
 .fi
 .SH DESCRIPTION
-The
-.I background
-of a
+Every
 .I curses
-window
-(in the library's \*(``wide\*('' configuration)
-is a
+window has a background property.
+In the library's wide configuration,
+this property is a
 .I \%cchar_t
-combining a set of attributes
+which combines a set of attributes with the
+.I "background character"
 (see \fB\%curs_attr\fP(3X))
-with a complex character called the
-.I "blank character."
+The background character is a spacing character.
 .PP
-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,
+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 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
+blank characters that are written into the window.
 .PP
-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.
 .PP
@@ -113,11 +116,11 @@ 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 blank
-character;
+first compares the cell's character to the previously specified
+background character;
 if they match,
 .I \%ncurses
-writes the new blank character to the cell.
+writes the new background character to the cell.
 .bP
 .I \%ncurses
 then checks if the cell uses color,
@@ -143,8 +146,12 @@ 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 blank character.
+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),
@@ -191,7 +198,7 @@ is null.
 \fB\%getbkgrnd\fP
 may be implemented as macros.
 .PP
-Unlike their counterparts in the non-\*(``wide\*('' configuration of
+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
@@ -208,7 +215,7 @@ 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
+non-wide configuration of
 .IR \%ncurses .
 .PP
 \fB\%curses\fP(3X),