Debian Codegraph @

upstream/debian-unstable/man3/pad.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2018-2024,2025 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.81 2025/08/23 22:50:00 tom Exp $
31 .TH pad 3NCURSES 2025-08-23 "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 <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 and set
180 .I \%errno
181 to
182 .BR \%ENOMEM "."
183 .PP
184 In this implementation
185 .RS 3
186 .TP 5
187 .BR prefresh\ and\ pnoutrefresh
188 return
189 .B ERR
190 if the window pointer is null, or
191 if the window is not really a pad or
192 if the area to refresh extends off-screen or
193 if the minimum coordinates are greater than the maximum.
194 .TP 5
195 .B pechochar
196 returns
197 .B ERR
198 if the window is not really a pad,
199 and the associated call to
200 .B \%wechochar
201 returns
202 .BR ERR "."
203 .TP 5
204 .B pecho_wchar
205 returns
206 .B ERR
207 if the window is not really a pad,
208 and the associated call to
209 .B \%wecho_wchar
210 returns
211 .BR ERR "."
212 .RE
213 .SH NOTES
214 .B \%pechochar
215 may be implemented as a macro.
216 .PP
217 .I curses
218 documentation is traditionally averse to motivating the term
219 \*(``pad\*(''.
220 The Apollo Aegis workstation operating system
221 .RI ( circa
222 1981)
223 supported a graphical pad feature.
224 .bP
225 These graphical pads could be much larger than the computer's display.
226 .bP
227 The read-only output from a command could be scrolled back to inspect
228 and select text from the pad.
229 .PP
230 The two uses may be related.
231 .SH PORTABILITY
232 X/Open Curses Issue\ 4 describes these functions.
233 It specifies no error conditions for them.
234 .PP
235 SVr4 describes a successful return value only as
236 \*(``an integer value other than
237 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 524
238 .PP
239 The behavior of
240 .I \%subpad
241 if the parent window is not a pad is undocumented,
242 and is not checked by the vendor Unix implementations.
243 .bP
244 SVr4
245 .IR curses 's
246 .I \%newpad
247 sets a flag in the
248 .I \%WINDOW
249 structure indicating that the window is a pad.
250 .IP
251 However,
252 it uses this information only in
253 .I \%waddch
254 (to decide if it should call
255 .IR \%wrefresh ")"
256 and
257 .I \%wscrl
258 (to avoid scrolling a pad);
259 its
260 .I \%wrefresh
261 does not check it to ensure that a pad is properly updated.
262 .bP
263 Solaris
264 .I \%xcurses
265 checks whether a window is a pad in its
266 .IR \%wnoutrefresh ","
267 returning
268 .I ERR
269 in that case.
270 .IP
271 However,
272 it sets the flag on subwindows only if the parent window is a pad.
273 Its
274 .I \%newpad
275 does not set this information.
276 Consequently,
277 the check never fails.
278 .IP
279 It makes no comparable check in
280 .I \%pnoutrefresh
281 \(em though interestingly enough,
282 a comment in the source code states that the lack of a check
283 was an MKS extension.
284 .bP
285 NetBSD\ 7
286 .I curses
287 sets a flag in the
288 .I \%WINDOW
289 structure for
290 .I \%newpad
291 and
292 .IR \%subpad ","
293 aiding itself to distinguish between
294 .I \%wnoutrefresh
295 and
296 .IR \%pnoutrefresh "."
297 .IP
298 It does not check for the case where a subwindow is created in
299 a pad using
300 .I \%subwin
301 or
302 .IR \%derwin "."
303 .IP
304 Its
305 .I \%dupwin
306 returns a regular window when duplicating a pad.
307 Likewise,
308 its
309 .I \%getwin
310 always returns a window,
311 even if the saved data was from a pad.
312 .PP
313 .IR \%ncurses ":"
314 .bP
315 sets a flag in the
316 .I \%WINDOW
317 structure for
318 .I \%newpad
319 and
320 .IR \%subpad ","
321 .bP
322 allows a
323 .I \%subwin
324 or
325 .I \%derwin
326 call to succeed having a pad parent
327 by forcing the subwindow to be a pad,
328 .bP
329 checks in both
330 .I \%wnoutrefresh
331 and
332 .I \%pnoutrefresh
333 to ensure that pads and windows are handled distinctly,
334 and
335 .bP
336 ensures that
337 .I \%dupwin
338 and
339 .I \%getwin
340 treat pads versus windows consistently.
341 .SH HISTORY
342 SVr2 (1984) introduced
343 .IR \%newpad ","
344 .IR \%prefresh ","
345 and
346 .IR \%pnoutrefresh ","
347 documenting them in a single line each.
348 .PP
349 SVr3 (1987) added
350 .I \%subpad
351 and
352 .IR \%pechochar ","
353 and provided more extensive documentation.
354 .PP
355 The System\ V Interface Definition,
356 Version 4 (1995),
357 specified a function named
358 .IR \%pechowchar "."
359 This was a later addition to
360 .RI SVr4. x ,
361 not appearing in the first SVr4 (1989).
362 It differs from X/Open's later
363 .I \%pecho_wchar
364 in that its
365 .I wstr
366 parameter was a
367 .I \%chtype
368 instead of a
369 .IR \%wchar_t ","
370 and was not
371 .IR const "-qualified."
372 .SH SEE ALSO
373 \fB\%ncurses\fP(3NCURSES),
374 \fB\%addch\fP(3NCURSES),
375 \fB\%refresh\fP(3NCURSES),
376 \fB\%touch\fP(3NCURSES)