curs_bkgrnd(3) | Library calls | curs_bkgrnd(3)

# NAME

bkgrnd, wbkgrnd, bkgrndset, wbkgrndset, getbkgrnd, wgetbkgrnd - curses window complex background manipulation routines

# 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

## bkgrndset

The bkgrndset and wbkgrndset routines manipulate the background of the named window. The window background is a cchar_t consisting of any combination of attributes (i.e., rendition) and a complex character.

- The attribute part of the background is combined (OR'ed) with all non-blank characters that are written into the window with waddch.
- Both the character and attribute parts of the background are combined with the blank characters.

The background becomes a property of the character and moves with the character through any scrolling and insert/delete line/character operations.

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.

## bkgrnd

The bkgrnd and wbkgrnd functions set the background property of the current or specified window and then apply this setting to every character position in that window:

- The rendition of every character on the screen is changed to the new background rendition.
- Wherever the former background character appears, it is changed to the new background character.

## getbkgrnd

The getbkgrnd function returns the given window's current background character/attribute pair via the wch pointer. If the given window pointer is null, the character is not updated (but no error returned).

# NOTES

Note that bkgrnd, bkgrndset, and getbkgrnd may be macros.

X/Open Curses does not provide details on how the rendition is changed. This implementation follows the approach used in SVr4 curses, which is explained in the manual page for wbkgd.

# RETURN VALUE

The bkgrndset and wbkgrndset routines do not return a value.

Upon successful completion, the other functions return OK. Otherwise, they return ERR:

- A null window pointer is treated as an error.
- A null character pointer is treated as an error.

# PORTABILITY

These functions are described in the XSI Curses standard, Issue 4 (X/Open Curses).

# SEE ALSO

curses(3), curs_bkgd(3)

2023-08-12 | ncurses 6.4