Debian Codegraph @

upstream/debian-trixie/man3/window.3ncurses

raw
1 .\"***************************************************************************
2 .\" Copyright 2020-2024,2025 Thomas E. Dickey *
3 .\" Copyright 1998-2015,2016 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_window.3x,v 1.66 2025/02/02 00:04:58 tom Exp $
31 .TH window 3NCURSES 2025-02-01 "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\%newwin\fP,
49 \fB\%delwin\fP,
50 \fB\%mvwin\fP,
51 \fB\%subwin\fP,
52 \fB\%derwin\fP,
53 \fB\%mvderwin\fP,
54 \fB\%dupwin\fP,
55 \fB\%wsyncup\fP,
56 \fB\%syncok\fP,
57 \fB\%wcursyncup\fP,
58 \fB\%wsyncdown\fP \-
59 create and manipulate \fIcurses\fR windows
60 .SH SYNOPSIS
61 .nf
62 \fB#include <curses.h>
63 .PP
64 \fBWINDOW * newwin(\fR
65 \fBint \fInlines\fP, int \fIncols\fP,
66 \fBint \fIbegin_y\fP, int \fIbegin_x\fP);
67 \fBint delwin(WINDOW * \fIwin\fP);
68 \fBint mvwin(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP);
69 \fBWINDOW * subwin(WINDOW * \fIorig\fP,
70 \fBint \fInlines\fP, int \fIncols\fP,
71 \fBint \fIbegin_y\fP, int \fIbegin_x\fP);
72 \fBWINDOW * derwin(WINDOW * \fIorig\fP,
73 \fBint \fInlines\fP, int \fIncols\fP,
74 \fBint \fIbegin_y\fP, int \fIbegin_x\fP);
75 \fBint mvderwin(WINDOW * \fIwin\fP, int \fIpar_y\fP, int \fIpar_x\fP);
76 \fBWINDOW * dupwin(WINDOW * \fIwin\fP);
77 \fBvoid wsyncup(WINDOW * \fIwin\fP);
78 \fBint syncok(WINDOW * \fIwin\fP, bool \fIbf\fP);
79 \fBvoid wcursyncup(WINDOW * \fIwin\fP);
80 \fBvoid wsyncdown(WINDOW * \fIwin\fP);
81 .fi
82 .SH DESCRIPTION
83 .SS newwin
84 Calling \fBnewwin\fP creates and returns a pointer to a new window with the
85 given number of lines and columns.
86 The upper left-hand corner of the window is
87 at
88 .RS
89 line \fIbegin\fR_\fIy\fP,
90 .br
91 column \fIbegin\fR_\fIx\fP
92 .RE
93 .PP
94 If either
95 \fInlines\fP or \fIncols\fP is zero, they default to
96 .RS
97 \fBLINES \-\fP \fIbegin\fR_\fIy\fP and
98 .br
99 \fBCOLS \-\fP \fIbegin\fR_\fIx\fP.
100 .RE
101 .PP
102 A new full-screen window is created by calling \fBnewwin(0,0,0,0)\fP.
103 .PP
104 Regardless of the function used for creating a new window
105 (e.g., \fBnewwin\fP, \fBsubwin\fP, \fBderwin\fP, \fBnewpad\fP),
106 rather than a duplicate (with \fBdupwin\fP),
107 all of the window modes are initialized to the default values.
108 These functions set window modes after a window is created:
109 .RS
110 .PP
111 \fB\%idcok\fP
112 \fB\%idlok\fP
113 \fB\%immedok\fP
114 \fB\%keypad\fP
115 \fB\%leaveok\fP
116 \fB\%nodelay\fP
117 \fB\%scrollok\fP
118 \fB\%setscrreg\fP
119 \fB\%syncok\fP
120 \fB\%wbkgdset\fP
121 \fB\%wbkgrndset\fP and
122 \fB\%wtimeout\fP.
123 .RE
124 .SS delwin
125 Calling \fBdelwin\fP deletes the named window, freeing all memory
126 associated with it (it does not actually erase the window's screen
127 image).
128 Subwindows must be deleted before the main window can be deleted.
129 .SS mvwin
130 Calling \fBmvwin\fP moves the window so that the upper left-hand
131 corner is at position (\fIx\fP, \fIy\fP).
132 If the move would cause the window to be off the screen,
133 it is an error and the window is not moved.
134 Moving subwindows is allowed, but should be avoided.
135 .SS subwin
136 Calling \fBsubwin\fP creates and returns a pointer to a new window
137 with the given number of lines, \fInlines\fP, and columns, \fIncols\fP.
138 The window is at position (\fIbegin\fR_\fIy\fP,
139 \fIbegin\fR_\fIx\fP) on the screen.
140 The subwindow shares memory with the window \fIorig\fP,
141 its \fIancestor\fP,
142 so that changes made to one window
143 will affect both windows.
144 When using this routine, it is necessary to call
145 \fBtouchwin\fP or \fBtouchline\fP on \fIorig\fP before calling
146 \fBwrefresh\fP on the subwindow.
147 .SS derwin
148 Calling \fBderwin\fP is the same as calling \fBsubwin,\fP except that
149 \fIbegin\fR_\fIy\fP and \fIbegin\fR_\fIx\fP are relative to the origin
150 of the window \fIorig\fP rather than the screen.
151 There is no difference between the subwindows and the derived windows.
152 .SS mvderwin
153 Calling \fBmvderwin\fP moves a derived window (or subwindow)
154 inside its parent window.
155 The screen-relative parameters of the window are not changed.
156 This routine is used to display different
157 parts of the parent window at the same physical position on the
158 screen.
159 .SS dupwin
160 Calling \fBdupwin\fP creates an exact duplicate of the window \fIwin\fP.
161 .SS wsyncup
162 Calling \fBwsyncup\fP touches all locations in ancestors of \fIwin\fP that are
163 changed in \fIwin\fP.
164 If \fBsyncok\fP is called with second argument
165 \fBTRUE\fP then \fBwsyncup\fP is called automatically whenever there is a
166 change in the window.
167 .SS wsyncdown
168 The \fBwsyncdown\fP routine touches each location in \fIwin\fP that has been
169 touched in any of its ancestor windows.
170 This routine is called by
171 \fBwrefresh\fP, so it should almost never be necessary to call it manually.
172 .SS wcursyncup
173 The routine \fBwcursyncup\fP updates the current cursor position of all the
174 ancestors of the window to reflect the current cursor position of the
175 window.
176 .SH RETURN VALUE
177 Functions that return integers return
178 .B ERR
179 upon failure and
180 .B OK
181 upon success.
182 .PP
183 Functions that return pointers return
184 .I NULL
185 on error.
186 .PP
187 .I \%ncurses
188 defines several error conditions.
189 .bP
190 .B \%delwin
191 returns
192 .B ERR
193 if
194 .I win
195 is a null pointer,
196 or if it is the parent of another window.
197 .IP
198 .I \%ncurses
199 maintains a list of windows,
200 and checks that the pointer passed to
201 .B \%delwin
202 is one that it created,
203 returning
204 .B ERR
205 if it was not.
206 .bP
207 .B \%derwin
208 returns
209 .B ERR
210 if
211 .I orig
212 is a null pointer,
213 or if any of the ordinate or dimension arguments is negative,
214 or if the resulting window does not fit inside the parent window.
215 .bP
216 .B \%dupwin
217 returns
218 .B ERR
219 if
220 .I win
221 is a null pointer.
222 .bP
223 .B \%mvderwin
224 returns
225 .B ERR
226 if
227 .I win
228 is a null pointer,
229 or if any part of the window would be placed off-screen.
230 .bP
231 .B \%mvwin
232 returns
233 .B ERR
234 if
235 .I win
236 is a null pointer,
237 if
238 .I win
239 is a pad,
240 or if any part of the window would be placed off-screen.
241 .bP
242 .B \%newwin
243 returns
244 .B ERR
245 if any of its arguments is negative.
246 .bP
247 .B \%subwin
248 returns
249 .B ERR
250 if
251 .I orig
252 is a null pointer,
253 or if any of the ordinate or dimension arguments is negative,
254 or if the resulting window does not fit inside the parent window.
255 .bP
256 .B \%syncok
257 returns
258 .B ERR
259 if
260 .I win
261 is a null pointer.
262 .PP
263 Functions that return a window pointer fail if memory allocation
264 for their data structures fails.
265 .PP
266 All of these functions fail if the screen has not been initialized;
267 see \fB\%initscr\fP(3NCURSES) or \fB\%newterm\fP(3NCURSES).
268 .SH NOTES
269 .B \%syncok
270 may be implemented as a macro.
271 .PP
272 Calling
273 .B \%syncup
274 on a window and making many small changes to it
275 could degrade performance.
276 .SH PORTABILITY
277 X/Open Curses Issue\ 4 describes these functions.
278 It specifies no error conditions for
279 .IR \%delwin ","
280 .IR \%derwin ","
281 .IR \%dupwin ","
282 .IR \%newwin ","
283 .IR \%mvderwin ","
284 or
285 .IR \%syncok "."
286 .PP
287 For functions returning integers
288 (except
289 .IR \%delwin "),"
290 SVr4 describes a successful return value only as
291 \*(``an integer value other than
292 .IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 544
293 .PP
294 Regarding
295 .IR \%delwin ","
296 X/Open Curses states that
297 .RS
298 .PP
299 [t]he application must delete subwindows before deleting the main
300 window.
301 .RE
302 .PP
303 If
304 .I \%delwin
305 is asked to delete a parent window,
306 it can succeed only if the
307 .I curses
308 library keeps a list of its subwindows.
309 SVr4
310 .I curses
311 kept a count of the number of subwindows rather than a list.
312 It simply returned
313 .B ERR
314 when asked to delete a subwindow.
315 Solaris X/Open
316 .I curses
317 .RI \%( xcurses )
318 does not make even that check,
319 and will delete a parent window that still has subwindows.
320 .I \%PDCurses
321 also behaves this way.
322 .PP
323 .I \%ncurses
324 4.0 (1996) and later maintains a list of windows for each screen
325 to ensure that a window has no subwindows before allowing its deletion.
326 NetBSD
327 .I curses
328 has followed suit since 2003.
329 .PP
330 SVr4
331 .I curses
332 documentation is unclear about what
333 .I \%wsyncup
334 and
335 .I \%wsyncdown
336 actually do.
337 It seems to imply that they are supposed to touch only those lines that
338 are affected by changes to a window's ancestors.
339 The description and behavior of these functions in
340 .I \%ncurses
341 is patterned on the X/Open Curses standard;
342 this approach may result in slower updates.
343 .SH SEE ALSO
344 \fB\%ncurses\fP(3NCURSES),
345 \fB\%initscr\fP(3NCURSES),
346 \fB\%refresh\fP(3NCURSES),
347 \fB\%touch\fP(3NCURSES),
348 \fB\%curses_variables\fP(3NCURSES)