bkgrnd(3XC)

NAME

bkgrnd, bkgrndset, getbkgrnd, wbkgrnd, wbkgrndset, wgetbkgrnd − set or get the background character (and rendition) of window using a complex character

SYNOPSIS

#include <curses.h>

int bkgrnd(const cchar_t ∗wch);

void bkgrndset(const cchar_t ∗wch);

int getbkgrnd(cchar_t ∗wch);

int wbkgrnd(WINDOW ∗win, const cchar_t ∗wch);

void wbkgrndset(WINDOW ∗win, const cchar_t ∗wch);

int wgetbkgrnd(WINDOW ∗win, cchar_t ∗wch);

ARGUMENTS

wchIs a pointer to the complex background character to be set.

winIs a pointer to the window in which the complex background character is to be set.

DESCRIPTION

All characters except space are part of the foreground. The character and its attributes make up a character/rendition pair defined as a chtype. The character is any single-byte value; the attribute consists of highlighting attributes that affect the appearance of the character on the screen (for example, bold, underline, color).

If wch is a multicolumn character that cannot fit on the window line, these functions return ERR.

The bkgrndset() function sets the current background character and rendition for the stdscr window. wbkgdset() sets the current background character and rendition for window win. You must specify the complete character/rendition pair; for example:

bkgrndset(A_BOLD|COLOR_PAIR(1)|‘ ’);

sets the background rendition to bold with color and the background character to a space. The default background character/rendition pair is

bkgrndset(A_NORMAL|COLOR_PAIR(0)|‘ ’);

The current background character and rendition are written to the window by the clear(3XC), erase(3XC), clrtoeol(3XC), and clrtobot(3XC) sets of functions as well as any other functions that insert blanks. If a background character is not supplied (that is, only a rendition is given), results are undefined.

The bkgrnd() and wbkgrnd() functions update the entire window (stdscr and win, respectively) with the supplied background and perform a wbkgrndset().

When calling the bkgrnd(), bkgrndset(), wbkgrnd(), or wbkgrndset() function, if wch is a complex non-spacing character, it is added to the existing complex background character.

The getbkgrnd() and wgetbkgrnd() functions retrieve the value of the window’s background character (with rendition) and store it in the area pointed to by wch.

RETURN VALUES

The bkgrndset() and wbkgrndset() functions do not return a value.

On success, the other functions return OK. Otherwise, they return ERR.

ERRORS

None.

Museum

Related Articles