From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/opensuse-tumbleweed/man3/bkgrnd.3ncurses | 215 ++++++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 upstream/opensuse-tumbleweed/man3/bkgrnd.3ncurses (limited to 'upstream/opensuse-tumbleweed/man3/bkgrnd.3ncurses') diff --git a/upstream/opensuse-tumbleweed/man3/bkgrnd.3ncurses b/upstream/opensuse-tumbleweed/man3/bkgrnd.3ncurses new file mode 100644 index 00000000..f344d51c --- /dev/null +++ b/upstream/opensuse-tumbleweed/man3/bkgrnd.3ncurses @@ -0,0 +1,215 @@ +.\"*************************************************************************** +.\" Copyright 2018-2022,2023 Thomas E. Dickey * +.\" Copyright 2002-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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_bkgrnd.3x,v 1.36 2023/12/23 16:35:10 tom Exp $ +.TH bkgrnd 3NCURSES 2023-12-23 "ncurses 6.4" "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 +.. +.SH NAME +\fB\%bkgrnd\fP, +\fB\%wbkgrnd\fP, +\fB\%bkgrndset\fP, +\fB\%wbkgrndset\fP, +\fB\%getbkgrnd\fP, +\fB\%wgetbkgrnd\fP \- +manipulate background of a \fIcurses\fP window of wide characters +.SH SYNOPSIS +.nf +\fB#include +.PP +\fBint bkgrnd(const cchar_t *\fIwch\fP); +\fBint wbkgrnd(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP); +.PP +\fBvoid bkgrndset(const cchar_t *\fIwch\fP); +\fBvoid wbkgrndset(WINDOW *\fIwin\fP, const cchar_t *\fIwch\fP); +.PP +\fBint getbkgrnd(cchar_t *\fIwch\fP); +\fBint wgetbkgrnd(WINDOW *\fIwin\fP, cchar_t *\fIwch\fP); +.fi +.SH DESCRIPTION +The +.I background +of a +.I curses +window +(in the library's \*(``wide\*('' configuration) +is a +.I \%cchar_t +combining a set of attributes +(see \fB\%attr\fP(3NCURSES)) +with a complex 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\%wadd_wch\fP(3NCURSES) and \fB\%wins_wch\fP(3NCURSES) 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 "bkgrnd, wbkgrnd" +\fB\%bkgrnd\fP and \fB\%wbkgrnd\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 in the window changes to the new +background rendition. +.bP +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 +If the terminal does not support color, +or if color has not been initialized with \fB\%start_color\fP(3NCURSES), +.I \%ncurses +ignores the new background character's color attribute. +.SS "bkgrndset, wbkgrndset" +\fB\%bkgrndset\fP and \fB\%wbkgrndset\fP manipulate the background of +the applicable window, +without updating the character cells as \fB\%bkgrnd\fP and +\fB\%wbkgrnd\fP do; +only future writes reflect the updated background. +.SS "getbkgrnd, wgetbkgrnd" +The \fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP functions obtain the +background character and attribute pair of \fB\%stdscr\fP or the +specified window and store it via the +.I wch +pointer. +.SH RETURN VALUE +\fBbkgrndset\fP and \fBwbkgrndset\fP do not return a value. +.PP +The other functions return +.B ERR +upon failure and +.B OK +upon success. +In +.I \%ncurses, +failure occurs if +.bP +a +.I \%WINDOW +pointer +.I win +is null, or +.bP +a +.I \%cchar_t +pointer +.I wch +is null. +.SH NOTES +\fB\%bkgrnd\fP, +\fB\%bkgrndset\fP, and +\fB\%getbkgrnd\fP +may be implemented as macros. +.PP +Unlike their counterparts in the non-\*(``wide\*('' configuration of +.I \%ncurses, +\fB\%getbkgrnd\fP and \fB\%wgetbkgrnd\fP supply the background character +and attribute in a modifiable +.I \%cchar_t +parameter, +not as the return value. +.SH PORTABILITY +X/Open Curses, Issue 4, describes these functions. +It specifies no error conditions for them. +.PP +X/Open Curses does not provide details of how the rendition is updated. +This implementation follows the approach used in SVr4 +.I curses. +.SH SEE ALSO +\fB\%bkgd\fP(3NCURSES) describes the corresponding functions in the +non-\*(``wide\*('' configuration of +.I \%ncurses. +.PP +\fB\%ncurses\fP(3NCURSES), +\fB\%add_wch\fP(3NCURSES), +\fB\%attr\fP(3NCURSES) -- cgit v1.2.3