X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_bkgd.3x;h=ec9fe3768be29ce889bc05ffb2a4c653d96fc57f;hb=75a9c36c205ebefe07580acd0b1053a2abbd44b9;hp=757186cf558bbc1964fd5ec501fa115468be901b;hpb=06078d3fa68db669ed37178c01873546b4b28745;p=ncurses.git diff --git a/man/curs_bkgd.3x b/man/curs_bkgd.3x index 757186cf..ec9fe376 100644 --- a/man/curs_bkgd.3x +++ b/man/curs_bkgd.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 1998-2015,2017 Free Software Foundation, Inc. * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * @@ -26,78 +27,199 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_bkgd.3x,v 1.25 2017/11/18 23:56:00 tom Exp $ +.\" $Id: curs_bkgd.3x,v 1.59 2024/03/23 19:58:58 tom Exp $ +.TH curs_bkgd 3X 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. .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 +\fB\%bkgdset\fP, +\fB\%wbkgdset\fP, +\fB\%bkgd\fP, +\fB\%wbkgd\fP, +\fB\%getbkgd\fP \- +manipulate background of a \fIcurses\fR window of characters .SH SYNOPSIS -\fB#include \fR -.PP -\fBvoid bkgdset(chtype \fP\fIch\fP\fB);\fR -.br -\fBvoid wbkgdset(WINDOW *\fP\fIwin, chtype \fP\fIch\fP\fB);\fR -.br -\fBint bkgd(chtype \fP\fIch\fP\fB);\fR -.br -\fBint wbkgd(WINDOW *\fP\fIwin\fP\fB, chtype \fP\fIch\fP\fB);\fR -.br -\fBchtype getbkgd(WINDOW *\fP\fIwin\fP\fB);\fR -.br +.nf +\fB#include +.PP +\fBint bkgd(chtype \fIch\fP); +\fBint wbkgd(WINDOW *\fIwin\fP, chtype \fIch\fP); +.PP +\fBvoid bkgdset(chtype \fIch\fP); +\fBvoid wbkgdset(WINDOW *\fIwin\fP, chtype \fIch\fP); +.PP +\fBchtype getbkgd(WINDOW *\fIwin\fP); +.fi .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 attribute part of the background is combined (OR'ed) with all non-blank -characters that are written into the window with \fBwaddch\fR. 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. -.PP -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. -.SS bkgd -.PP -The \fBbkgd\fR and \fBwbkgd\fR functions -set the background property of the current or specified window -and then apply this setting to every character position in that window: +The +.I background +of a +.I curses +window +(in the library's non-\*(``wide\*('' configuration) +is a +.I \%chtype +combining a set of attributes +(see \fB\%curs_attr\fP(3X)) +with a character called the +.I "blank character." +.PP +The blank character is a spacing character that populates a window's +character cells when their contents are erased without replacement. +The background's attributes are combined with all non-blank characters +written to the window, +as with the \fB\%waddch\fP(3X) and \fB\%winsch\fP(3X) families of +functions. .PP +The blank character and attributes of the background combine with +characters written to the window as described below. +The background becomes a property of the character and moves with it +through any scrolling and insert/delete line/character operations. +.PP +To the extent possible on a given terminal, +the attribute part of the background is displayed as the graphic +rendition of the character put on the screen. +.SS "bkgd, wbkgd" +\fB\%bkgd\fP and \fB\%wbkgd\fP set the background property of +\fB\%stdscr\fP or the specified window and then apply this setting to +every character cell in that window. .bP -The rendition of every character on the screen is changed to -the new background rendition. +The rendition of every character in the window changes to the new +background rendition. .bP -Wherever the former background character -appears, it is changed to the new background character. -.SS getbkgd +Wherever the former background character appears, +it changes to the new background character. +.PP +.I \%ncurses +updates the rendition of each character cell by comparing the character, +non-color attributes, +and colors. +The library applies to following procedure to each cell in the window, +whether or not it is blank. +.bP +.I \%ncurses +first compares the cell's character to the previously specified blank +character; +if they match, +.I \%ncurses +writes the new blank character to the cell. +.bP +.I \%ncurses +then checks if 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. +.bP +If the cell uses color, +and its background color matches that of the current window background, +.I \%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. +.bP +If the cell uses color, +and its background color does not match that of the current window +background, +.I \%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. +.PP +.I \%ncurses +treats a background character value of zero (0) as a blank character. .PP -The \fBgetbkgd\fR function returns the given window's current background -character/attribute pair. +If the terminal does not support color, +or if color has not been initialized with \fB\%start_color\fP(3X), +.I \%ncurses +ignores the new background character's color attribute. +.SS "bkgdset, wbkgdset" +\fB\%bkgdset\fP and \fB\%wbkgdset\fP manipulate the background of +the applicable window, +without updating the character cells as \fB\%bkgd\fP and +\fB\%wbkgd\fP do; +only future writes reflect the updated background. +.SS getbkgd +\fB\%getbkgd\fP obtains the given window's background character and +attribute combination. .SH RETURN VALUE +Functions returning an \fIint\fP return \fBOK\fP on success. +\fB\%bkgd\fP returns \fBERR\fP if the library has not been initialized. +\fB\%wbkgd\fP and \fB\%getbkgd\fP return \fBERR\fP if a \fI\%WINDOW\fP +pointer argument is null. +.PP +\fB\%bkgdset\fP and \fBwbkgdset\fP do not return a value. .PP -The routines \fBbkgd\fR and \fBwbkgd\fR return the integer \fBOK\fR. -The SVr4.0 manual says "or a non-negative integer if \fBimmedok\fR is set", -but this appears to be an error. +\fB\%getbkgd\fP returns a window's background character and attribute +combination. .SH NOTES +Unusually, +there is no \fB\%wgetbkgd\fP function; +\fB\%getbkgd\fP behaves as one would expect \fB\%wgetbkgd\fP to, +accepting a \fI\%WINDOW\fP pointer argument. .PP -Note that \fBbkgdset\fR and \fBbkgd\fR may be macros. +\fB\%bkgd\fP and +\fB\%bkgdset\fP +may be implemented as macros. +.PP +X/Open Curses mentions that the character part of the background must +be a single-byte value. +\fI\%ncurses\fP, +like SVr4 \fIcurses\fP, +checks to ensure that, +and will reuse the old background character if the check fails. .SH PORTABILITY +X/Open Curses, Issue 4, describes these functions. +It specifies that +\fB\%bkgd\fP, +\fB\%wbkgd\fP, +and +\fB\%getbkgd\fP +return \fBERR\fP on failure +(in the case of the last, +this value is cast to +.IR \%chtype ), +but describes no failure conditions. +.PP +The SVr4.0 manual says that \fB\%bkgd\fP and \fB\%wbkgd\fP may return +\fBOK\fP +\*(``or a non-negative integer if \fB\%immedok\fP is set\*('', +which refers to the return value from \fB\%wrefresh\fP(3X), +used to implement the immediate repainting. +SVr4 \fIcurses\fP's \fB\%wrefresh\fP returns the number of characters +written to the screen during the refresh. +\fI\%ncurses\fP does not do that. .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, -but gives no failure conditions. +Neither X/Open Curses nor the SVr4 manual pages detail how the rendition +of characters on the screen updates when \fB\%bkgd\fP or \fB\%wbkgd\fP +changes the background character. +.IR \%ncurses , +like SVr4 +.IR curses , +does not +(in its non-\*(``wide\*('' configuration) +store the background and window attribute contributions to each +character cell separately. .SH SEE ALSO -.na +\fB\%curs_bkgrnd\fP(3X) describes the corresponding functions in the +\*(``wide\*('' configuration of +.IR \%ncurses . .PP -\fBcurses\fR(3X), -\fBcurs_addch\fR(3X), -\fBcurs_attr\fR(3X), -\fBcurs_outopts\fR(3X) +\fB\%curses\fP(3X), +\fB\%curs_addch\fP(3X), +\fB\%curs_attr\fP(3X)