| blob | d2fe8b6d5ada9b38d36eee7e0853b6a1312f63ba |
1 .\" $NetBSD: curses_window.3,v 1.15 2011/09/15 12:01:18 wiz Exp $
2 .\"
3 .\" Copyright (c) 2002
4 .\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au)
5 .\"
6 .\" This code is donated to the NetBSD Foundation by the Author.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. The name of the Author may not be used to endorse or promote
17 .\" products derived from this software without specific prior written
18 .\" permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\"
33 .Dd September 15, 2011
34 .Dt CURSES_WINDOW 3
35 .Os
36 .Sh NAME
37 .Nm curses_window ,
38 .Nm copywin ,
39 .Nm dupwin ,
40 .Nm delwin ,
41 .Nm derwin ,
42 .Nm mvwin ,
43 .Nm mvderwin ,
44 .Nm newwin ,
45 .Nm overlay ,
46 .Nm overwrite ,
47 .Nm subwin ,
48 .Nm wresize
49 .Nd curses window routines
50 .Sh LIBRARY
51 .Lb libcurses
52 .Sh SYNOPSIS
53 .In curses.h
54 .Ft int
55 .Fo copywin
56 .Fa "WINDOW *source"
57 .Fa "WINDOW *dest"
58 .Fa "int sminrow"
59 .Fa "int smincol"
60 .Fa "int dminrow"
61 .Fa "int dmincol"
62 .Fa "int dmaxrow"
63 .Fa "int dmaxcol"
64 .Fa "int overlay"
65 .Fc
66 .Ft WINDOW *
67 .Fn dupwin "WINDOW *win"
68 .Ft WINDOW *
69 .Fn derwin "WINDOW *win" "int lines" "int cols" "int y" "int x"
70 .Ft int
71 .Fn delwin "WINDOW *win"
72 .Ft int
73 .Fn mvwin "WINDOW *win" "int y" "int x"
74 .Ft int
75 .Fn mvderwin "WINDOW *win" "int y" "int x"
76 .Ft WINDOW *
77 .Fn newwin "int lines" "int cols" "int begin_y" "int begin_x"
78 .Ft WINDOW *
79 .Fn subwin "WINDOW *win" "int lines" "int cols" "int begin_y" "int begin_x"
80 .Ft int
81 .Fn overlay "WINDOW *source" "WINDOW *dest"
82 .Ft int
83 .Fn overwrite "WINDOW *source" "WINDOW *dest"
84 .Ft int
85 .Fn wresize "WINDOW *win" "int lines" "int cols"
86 .Sh DESCRIPTION
87 These functions create, modify and delete windows on the current screen.
88 .Pp
89 The contents of a window may be copied to another window by using the
90 .Fn copywin
91 function, a section of the destination window
92 .Fa dest
93 bounded by
94 .Fa (dminrow ,
95 .Fa dmincol )
96 and
97 .Fa (dmaxrow ,
98 .Fa dmaxcol )
99 will be overwritten with the contents of the window
100 .Fa source
101 starting at the coordinates
102 .Fa (sminrow ,
103 .Fa smincol ) .
104 If the
105 .Fa overlay
106 flag is
107 .Dv TRUE
108 then only non-blank characters from
109 .Fa source
110 will be copied to
111 .Fa dest ,
112 if
113 .Fa overlay
114 is
115 .Dv FALSE
116 then all characters from
117 .Fa source
118 will be copied to
119 .Fa dest .
120 If the bounding rectangles of either the source or the destination
121 windows lay outside the maximum size of the respective windows then
122 the size of the window copied will be adjusted to be within the bounds
123 of both the source and destination windows.
124 .Pp
125 The
126 .Fn dupwin
127 function creates an exact duplicate of
128 .Fa win
129 and returns a pointer to it.
130 .Pp
131 Calling
132 .Fn derwin
133 will create a subwindow of
134 .Fa win
135 in the same manner as
136 .Fn subwin
137 excepting that the starting column and row
138 .Fa y ,
139 .Fa x
140 are relative to the parent window origin.
141 .Pp
142 A window may deleted and all resources freed by calling the
143 .Fn delwin
144 function with the pointer to the window to be deleted in
145 .Fa win .
146 .Pp
147 A window can be moved to a new position by calling the
148 .Fn mvwin
149 function.
150 The
151 .Fa y
152 and
153 .Fa x
154 positions are the new origin of the window on the screen.
155 If the new position would cause the any part of the window to lie outside
156 the screen, it is an error and the window is not moved.
157 .Pp
158 A mapping of a region relative to the parent window may be created by
159 calling the
160 .Fn mvderwin
161 function, the
162 .Fa y
163 and
164 .Fa x
165 positions are relative to the origin of the parent window.
166 The screen offset of
167 .Fa win
168 is not updated, the characters beginning at
169 .Fa y ,
170 .Fa x
171 for the area the size of
172 .Fa win
173 will be displayed at the screen offset of
174 .Fa win .
175 If the given window in
176 .Fa win
177 is not a subwindow then an error will be returned.
178 If the new position would cause the any part of the window to lie outside
179 the parent window, it is an error and the mapping is not updated.
180 .Pp
181 The
182 .Fn newwin
183 function creates a new window of size
184 .Fa lines ,
185 .Fa cols
186 with an origin at
187 .Fa begin_y ,
188 .Fa begin_x .
189 If
190 .Fa lines
191 is less than or equal to zero then the number of rows
192 for the window is set to
193 .Dv LINES -
194 .Fa begin_x
195 +
196 .Fa lines .
197 Similarly if
198 .Fa cols
199 is less than or equal to zero then the number of columns
200 for the window is set to
201 .Dv COLS -
202 .Fa begin_y
203 +
204 .Fa cols .
205 .Pp
206 .Fn subwin
207 is similar to
208 .Fn newwin
209 excepting that the size of the subwindow is bounded by the parent
210 window
211 .Fa win .
212 The subwindow shares internal data structures with the parent window
213 and will be refreshed when the parent window is refreshed.
214 The subwindow inherits the background character and attributes of the
215 parent window.
216 .Pp
217 The
218 .Fn overlay
219 function copies the contents of the source window
220 .Fa source
221 to the destination window
222 .Fa dest ,
223 only the characters that are not the background character in the
224 source window are copied to the destination.
225 The windows need not be the same size, only the overlapping portion of both
226 windows will be copied.
227 The
228 .Fn overwrite
229 function performs the same functions as
230 .Fn overlay
231 excepting that characters from the source window are copied to the
232 destination without exception.
233 .Pp
234 .Fn wresize
235 resizes the specified window to the new number of lines and columns
236 given, all internal curses structures are resized.
237 Any subwindows of the specified window will also be resized if any part
238 of them falls outside the new parent window size.
239 The application must redraw the window after it has been resized.
240 Note that
241 .Dv curscr
242 and
243 .Dv stdscr
244 can not be resized to be larger than the size of the screen.
245 .Sh RETURN VALUES
246 Functions returning pointers will return
247 .Dv NULL
248 if an error is detected.
249 The functions that return an int will return one of the following
250 values:
251 .Pp
252 .Bl -tag -width ERR -compact
253 .It Er OK
254 The function completed successfully.
255 .It Er ERR
256 An error occurred in the function.
257 .El
258 .Sh SEE ALSO
259 .Xr curses_fileio 3 ,
260 .Xr curses_pad 3 ,
261 .Xr curses_screen 3
262 .Sh STANDARDS
263 The
264 .Nx
265 Curses library complies with the X/Open Curses specification, part of the
266 Single Unix Specification.
267 .Sh HISTORY
268 The Curses package appeared in
269 .Bx 4.0 .