Debian Codegraph @

upstream/opensuse-tumbleweed/man3/pad.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2025,2026 Thomas E. Dickey *
3 .\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
4 .\" *
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: *
12 .\" *
13 .\" The above copyright notice and this permission notice shall be included *
14 .\" in all copies or substantial portions of the Software. *
15 .\" *
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. *
23 .\" *
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 *
27 .\" authorization. *
28 .\"***************************************************************************
29 .\"
30 .\" $Id: curs_pad.3x,v 1.82 2026/04/18 22:53:21 tom Exp $
31 .TH pad 3NCURSES 2026-04-18 "ncurses 6.6" "Library calls"
32 .ie \n(.g \{\
33 .ds `` \(lq
34 .ds '' \(rq
35 .\}
36 .el \{\
37 .ie t .ds `` ``
38 .el .ds `` ""
39 .ie t .ds '' ''
40 .el .ds '' ""
41 .\}
42 .
43 .de bP
44 .ie n .IP \(bu 4
45 .el .IP \(bu 2
46 ..
47 .SH NAME
48 \fB\%newpad\fP,
49 \fB\%subpad\fP,
50 \fB\%prefresh\fP,
51 \fB\%pnoutrefresh\fP,
52 \fB\%pechochar\fP,
53 \fB\%pecho_wchar\fP \-
54 create and display \fIcurses\fR pads
55 .SH SYNOPSIS
56 .nf
57 \fB#include <ncursesw/curses.h>
58 .PP
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
62 .PP
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
67 .PP
68 \fBint pechochar(WINDOW *\fIpad\fB, chtype \fIch\fB);\fR
69 \fBint pecho_wchar(WINDOW *\fIpad\fB, const cchar_t *\fIwch\fB);\fR
70 .fi
71 .SH DESCRIPTION
72 A
73 .I curses
74 .I pad
75 is like a window,
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
81 operations.
82 .PP
83 Pads cannot be refreshed with \fB\%wrefresh\fP(3NCURSES);
84 use
85 .B \%prefresh
86 or
87 .B \%pnoutrefresh
88 instead.
89 .SS newpad
90 .B \%newpad
91 creates and returns a pointer to a new pad data structure
92 with the given number of lines,
93 .IR nlines ,
94 and columns,
95 .IR ncols .
96 .SS subpad
97 .B \%subpad
98 creates and returns a pointer to a subwindow within a pad
99 with the given number of lines,
100 .IR nlines ,
101 and columns,
102 .IR ncols .
103 Unlike \fB\%subwin\fP(3NCURSES),
104 which uses screen coordinates,
105 the new pad is placed at position
106 .RI ( begin_y ,
107 .IR begin_x )
108 relative to its parent.
109 Thus,
110 changes made to one pad can affect both.
111 When operating on a subpad,
112 it is often necessary to call \fB\%touchwin\fP(3NCURSES) or
113 \fB\%touchline\fP(3NCURSES) on
114 .I parent
115 before calling
116 .BR \%prefresh .
117 .SS "prefresh, pnoutrefresh"
118 .B \%prefresh
119 and
120 .B \%pnoutrefresh
121 are analogous to \fB\%wrefresh\fP(3NCURSES) and \fB\%wnoutrefresh\fP(3NCURSES)
122 except that they operate on pads rather than windows.
123 They require additional parameters are needed to indicate what portions
124 of the pad and screen are involved.
125 .bP
126 .I pminrow
127 and
128 .I pmincol
129 specify the upper left-hand corner of a rectangular view of the pad.
130 .bP
131 .IR sminrow ,
132 .IR smincol ,
133 .IR smaxrow ,
134 and
135 .I smaxcol
136 specify the vertices of the rectangle to be displayed on the screen.
137 .PP
138 The lower right-hand corner
139 of the rectangle to be displayed in the pad
140 is calculated from the screen coordinates,
141 since the rectangles must be the same size.
142 Both rectangles must be entirely contained
143 within their respective structures.
144 .I curses
145 treats
146 negative values of any of these parameters as zero.
147 .SS pechochar
148 .B \%pechochar
149 is functionally equivalent to calling \fB\%waddch\fP(3NCURSES) followed by
150 .BR \%prefresh .
151 It suggests to the
152 .I curses
153 optimizer that only a single character is being output;
154 a considerable performance benefit may be thus enjoyed.
155 The location of the character
156 .I ch
157 written to the pad is used to populate the arguments to
158 .BR \%prefresh .
159 .SS pecho_wchar
160 .B \%pecho_wchar
161 is functionally equivalent to calling \fB\%wadd_wch\fP(3NCURSES) followed by
162 .BR \%prefresh .
163 It suggests to the
164 .I curses
165 optimizer that only a single wide character is being output;
166 a considerable performance benefit may be thus enjoyed.
167 The location of the character
168 .I wch
169 written to the pad is used to populate the arguments to
170 .BR \%prefresh .
171 .SH RETURN VALUE
172 Functions that return an integer return
173 .B ERR
174 upon failure and
175 .B OK
176 upon successful completion.
177 .PP
178 Functions that return pointers return a null pointer on failure.
179 .PP
180 In this implementation
181 .RS 3
182 .TP 5
183 .BR prefresh\ and\ pnoutrefresh
184 return
185 .B ERR
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.
190 .TP 5
191 .B pechochar
192 returns
193 .B ERR
194 if the window is not really a pad,
195 and the associated call to
196 .B \%wechochar
197 returns
198 .BR ERR "."
199 .TP 5
200 .B pecho_wchar
201 returns
202 .B ERR
203 if the window is not really a pad,
204 and the associated call to
205 .B \%wecho_wchar
206 returns
207 .BR ERR "."
208 .RE
209 .SH NOTES
210 .B \%pechochar
211 may be implemented as a macro.
212 .PP
213 .I curses
214 documentation is traditionally averse to motivating the term
215 \*(``pad\*(''.
216 The Apollo Aegis workstation operating system
217 .RI ( circa
218 1981)
219 supported a graphical pad feature.
220 .bP
221 These graphical pads could be much larger than the computer's display.
222 .bP
223 The read-only output from a command could be scrolled back to inspect
224 and select text from the pad.
225 .PP
226 The two uses may be related.
227 .SH PORTABILITY
228 X/Open Curses Issue\ 4 describes these functions.
229 It specifies no error conditions for them.
230 .PP
231 SVr4 describes a successful return value only as
232 \*(``an integer value other than
233 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 524
234 .PP
235 The behavior of
236 .I \%subpad
237 if the parent window is not a pad is undocumented,
238 and is not checked by the vendor Unix implementations.
239 .bP
240 SVr4
241 .IR curses 's
242 .I \%newpad
243 sets a flag in the
244 .I \%WINDOW
245 structure indicating that the window is a pad.
246 .IP
247 However,
248 it uses this information only in
249 .I \%waddch
250 (to decide if it should call
251 .IR \%wrefresh ")"
252 and
253 .I \%wscrl
254 (to avoid scrolling a pad);
255 its
256 .I \%wrefresh
257 does not check it to ensure that a pad is properly updated.
258 .bP
259 Solaris
260 .I \%xcurses
261 checks whether a window is a pad in its
262 .IR \%wnoutrefresh ","
263 returning
264 .I ERR
265 in that case.
266 .IP
267 However,
268 it sets the flag on subwindows only if the parent window is a pad.
269 Its
270 .I \%newpad
271 does not set this information.
272 Consequently,
273 the check never fails.
274 .IP
275 It makes no comparable check in
276 .I \%pnoutrefresh
277 \(em though interestingly enough,
278 a comment in the source code states that the lack of a check
279 was an MKS extension.
280 .bP
281 NetBSD\ 7
282 .I curses
283 sets a flag in the
284 .I \%WINDOW
285 structure for
286 .I \%newpad
287 and
288 .IR \%subpad ","
289 aiding itself to distinguish between
290 .I \%wnoutrefresh
291 and
292 .IR \%pnoutrefresh "."
293 .IP
294 It does not check for the case where a subwindow is created in
295 a pad using
296 .I \%subwin
297 or
298 .IR \%derwin "."
299 .IP
300 Its
301 .I \%dupwin
302 returns a regular window when duplicating a pad.
303 Likewise,
304 its
305 .I \%getwin
306 always returns a window,
307 even if the saved data was from a pad.
308 .PP
309 .IR \%ncurses ":"
310 .bP
311 sets a flag in the
312 .I \%WINDOW
313 structure for
314 .I \%newpad
315 and
316 .IR \%subpad ","
317 .bP
318 allows a
319 .I \%subwin
320 or
321 .I \%derwin
322 call to succeed having a pad parent
323 by forcing the subwindow to be a pad,
324 .bP
325 checks in both
326 .I \%wnoutrefresh
327 and
328 .I \%pnoutrefresh
329 to ensure that pads and windows are handled distinctly,
330 and
331 .bP
332 ensures that
333 .I \%dupwin
334 and
335 .I \%getwin
336 treat pads versus windows consistently.
337 .SH HISTORY
338 SVr2 (1984) introduced
339 .IR \%newpad ","
340 .IR \%prefresh ","
341 and
342 .IR \%pnoutrefresh ","
343 documenting them in a single line each.
344 .PP
345 SVr3 (1987) added
346 .I \%subpad
347 and
348 .IR \%pechochar ","
349 and provided more extensive documentation.
350 .PP
351 The System\ V Interface Definition,
352 Version 4 (1995),
353 specified a function named
354 .IR \%pechowchar "."
355 This was a later addition to
356 .RI SVr4. x ,
357 not appearing in the first SVr4 (1989).
358 It differs from X/Open's later
359 .I \%pecho_wchar
360 in that its
361 .I wstr
362 parameter was a
363 .I \%chtype
364 instead of a
365 .IR \%wchar_t ","
366 and was not
367 .IR const "-qualified."
368 .SH SEE ALSO
369 \fB\%ncurses\fP(3NCURSES),
370 \fB\%addch\fP(3NCURSES),
371 \fB\%refresh\fP(3NCURSES),
372 \fB\%touch\fP(3NCURSES)