1.\"	$NetBSD: doc.I,v 1.4 1998/01/09 04:12:06 perry 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
34char	ch;
35.Fd waddch win\*,ch
36WINDOW	*win;
37char	ch;
38.De
39Add the character
40.Vn ch
41on the window
42at the current \*y.
43If the character is a newline
44(\'\en\')
45the line will be cleared to the end,
46and the current \*y will be changed to the
47beginning off the next line
48if newline mapping is on,
49or to the next line at the same x co-ordinate
50if it is off.
51A return
52(\'\er\')
53will move to the beginning of the line on the window.
54Tabs
55(\'\et\')
56will be expanded into spaces
57in the normal tabstop positions of
58every eight characters.
59\*(Es
60.Ds
61.Fd addstr str \*m
62char	*str;
63.Fd waddstr win\*,str
64WINDOW	*win;
65char	*str;
66.De
67Add the string pointed to by
68.Vn str
69on the window at the current \*y.
70\*(Es
71In this case, it will put on as much as it can.
72.Ds
73.Fd box win\*,vert\*,hor
74WINDOW	*win;
75char	vert\*,hor;
76.De
77.Pp
78Draws a box around the window using
79.Vn vert
80as the character for drawing the vertical sides, and
81.Vn hor
82for drawing the horizontal lines.
83If scrolling is not allowed,
84and the window encompasses the lower right-hand corner of the terminal,
85the corners are left blank to avoid a scroll.
86.Ds
87.Fd clear "" \*m
88.Fd wclear win
89WINDOW	*win;
90.De
91Resets the entire window to blanks.
92If
93.Vn win
94is a screen,
95this sets the clear flag,
96which will cause a clear-screen sequence to be sent
97on the next
98.Fn refresh
99call.
100This also moves the current \*y
101to (0\*,0).
102.Ds
103.Fd clearok scr\*,boolf \*m
104WINDOW	*scr;
105bool	boolf;
106.De
107Sets the clear flag for the screen
108.Vn scr .
109If
110.Vn boolf
111is TRUE,
112this will force a clear-screen to be printed on the next
113.Fn refresh ,
114or stop it from doing so if
115.Vn boolf
116is FALSE.
117This only works on screens,
118and,
119unlike
120.Fn clear ,
121does not alter the contents of the screen.
122If
123.Vn scr
124is
125.Vn curscr ,
126the next
127.Fn refresh
128call will cause a clear-screen,
129even if the window passed to
130.Fn refresh
131is not a screen.
132.Ds
133.Fd clrtobot "" \*m
134.Fd wclrtobot win
135WINDOW	*win;
136.De
137Wipes the window clear from the current \*y to the bottom.
138This does not force a clear-screen sequence on the next refresh
139under any circumstances.
140\*(Nm
141.Ds
142.Fd clrtoeol "" \*m
143.Fd wclrtoeol win
144WINDOW	*win;
145.De
146Wipes the window clear from the current \*y to the end of the line.
147\*(Nm
148.Ds
149.Fd delch
150.Fd wdelch win
151WINDOW	*win;
152.De
153Delete the character at the current \*y.
154Each character after it on the line shifts to the left,
155and the last character becomes blank.
156.Ds
157.Fd deleteln
158.Fd wdeleteln win
159WINDOW	*win;
160.De
161Delete the current line.
162Every line below the current one will move up,
163and the bottom line will become blank.
164The current \*y will remain unchanged.
165.Ds
166.Fd erase "" \*m
167.Fd werase win
168WINDOW	*win;
169.De
170Erases the window to blanks without setting the clear flag.
171This is analagous to
172.Fn clear ,
173except that it never causes a clear-screen sequence to be generated
174on a
175.Fn refresh .
176\*(Nm
177.Ds
178.Fd flushok win\*,boolf \*m
179WINDOW	*win;
180bool	boolf;
181.De
182Normally,
183.Fn refresh
184.Fn fflush 's
185.Vn stdout
186when it is finished.
187.Fn flushok
188allows you to control this.
189if
190.Vn boolf
191is TRUE
192(\c
193.i i.e. ,
194non-zero)
195it will do the
196.Fn fflush ;
197if it is FALSE.
198it will not.
199.Ds
200.Fd idlok win\*,boolf
201WINDOW	*win;
202bool	boolf;
203.De
204Reserved for future use.
205This will eventually signal to
206.Fn refresh
207that it is all right to use the insert and delete line sequences
208when updating the window.
209.Ds
210.Fd insch c
211char	c;
212.Fd winsch win\*,c
213WINDOW	*win;
214char	c;
215.De
216Insert
217.Vn c
218at the current \*y
219Each character after it shifts to the right,
220and the last character disappears.
221\*(Es
222.Ds
223.Fd insertln
224.Fd winsertln win
225WINDOW	*win;
226.De
227Insert a line above the current one.
228Every line below the current line
229will be shifted down,
230and the bottom line will disappear.
231The current line will become blank,
232and the current \*y will remain unchanged.
233.Ds
234.Fd move y\*,x \*m
235int	y\*,x;
236.Fd wmove win\*,y\*,x
237WINDOW	*win;
238int	y\*,x;
239.De
240Change the current \*y of the window to
241.Vn y\*,x ). (
242\*(Es
243.Ds
244.Fd overlay win1\*,win2
245WINDOW	*win1\*,*win2;
246.De
247Overlay
248.Vn win1
249on
250.Vn win2 .
251The contents of
252.Vn win1 ,
253insofar as they fit,
254are placed on
255.Vn win2
256at their starting \*y.
257This is done non-destructively,
258i.e., blanks on
259.Vn win1
260leave the contents of the space on
261.Vn win2
262untouched.
263.Ds
264.Fd overwrite win1\*,win2
265WINDOW	*win1\*,*win2;
266.De
267Overwrite
268.Vn win1
269on
270.Vn win2 .
271The contents of
272.Vn win1 ,
273insofar as they fit,
274are placed on
275.Vn win2
276at their starting \*y.
277This is done destructively,
278.i i.e. ,
279blanks on
280.Vn win1
281become blank on
282.Vn win2 .
283.Ds
284.Fd printw fmt\*,arg1\*,arg2\*,...
285char	*fmt;
286.Fd wprintw win\*,fmt\*,arg1\*,arg2\*,...
287WINDOW	*win;
288char	*fmt;
289.De
290Performs a
291.Fn printf
292on the window starting at the current \*y.
293It uses
294.Fn addstr
295to add the string on the window.
296It is often advisable to use the field width options of
297.Fn printf
298to avoid leaving things on the window from earlier calls.
299\*(Es
300.Ds
301.Fd refresh "" \*m
302.Fd wrefresh win
303WINDOW	*win;
304.De
305Synchronize the terminal screen with the desired window.
306If the window is not a screen,
307only that part covered by it is updated.
308\*(Es
309In this case, it will update whatever it can
310without causing the scroll.
311.sp
312As a special case,
313if
314.Fn wrefresh
315is called with the window
316.Vn curscr
317the screen is cleared
318and repainted as it is currently.
319This is very useful for allowing the redrawing of the screen
320when the user has garbage dumped on his terminal.
321.Ds
322.Fd standout "" \*m
323.Fd wstandout win
324WINDOW	*win;
325.Fd standend "" \*m
326.Fd wstandend win
327WINDOW	*win;
328.De
329Start and stop putting characters onto
330.i win
331in standout mode.
332.Fn standout
333causes any characters added to the window
334to be put in standout mode on the terminal
335(if it has that capability).
336.Fn standend
337stops this.
338The sequences
339.Vn SO
340and
341.Vn SE
342(or
343.Vn US
344and
345.Vn UE
346if they are not defined)
347are used (see Appendix A).
348