Debian Codegraph @

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