diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man3/pad.3ncurses')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man3/pad.3ncurses | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/pad.3ncurses b/upstream/opensuse-tumbleweed/man3/pad.3ncurses new file mode 100644 index 00000000..58ba43e2 --- /dev/null +++ b/upstream/opensuse-tumbleweed/man3/pad.3ncurses @@ -0,0 +1,252 @@ +.\"*************************************************************************** +.\" 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 * +.\" "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_pad.3x,v 1.53 2024/01/05 21:46:58 tom Exp $ +.TH pad 3NCURSES 2024-01-05 "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\%newpad\fP, +\fB\%subpad\fP, +\fB\%prefresh\fP, +\fB\%pnoutrefresh\fP, +\fB\%pechochar\fP, +\fB\%pecho_wchar\fP \- +create and display \fIcurses\fR pads +.SH SYNOPSIS +.nf +\fB#include <ncursesw/curses.h> +.PP +\fBWINDOW *newpad(int \fInlines\fP, int \fIncols\fP); +\fBWINDOW *subpad(WINDOW *\fIorig\fP, int \fInlines\fP, int \fIncols\fP, + \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR +\fBint prefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR + \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR +\fBint pnoutrefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR + \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR +\fBint pechochar(WINDOW *\fIpad\fB, chtype \fIch\fB);\fR +\fBint pecho_wchar(WINDOW *\fIpad\fB, const cchar_t *\fIwch\fB);\fR +.fi +.SH DESCRIPTION +.SS newpad +\fB\%newpad\fP creates and returns a pointer to a new pad data structure +with the given number of lines, +\fInlines\fP, +and columns, +\fIncols\fP. +A pad is like a window, +except that it is not restricted by the screen size, +and is not necessarily associated with a particular part of the screen. +Pads can be used when a large window is needed, +and only a part of the window will be on the screen at one time. +Automatic refreshes of pads +(as from scrolling or echoing of input) +do not occur. +.PP +It is not valid to call \fB\%wrefresh\fP with a \fIpad\fP argument; +call \fB\%prefresh\fP or \fB\%pnoutrefresh\fP instead. +They require additional parameters to specify the part of the pad to be +displayed and the location on the screen to be used for the display. +.SS subpad +The \fB\%subpad\fP routine creates and returns a pointer to a subwindow within a +pad with the given number of lines, \fInlines\fP, and columns, \fIncols\fP. +Unlike \fB\%subwin\fP, which uses screen coordinates, the window is at position +(\fIbegin\fR_\fIx\fB,\fR \fIbegin\fR_\fIy\fR) on the pad. +The window is +made in the middle of the window \fIorig\fP, so that changes made to one window +affect both windows. +During the use of this routine, it will often be +necessary to call \fB\%touchwin\fP or \fB\%touchline\fP on \fIorig\fP before +calling \fB\%prefresh\fP. +.SS "prefresh, pnoutrefresh" +The \fB\%prefresh\fP and \fB\%pnoutrefresh\fP routines are analogous to +\fB\%wrefresh\fP and \fB\%wnoutrefresh\fP except that they relate to pads instead +of windows. +The additional parameters are needed to indicate what part of the +pad and screen are involved. +.bP +The \fIpminrow\fP and \fIpmincol\fP parameters specify the upper +left-hand corner of the rectangle to be displayed in the pad. +.bP +The \fIsminrow\fP, +\fIsmincol\fP, \fIsmaxrow\fP, and \fIsmaxcol\fP +parameters specify the edges of the +rectangle to be displayed on the screen. +.PP +The lower right-hand corner of the +rectangle to be displayed in the pad is calculated from the screen coordinates, +since the rectangles must be the same size. +Both rectangles must be entirely +contained within their respective structures. +Negative values of +\fIpminrow\fP, \fIpmincol\fP, \fIsminrow\fP, or \fIsmincol\fP are treated as if +they were zero. +.SS pechochar +The \fB\%pechochar\fP routine is functionally equivalent +to a call to \fB\%addch\fP +followed by a call to \fB\%refresh\fP(3NCURSES), +a call to \fB\%waddch\fP followed by a call +to \fB\%wrefresh\fP, or a call to \fB\%waddch\fP followed by a call to +\fB\%prefresh\fP. +The knowledge that only a single character is being output is +taken into consideration and, for non-control characters, a considerable +performance gain might be seen by using these routines instead of their +equivalents. +In the case of \fB\%pechochar\fP, the last location of the pad on +the screen is reused for the arguments to \fB\%prefresh\fP. +.SS pecho_wchar +The \fB\%pecho_wchar\fP function is the analogous wide-character +form of \fB\%pechochar\fP. +It outputs one character to a pad and immediately refreshes the pad. +It does this by a call to \fB\%wadd_wch\fP followed by a call +to \fB\%prefresh\fP. +.SH RETURN VALUE +Functions that return an integer return \fBERR\fP upon failure and +\fBOK\fP +(SVr4 specifies only +\*(``an integer value other than \fBERR\fP\*('') +upon successful completion. +.PP +Functions that return pointers return \fBNULL\fP on error, +and set \fB\%errno\fP to \fB\%ENOMEM\fP. +.PP +X/Open Curses does not define any error conditions. +In this implementation +.RS 3 +.TP 5 +\fB\%prefresh\fP and \fB\%pnoutrefresh\fP +return an error +if the window pointer is null, or +if the window is not really a pad or +if the area to refresh extends off-screen or +if the minimum coordinates are greater than the maximum. +.TP 5 +\fBpechochar\fP +returns an error +if the window is not really a pad, and the associated call +to \fB\%wechochar\fP returns an error. +.TP 5 +\fBpecho_wchar\fP +returns an error +if the window is not really a pad, and the associated call +to \fB\%wecho_wchar\fP returns an error. +.RE +.SH NOTES +\fB\%pechochar\fP may be a macro. +.SH PORTABILITY +BSD \fIcurses\fP has no \fIpad\fP feature. +.PP +SVr2 \fIcurses\fP (1986) provided the \fB\%newpad\fP and related functions, +documenting them in a single line each. +SVr3 (1987) provided more extensive documentation. +.PP +The documentation does not explain the term \fIpad\fP. +However, the Apollo \fIAegis\fP workstation operating system +supported a graphical \fIpad\fP feature: +.bP +These graphical pads could be much larger than the computer's display. +.bP +The read-only output from a command could be scrolled back to inspect, +and select text from the pad. +.PP +The two uses may be related. +.PP +The XSI Curses standard, Issue 4 describes these functions, +without significant change from the SVr3 documentation. +It describes no error conditions. +The behavior of \fB\%subpad\fP if the parent window is not +a pad is undocumented, +and is not checked by the vendor Unix implementations: +.bP +SVr4 \fIcurses\fP sets a flag in the \fI\%WINDOW\fP structure in +\fB\%newpad\fP which tells if the window is a \fIpad\fP. +.IP +However, it uses this information only in +\fB\%waddch\fP (to decide if it should call \fB\%wrefresh\fP) and +\fB\%wscrl\fP (to avoid scrolling a pad), +and does not check in \fB\%wrefresh\fP to ensure that the pad +is refreshed properly. +.bP +Solaris \fI\%xcurses\fP checks whether a window is a pad in +\fB\%wnoutrefresh\fP, +returning \fBERR\fP in that case. +.IP +However, +it only sets the flag for subwindows if the parent window is a pad. +Its \fB\%newpad\fP function does not set this information. +Consequently, the check will never fail. +.IP +It makes no comparable check in \fB\%pnoutrefresh\fP, +though interestingly enough, a comment in the source code +states that the lack of a check was an MKS extension. +.bP +NetBSD 7 \fIcurses\fP +sets a flag in the \fI\%WINDOW\fP structure +for \fB\%newpad\fP and \fB\%subpad\fP, +using this to help with the distinction between \fB\%wnoutrefresh\fP +and \fB\%pnoutrefresh\fP. +.IP +It does not check for the case where a subwindow is created in +a pad using \fB\%subwin\fP or \fB\%derwin\fP. +.IP +The \fB\%dupwin\fP function returns a regular window when duplicating a pad. +Likewise, \fB\%getwin\fP always returns a window, even if the saved +data was from a pad. +.PP +This implementation +.bP +sets a flag in the \fI\%WINDOW\fP structure +for \fB\%newpad\fP and \fB\%subpad\fP, +.bP +allows a \fB\%subwin\fP or \fB\%derwin\fP call to succeed having a pad parent by +forcing the subwindow to be a pad, +.bP +checks in both \fB\%wnoutrefresh\fP and \fB\%pnoutrefresh\fP to ensure +that pads and windows are handled distinctly, and +.bP +ensures that \fB\%dupwin\fP and \fB\%getwin\fP treat +pads versus windows consistently. +.SH SEE ALSO +\fB\%ncurses\fP(3NCURSES), +\fB\%addch\fP(3NCURSES), +\fB\%refresh\fP(3NCURSES), +\fB\%touch\fP(3NCURSES) |