curs_bkgrnd
Section: Library calls (3X)
Updated: 202-0-23
Index
Return to Main Contents
NAME
bkgrnd,
wbkgrnd,
bkgrndset,
wbkgrndset,
getbkgrnd,
wgetbkgrnd -
manipulate background of a
curses window of wide characters
SYNOPSIS
#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);
DESCRIPTION
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.
.IP * 4
The attribute part of the background character combines with all
no-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).
.IP * 4
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.
.IP * 4
The rendition of every character in the window changes to the new
background rendition.
.IP * 4
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,
no-color attributes,
and color pair selection.
The library applies to following procedure to each cell in the window,
whether or not it is blank.
.IP * 4
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.
.IP * 4
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.
.IP * 4
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.
.IP * 4
If the cell uses color,
and its background color does not match that of the current window
background,
ncurses
updates only the no-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 no-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.
RETURN VALUE
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
.IP * 4
the
curses
screen has not been initialized,
.IP * 4
win
is
NULL,
or
.IP * 4
wch
is
NULL.
NOTES
bkgrnd,
bkgrndset,
and
getbkgrnd
may be implemented as macros.
Unlike their counterparts in the no-wid-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.
PORTABILITY
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
no-wide functions for manipulating the window background.
HISTORY
X/Open Curses Issue 4 (1995) initially specified these functions.
SEE ALSO
curs_bkgd(3X) describes the corresponding functions in the
no-wid-character configuration of
ncurses.
curses(3X),
curs_add_wch(3X),
curs_attr(3X)
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- bkgrnd, wbkgrnd
-
- bkgrndset, wbkgrndset
-
- getbkgrnd, wgetbkgrnd
-
- RETURN VALUE
-
- NOTES
-
- PORTABILITY
-
- HISTORY
-
- SEE ALSO
-
|
|
- Running on 
-
:
