Debian Codegraph @

upstream/debian-unstable/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.71 2025/08/23 22:50:00 tom Exp $
31 .TH window 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\%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 The following functions set a window's modes after it is created:
109 .RS
110 .PP
111 .BR \%idcok ","
112 .BR \%idlok ","
113 .BR \%immedok ","
114 .BR \%keypad ","
115 .BR \%leaveok ","
116 .BR \%nodelay ","
117 .BR \%notimeout ","
118 .BR \%scrollok ","
119 .BR \%setscrreg ","
120 .BR \%syncok ","
121 .BR \%wbkgdset ","
122 .BR \%wbkgrndset ","
123 and
124 .BR \%wtimeout "."
125 .RE
126 .SS delwin
127 Calling \fBdelwin\fP deletes the named window, freeing all memory
128 associated with it (it does not actually erase the window's screen
129 image).
130 Subwindows must be deleted before the main window can be deleted.
131 .SS mvwin
132 Calling \fBmvwin\fP moves the window so that the upper left-hand
133 corner is at position (\fIx\fP, \fIy\fP).
134 If the move would cause the window to be off the screen,
135 it is an error and the window is not moved.
136 Moving subwindows is allowed, but should be avoided.
137 .SS subwin
138 Calling \fBsubwin\fP creates and returns a pointer to a new window
139 with the given number of lines, \fInlines\fP, and columns, \fIncols\fP.
140 The window is at position (\fIbegin\fR_\fIy\fP,
141 \fIbegin\fR_\fIx\fP) on the screen.
142 The subwindow shares memory with the window \fIorig\fP,
143 its \fIancestor\fP,
144 so that changes made to one window
145 will affect both windows.
146 When using this routine, it is necessary to call
147 \fBtouchwin\fP or \fBtouchline\fP on \fIorig\fP before calling
148 \fBwrefresh\fP on the subwindow.
149 .SS derwin
150 Calling \fBderwin\fP is the same as calling \fBsubwin,\fP except that
151 \fIbegin\fR_\fIy\fP and \fIbegin\fR_\fIx\fP are relative to the origin
152 of the window \fIorig\fP rather than the screen.
153 There is no difference between the subwindows and the derived windows.
154 .SS mvderwin
155 Calling \fBmvderwin\fP moves a derived window (or subwindow)
156 inside its parent window.
157 The screen-relative parameters of the window are not changed.
158 This routine is used to display different
159 parts of the parent window at the same physical position on the
160 screen.
161 .SS dupwin
162 Calling \fBdupwin\fP creates an exact duplicate of the window \fIwin\fP.
163 .SS wsyncup
164 Calling \fBwsyncup\fP touches all locations in ancestors of \fIwin\fP that are
165 changed in \fIwin\fP.
166 If \fBsyncok\fP is called with second argument
167 \fBTRUE\fP then \fBwsyncup\fP is called automatically whenever there is a
168 change in the window.
169 .SS wsyncdown
170 The \fBwsyncdown\fP routine touches each location in \fIwin\fP that has been
171 touched in any of its ancestor windows.
172 This routine is called by
173 \fBwrefresh\fP, so it should almost never be necessary to call it manually.
174 .SS wcursyncup
175 The routine \fBwcursyncup\fP updates the current cursor position of all the
176 ancestors of the window to reflect the current cursor position of the
177 window.
178 .SH RETURN VALUE
179 Functions that return integers return
180 .B ERR
181 upon failure and
182 .B OK
183 upon success.
184 .PP
185 Functions that return pointers return a null pointer on failure.
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 \fBinitscr\fP(3NCURSES) or \fBnewterm\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)