|
HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | PORTABILITY | HISTORY | SEE ALSO | COLOPHON |
|
|
|
curs_bkgrnd(3X) Library calls curs_bkgrnd(3X)
bkgrnd, wbkgrnd, bkgrndset, wbkgrndset, getbkgrnd, wgetbkgrnd -
manipulate background of a curses window of wide characters
#include <curses.h>
int bkgrnd(const cchar_t *wch);
int wbkgrnd(WINDOW *win, const cchar_t *wch);
void bkgrndset(const cchar_t *wch);
void wbkgrndset(WINDOW *win, const cchar_t *wch);
int getbkgrnd(cchar_t *wch);
int wgetbkgrnd(WINDOW *win, cchar_t *wch);
Every curses window has a background character property: in the
library's wide configuration, it is a curses complex character
(cchar_t) that combines a set of attributes (and, if colors are
enabled, a color pair identifier) with a character code. When
erasing (parts of) a window, curses replaces the erased cells with
the background character.
curses also uses the background character when writing characters
to a populated window.
• The attribute part of the background character combines with
all non-blank character cells in the window, as populated by
the wadd_wch(3X) and wins_wch(3X) families of functions (and
those that call them).
• Both the character code and attributes of the background
character combine with blank character cells in the window.
The background character's set of attributes becomes a property of
the character cell and move with it through any scrolling and
insert/delete line/character operations. To the extent possible
on the terminal type, curses displays the attributes of the
background character as the graphic rendition of a character cell
on the display.
bkgrnd, wbkgrnd
bkgrnd and wbkgrnd set the background property of stdscr or the
specified window and then apply this setting to every character
cell in that window.
• The rendition of every character in the window changes to the
new background rendition.
• Wherever the former background character appears, it changes
to the new background character.
ncurses updates the rendition of each character cell by comparing
the character, non-color attributes, and color pair selection.
The library applies to following procedure to each cell in the
window, whether or not it is blank.
• ncurses first compares the cell's character to the previously
specified background character; if they match, ncurses writes
the new background character to the cell.
• ncurses then checks whether 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.
• If the cell uses color, and its background color matches that
of the current window background, 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.
• If the cell uses color, and its background color does not
match that of the current window background, 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.
If the new background's character is non-spacing, ncurses reuses
the old background character, except for one special case: ncurses
treats a background character code of zero (0) as a space.
If the terminal does not support color, or if color has not been
initialized with start_color(3X), ncurses ignores the new
background character's color pair selection.
bkgrndset, wbkgrndset
bkgrndset and wbkgrndset manipulate the background of the
applicable window, without updating the character cells as bkgrnd
and wbkgrnd do; only future writes reflect the updated background.
getbkgrnd, wgetbkgrnd
getbkgrnd and wgetbkgrnd respectively obtain stdscr's or the given
window's background character, attributes, and color pair, and
store it in their wch argument.
bkgrndset and wbkgrndset do not return a value.
Functions returning an int return ERR upon failure and OK upon
success. In ncurses, failure occurs if
• the curses screen has not been initialized,
• win is NULL, or
• wch is NULL.
bkgrnd, bkgrndset, and getbkgrnd may be implemented as macros.
Unlike their counterparts in the non-wide-character configuration
of ncurses, getbkgrnd and wgetbkgrnd store the background
character in a modifiable cchar_t parameter, rather than supplying
it as the return value.
X/Open Curses Issue 4 describes these functions. It specifies no
error conditions for them.
X/Open Curses does not provide details of how the rendition is
updated. ncurses follows the approach used in SVr4 curses's non-
wide functions for manipulating the window background.
X/Open Curses Issue 4 (1995) initially specified these functions.
curs_bkgd(3X) describes the corresponding functions in the non-
wide-character configuration of ncurses.
curses(3X), curs_add_wch(3X), curs_attr(3X)
This page is part of the ncurses (new curses) project.
Information about the project can be found at
⟨https://invisible-island.net/ncurses/ncurses.html⟩. If you have a
bug report for this manual page, send it to bug-ncurses@gnu.org.
This page was obtained from the tarball ncurses-6.6.tar.gz fetched
from ⟨https://ftp.gnu.org/gnu/ncurses/⟩ on 2026-01-16. If you
discover any rendering problems in this HTML version of the page,
or you believe there is a better or more up-to-date source for the
page, or you have corrections or improvements to the information
in this COLOPHON (which is not part of the original manual page),
send a mail to man-pages@man7.org
ncurses @NCURSES_MAJOR@.@NCU... 2025-08-23 curs_bkgrnd(3X)
|
HTML rendering created 2026-01-16 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|