1 .\"***************************************************************************
2 .\" Copyright 2018-2023,2024 Thomas E. Dickey *
3 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
5 .\" Permission is hereby granted, free of charge, to any person obtaining a *
6 .\" copy of this software and associated documentation files (the *
7 .\" "Software"), to deal in the Software without restriction, including *
8 .\" without limitation the rights to use, copy, modify, merge, publish, *
9 .\" distribute, distribute with modifications, sublicense, and/or sell *
10 .\" copies of the Software, and to permit persons to whom the Software is *
11 .\" furnished to do so, subject to the following conditions: *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 .\" Except as contained in this notice, the name(s) of the above copyright *
25 .\" holders shall not be used in advertising or otherwise to promote the *
26 .\" sale, use or other dealings in this Software without prior written *
28 .\"***************************************************************************
30 .\" $Id: curs_pad.3x,v 1.59 2024/04/20 21:20:07 tom Exp $
31 .TH curs_pad 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
53 \fB\%pecho_wchar\fP \-
54 create and display \fIcurses\fR pads
57 \fB#include <curses.h>
59 \fBWINDOW *newpad(int \fInlines\fP, int \fIncols\fP);
60 \fBWINDOW *subpad(WINDOW *\fIparent\fP, int \fInlines\fP, int \fIncols\fP,
61 \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
63 \fBint prefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
64 \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR
65 \fBint pnoutrefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
66 \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR
68 \fBint pechochar(WINDOW *\fIpad\fB, chtype \fIch\fB);\fR
69 \fBint pecho_wchar(WINDOW *\fIpad\fB, const cchar_t *\fIwch\fB);\fR
76 except that it is not restricted by the screen size,
77 and is not necessarily associated with a particular part of the screen.
78 Pads can be used when a large window is needed,
79 only part of which is to be visible on the screen.
80 Pads are not automatically refreshed by scrolling or input-echoing
83 Pads cannot be refreshed with \fB\%wrefresh\fP(3X);
90 \fB\%newpad\fP creates and returns a pointer to a new pad data structure
91 with the given number of lines,
97 creates and returns a pointer to a subwindow within a pad
98 with the given number of lines,
102 Unlike \fB\%subwin\fP(3X),
103 which uses screen coordinates,
104 the new pad is placed at position
107 relative to its parent.
109 changes made to one pad can affect both.
110 When operating on a subpad,
111 it is often necessary to call \fB\%touchwin\fP(3X) or
112 \fB\%touchline\fP(3X) on
116 .SS "prefresh, pnoutrefresh"
120 are analogous to \fB\%wrefresh\fP(3X) and \fB\%wnoutrefresh\fP(3X)
121 except that they operate on pads rather than windows.
122 They require additional parameters are needed to indicate what portions
123 of the pad and screen are involved.
128 specify the upper left-hand corner of a rectanglar view of the pad.
135 specify the vertices of the rectangle to be displayed on the screen.
137 The lower right-hand corner
138 of the rectangle to be displayed in the pad
139 is calculated from the screen coordinates,
140 since the rectangles must be the same size.
141 Both rectangles must be entirely contained
142 within their respective structures.
145 negative values of any of these parameters as zero.
148 is functionally equivalent to calling \fB\%waddch\fP(3X) followed by
152 optimizer that only a single character is being output;
153 a considerable performance benefit may be thus enjoyed.
154 The location of the character
156 written to the pad is used to populate the arguments to
160 is functionally equivalent to calling \fB\%wadd_wch\fP(3X) followed by
164 optimizer that only a single wide character is being output;
165 a considerable performance benefit may be thus enjoyed.
166 The location of the character
168 written to the pad is used to populate the arguments to
171 Functions that return an integer return \fBERR\fP upon failure and
174 \*(``an integer value other than \fBERR\fP\*('')
175 upon successful completion.
177 Functions that return pointers return \fBNULL\fP on error,
178 and set \fB\%errno\fP to \fB\%ENOMEM\fP.
180 X/Open Curses does not specify any error conditions.
181 In this implementation
184 \fB\%prefresh\fP and \fB\%pnoutrefresh\fP
186 if the window pointer is null, or
187 if the window is not really a pad or
188 if the area to refresh extends off-screen or
189 if the minimum coordinates are greater than the maximum.
193 if the window is not really a pad, and the associated call
194 to \fB\%wechochar\fP returns an error.
198 if the window is not really a pad, and the associated call
199 to \fB\%wecho_wchar\fP returns an error.
202 \fB\%pechochar\fP may be a macro.
204 BSD \fIcurses\fP has no \fIpad\fP feature.
206 SVr2 \fIcurses\fP (1986) provided the \fB\%newpad\fP and related functions,
207 documenting them in a single line each.
208 SVr3 (1987) provided more extensive documentation.
210 The documentation does not explain the term \fIpad\fP.
211 However, the Apollo \fIAegis\fP workstation operating system
212 supported a graphical \fIpad\fP feature:
214 These graphical pads could be much larger than the computer's display.
216 The read-only output from a command could be scrolled back to inspect,
217 and select text from the pad.
219 The two uses may be related.
221 X/Open Curses, Issue 4 describes these functions,
222 without significant change from the SVr3 documentation.
223 It describes no error conditions.
224 The behavior of \fB\%subpad\fP if the parent window is not
225 a pad is undocumented,
226 and is not checked by the vendor Unix implementations:
228 SVr4 \fIcurses\fP sets a flag in the \fI\%WINDOW\fP structure in
229 \fB\%newpad\fP which tells if the window is a \fIpad\fP.
231 However, it uses this information only in
232 \fB\%waddch\fP (to decide if it should call \fB\%wrefresh\fP) and
233 \fB\%wscrl\fP (to avoid scrolling a pad),
234 and does not check in \fB\%wrefresh\fP to ensure that the pad
235 is refreshed properly.
237 Solaris \fI\%xcurses\fP checks whether a window is a pad in
238 \fB\%wnoutrefresh\fP,
239 returning \fBERR\fP in that case.
242 it only sets the flag for subwindows if the parent window is a pad.
243 Its \fB\%newpad\fP function does not set this information.
244 Consequently, the check will never fail.
246 It makes no comparable check in \fB\%pnoutrefresh\fP,
247 though interestingly enough, a comment in the source code
248 states that the lack of a check was an MKS extension.
250 NetBSD 7 \fIcurses\fP
251 sets a flag in the \fI\%WINDOW\fP structure
252 for \fB\%newpad\fP and \fB\%subpad\fP,
253 using this to help with the distinction between \fB\%wnoutrefresh\fP
254 and \fB\%pnoutrefresh\fP.
256 It does not check for the case where a subwindow is created in
257 a pad using \fB\%subwin\fP or \fB\%derwin\fP.
259 The \fB\%dupwin\fP function returns a regular window when duplicating a pad.
260 Likewise, \fB\%getwin\fP always returns a window, even if the saved
265 sets a flag in the \fI\%WINDOW\fP structure
266 for \fB\%newpad\fP and \fB\%subpad\fP,
268 allows a \fB\%subwin\fP or \fB\%derwin\fP call to succeed having a pad parent by
269 forcing the subwindow to be a pad,
271 checks in both \fB\%wnoutrefresh\fP and \fB\%pnoutrefresh\fP to ensure
272 that pads and windows are handled distinctly, and
274 ensures that \fB\%dupwin\fP and \fB\%getwin\fP treat
275 pads versus windows consistently.
278 \fB\%curs_addch\fP(3X),
279 \fB\%curs_refresh\fP(3X),
280 \fB\%curs_touch\fP(3X)