X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_bkgd.3x;h=f9199ce077bb6741303246b3c80482ee37b255bd;hp=356eff470819f81df2246c943d704377a90cc081;hb=80803f3a4a1fbdebb4de105cef9a10af36230f3c;hpb=9f479192e3ca3413d235c66bf058f8cc63764898 diff --git a/man/curs_bkgd.3x b/man/curs_bkgd.3x index 356eff47..f9199ce0 100644 --- a/man/curs_bkgd.3x +++ b/man/curs_bkgd.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2020,2021 Thomas E. Dickey * +.\" Copyright 2018-2021,2022 Thomas E. Dickey * .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,40 +27,43 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_bkgd.3x,v 1.32 2021/06/17 21:30:22 tom Exp $ +.\" $Id: curs_bkgd.3x,v 1.35 2022/06/25 21:55:45 tom Exp $ .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 .. .TH curs_bkgd 3X "" .SH NAME -\fBbkgdset\fR, \fBwbkgdset\fR, -\fBbkgd\fR, \fBwbkgd\fR, -\fBgetbkgd\fR \- \fBcurses\fR window background manipulation routines +\fBbkgdset\fP, \fBwbkgdset\fP, +\fBbkgd\fP, \fBwbkgd\fP, +\fBgetbkgd\fP \- \fBcurses\fP window background manipulation routines .SH SYNOPSIS -\fB#include \fR +\fB#include \fP .PP -\fBvoid bkgdset(chtype \fP\fIch\fP\fB);\fR +\fBvoid bkgdset(chtype \fIch\fB);\fR .br -\fBvoid wbkgdset(WINDOW *\fP\fIwin, chtype \fP\fIch\fP\fB);\fR +\fBvoid wbkgdset(WINDOW *\fIwin, chtype \fIch\fB);\fR .sp -\fBint bkgd(chtype \fP\fIch\fP\fB);\fR +\fBint bkgd(chtype \fIch\fB);\fR .br -\fBint wbkgd(WINDOW *\fP\fIwin\fP\fB, chtype \fP\fIch\fP\fB);\fR +\fBint wbkgd(WINDOW *\fIwin\fB, chtype \fIch\fB);\fR .sp -\fBchtype getbkgd(WINDOW *\fP\fIwin\fP\fB);\fR +\fBchtype getbkgd(WINDOW *\fIwin\fB);\fR .br .SH DESCRIPTION .SS bkgdset -The \fBbkgdset\fR and \fBwbkgdset\fR routines manipulate the -background of the named window. -The window background is a \fBchtype\fR consisting of -any combination of attributes (i.e., rendition) and a character. +The \fBbkgdset\fP and \fBwbkgdset\fP routines +set the \fIbackground\fP for a window. +A window's background is a \fBchtype\fP consisting of +any combination of attributes (i.e., rendition) and a character: +.bP The attribute part of the background is combined (OR'ed) with all non-blank -characters that are written into the window with \fBwaddch\fR. +characters that are written into the window with \fBwaddch\fP. +.bP Both the character and attribute parts of the background are combined with -the blank characters. -The background becomes a property of the +blank characters that are written into the window. +.PP +The background becomes a property of each character and moves with the character through any scrolling and insert/delete line/character operations. .PP @@ -69,7 +72,7 @@ the attribute part of the background is displayed as the graphic rendition of the character put on the screen. .SS bkgd .PP -The \fBbkgd\fR and \fBwbkgd\fR functions +The \fBbkgd\fP and \fBwbkgd\fP functions set the background property of the current or specified window and then apply this setting to every character position in that window. According to X/Open Curses, it should do this: @@ -94,6 +97,11 @@ For each cell in the window, whether or not it is blank: The library first compares the \fIcharacter\fP, and if it matches the current character part of the background, it replaces that with the new background character. +.IP +When \fBbkgdset\fP is used to set the background character, +that does not update each cell in the window. +A subsequent call to \fBbkgd\fP will only modify the \fIcharacter\fP in +cells which match the current background character. .bP The library then checks if the cell uses color, i.e., its color pair value is nonzero. @@ -114,27 +122,27 @@ the library updates only the non-color attributes, first removing those which may have come from the current background, and then adding attributes from the new background. .PP -If the background's character value is zero, a space is assumed. +If the background's character value is zero (0), a space is assumed. .PP If the terminal does not support color, or if color has not been started with \fBstart_color\fP, the new background character's color attribute will be ignored. .SS getbkgd .PP -The \fBgetbkgd\fR function returns the given window's current background +The \fBgetbkgd\fP function returns the given window's current background character/attribute pair. .SH RETURN VALUE .PP These functions are described in the XSI Curses standard, Issue 4. -It specifies that \fBbkgd\fR and \fBwbkgd\fR return \fBERR\fR on failure, +It specifies that \fBbkgd\fP and \fBwbkgd\fP return \fBERR\fP on failure, but gives no failure conditions. .PP -The routines \fBbkgd\fR and \fBwbkgd\fR return the integer \fBOK\fR, +The routines \fBbkgd\fP and \fBwbkgd\fP return the integer \fBOK\fP, unless the library has not been initialized. .PP In contrast, -the SVr4.0 manual says \fBbkgd\fR and \fBwbkgd\fR may return \fBOK\fP -"or a non-negative integer if \fBimmedok\fR is set", +the SVr4.0 manual says \fBbkgd\fP and \fBwbkgd\fP may return \fBOK\fP +"or a non-negative integer if \fBimmedok\fP is set", which refers to the return value from \fBwrefresh\fP (used to implement the immediate repainting). The SVr4 curses \fBwrefresh\fP returns the number of characters @@ -142,7 +150,7 @@ written to the screen during the refresh. This implementation does not do that. .SH NOTES .PP -Note that \fBbkgdset\fR and \fBbkgd\fR may be macros. +Note that \fBbkgdset\fP and \fBbkgd\fP may be macros. .PP X/Open Curses mentions that the character part of the background must be a single-byte value. @@ -155,7 +163,7 @@ These functions are described in the XSI Curses standard, Issue 4 .SH SEE ALSO .na .PP -\fBcurses\fR(3X), -\fBcurs_addch\fR(3X), -\fBcurs_attr\fR(3X), -\fBcurs_outopts\fR(3X) +\fBcurses\fP(3X), +\fBcurs_addch\fP(3X), +\fBcurs_attr\fP(3X), +\fBcurs_outopts\fP(3X)