| blob | 01bb3fc1705f341555b31629606888c840421ad8 |
1 .\" $NetBSD: doc.I,v 1.5 2003/08/07 16:44:27 agc Exp $
2 .\"
3 .\" Copyright (c) 1980, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)doc.I 8.1 (Berkeley) 6/4/93
31 .\"
32 .Ds
33 .Fd addch ch \*m
34 char ch;
35 .Fd waddch win\*,ch
36 WINDOW *win;
37 char ch;
38 .De
39 Add the character
40 .Vn ch
41 on the window
42 at the current \*y.
43 If the character is a newline
44 (\'\en\')
45 the line will be cleared to the end,
46 and the current \*y will be changed to the
47 beginning off the next line
48 if newline mapping is on,
49 or to the next line at the same x co-ordinate
50 if it is off.
51 A return
52 (\'\er\')
53 will move to the beginning of the line on the window.
54 Tabs
55 (\'\et\')
56 will be expanded into spaces
57 in the normal tabstop positions of
58 every eight characters.
59 \*(Es
60 .Ds
61 .Fd addstr str \*m
62 char *str;
63 .Fd waddstr win\*,str
64 WINDOW *win;
65 char *str;
66 .De
67 Add the string pointed to by
68 .Vn str
69 on the window at the current \*y.
70 \*(Es
71 In this case, it will put on as much as it can.
72 .Ds
73 .Fd box win\*,vert\*,hor
74 WINDOW *win;
75 char vert\*,hor;
76 .De
77 .Pp
78 Draws a box around the window using
79 .Vn vert
80 as the character for drawing the vertical sides, and
81 .Vn hor
82 for drawing the horizontal lines.
83 If scrolling is not allowed,
84 and the window encompasses the lower right-hand corner of the terminal,
85 the corners are left blank to avoid a scroll.
86 .Ds
87 .Fd clear "" \*m
88 .Fd wclear win
89 WINDOW *win;
90 .De
91 Resets the entire window to blanks.
92 If
93 .Vn win
94 is a screen,
95 this sets the clear flag,
96 which will cause a clear-screen sequence to be sent
97 on the next
98 .Fn refresh
99 call.
100 This also moves the current \*y
101 to (0\*,0).
102 .Ds
103 .Fd clearok scr\*,boolf \*m
104 WINDOW *scr;
105 bool boolf;
106 .De
107 Sets the clear flag for the screen
108 .Vn scr .
109 If
110 .Vn boolf
111 is TRUE,
112 this will force a clear-screen to be printed on the next
113 .Fn refresh ,
114 or stop it from doing so if
115 .Vn boolf
116 is FALSE.
117 This only works on screens,
118 and,
119 unlike
120 .Fn clear ,
121 does not alter the contents of the screen.
122 If
123 .Vn scr
124 is
125 .Vn curscr ,
126 the next
127 .Fn refresh
128 call will cause a clear-screen,
129 even if the window passed to
130 .Fn refresh
131 is not a screen.
132 .Ds
133 .Fd clrtobot "" \*m
134 .Fd wclrtobot win
135 WINDOW *win;
136 .De
137 Wipes the window clear from the current \*y to the bottom.
138 This does not force a clear-screen sequence on the next refresh
139 under any circumstances.
140 \*(Nm
141 .Ds
142 .Fd clrtoeol "" \*m
143 .Fd wclrtoeol win
144 WINDOW *win;
145 .De
146 Wipes the window clear from the current \*y to the end of the line.
147 \*(Nm
148 .Ds
149 .Fd delch
150 .Fd wdelch win
151 WINDOW *win;
152 .De
153 Delete the character at the current \*y.
154 Each character after it on the line shifts to the left,
155 and the last character becomes blank.
156 .Ds
157 .Fd deleteln
158 .Fd wdeleteln win
159 WINDOW *win;
160 .De
161 Delete the current line.
162 Every line below the current one will move up,
163 and the bottom line will become blank.
164 The current \*y will remain unchanged.
165 .Ds
166 .Fd erase "" \*m
167 .Fd werase win
168 WINDOW *win;
169 .De
170 Erases the window to blanks without setting the clear flag.
171 This is analagous to
172 .Fn clear ,
173 except that it never causes a clear-screen sequence to be generated
174 on a
175 .Fn refresh .
176 \*(Nm
177 .Ds
178 .Fd flushok win\*,boolf \*m
179 WINDOW *win;
180 bool boolf;
181 .De
182 Normally,
183 .Fn refresh
184 .Fn fflush 's
185 .Vn stdout
186 when it is finished.
187 .Fn flushok
188 allows you to control this.
189 if
190 .Vn boolf
191 is TRUE
192 (\c
193 .i i.e. ,
194 non-zero)
195 it will do the
196 .Fn fflush ;
197 if it is FALSE.
198 it will not.
199 .Ds
200 .Fd idlok win\*,boolf
201 WINDOW *win;
202 bool boolf;
203 .De
204 Reserved for future use.
205 This will eventually signal to
206 .Fn refresh
207 that it is all right to use the insert and delete line sequences
208 when updating the window.
209 .Ds
210 .Fd insch c
211 char c;
212 .Fd winsch win\*,c
213 WINDOW *win;
214 char c;
215 .De
216 Insert
217 .Vn c
218 at the current \*y
219 Each character after it shifts to the right,
220 and the last character disappears.
221 \*(Es
222 .Ds
223 .Fd insertln
224 .Fd winsertln win
225 WINDOW *win;
226 .De
227 Insert a line above the current one.
228 Every line below the current line
229 will be shifted down,
230 and the bottom line will disappear.
231 The current line will become blank,
232 and the current \*y will remain unchanged.
233 .Ds
234 .Fd move y\*,x \*m
235 int y\*,x;
236 .Fd wmove win\*,y\*,x
237 WINDOW *win;
238 int y\*,x;
239 .De
240 Change the current \*y of the window to
241 .Vn y\*,x ). (
242 \*(Es
243 .Ds
244 .Fd overlay win1\*,win2
245 WINDOW *win1\*,*win2;
246 .De
247 Overlay
248 .Vn win1
249 on
250 .Vn win2 .
251 The contents of
252 .Vn win1 ,
253 insofar as they fit,
254 are placed on
255 .Vn win2
256 at their starting \*y.
257 This is done non-destructively,
258 i.e., blanks on
259 .Vn win1
260 leave the contents of the space on
261 .Vn win2
262 untouched.
263 .Ds
264 .Fd overwrite win1\*,win2
265 WINDOW *win1\*,*win2;
266 .De
267 Overwrite
268 .Vn win1
269 on
270 .Vn win2 .
271 The contents of
272 .Vn win1 ,
273 insofar as they fit,
274 are placed on
275 .Vn win2
276 at their starting \*y.
277 This is done destructively,
278 .i i.e. ,
279 blanks on
280 .Vn win1
281 become blank on
282 .Vn win2 .
283 .Ds
284 .Fd printw fmt\*,arg1\*,arg2\*,...
285 char *fmt;
286 .Fd wprintw win\*,fmt\*,arg1\*,arg2\*,...
287 WINDOW *win;
288 char *fmt;
289 .De
290 Performs a
291 .Fn printf
292 on the window starting at the current \*y.
293 It uses
294 .Fn addstr
295 to add the string on the window.
296 It is often advisable to use the field width options of
297 .Fn printf
298 to avoid leaving things on the window from earlier calls.
299 \*(Es
300 .Ds
301 .Fd refresh "" \*m
302 .Fd wrefresh win
303 WINDOW *win;
304 .De
305 Synchronize the terminal screen with the desired window.
306 If the window is not a screen,
307 only that part covered by it is updated.
308 \*(Es
309 In this case, it will update whatever it can
310 without causing the scroll.
311 .sp
312 As a special case,
313 if
314 .Fn wrefresh
315 is called with the window
316 .Vn curscr
317 the screen is cleared
318 and repainted as it is currently.
319 This is very useful for allowing the redrawing of the screen
320 when the user has garbage dumped on his terminal.
321 .Ds
322 .Fd standout "" \*m
323 .Fd wstandout win
324 WINDOW *win;
325 .Fd standend "" \*m
326 .Fd wstandend win
327 WINDOW *win;
328 .De
329 Start and stop putting characters onto
330 .i win
331 in standout mode.
332 .Fn standout
333 causes any characters added to the window
334 to be put in standout mode on the terminal
335 (if it has that capability).
336 .Fn standend
337 stops this.
338 The sequences
339 .Vn SO
340 and
341 .Vn SE
342 (or
343 .Vn US
344 and
345 .Vn UE
346 if they are not defined)
347 are used (see Appendix A).