| blob | 94d4dd2672079c1b4cc761e4dd8d577c3826976d |
1 .\" $NetBSD: doc.III,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.III 8.1 (Berkeley) 6/4/93
31 .\"
32 .Ds
33 .Fd baudrate "" \*m
34 .De
35 Returns the output baud rate of the terminal.
36 This is a system dependent constant
37 (defined in
38 .b <sys/tty.h>
39 on BSD systems,
40 which is included by
41 .b <curses.h> ).
42 .Ds
43 .Fd delwin win
44 WINDOW *win;
45 .De
46 Deletes the window from existence.
47 All resources are freed for future use by
48 .b calloc (3).
49 If a window has a
50 .Fn subwin
51 allocated window inside of it,
52 deleting the outer window
53 the subwindow is not affected,
54 even though this does invalidate it.
55 Therefore,
56 subwindows should be deleted before their
57 outer windows are.
58 .Ds
59 .Fd endwin
60 .De
61 Finish up window routines before exit.
62 This restores the terminal to the state it was before
63 .Fn initscr
64 (or
65 .Fn gettmode
66 and
67 .Fn setterm )
68 was called.
69 It should always be called before exiting.
70 It does not exit.
71 This is especially useful for resetting tty stats
72 when trapping rubouts via
73 .b signal (2).
74 .Ds
75 .Fd erasechar "" \*m
76 .De
77 Returns the erase character
78 for the terminal,
79 .i i.e. ,
80 the character used by the user to erase a single character from the input.
81 .Ds
82 .Fd getcap str "" "char *"
83 char *str;
84 .De
85 Return a pointer to the
86 .b termcap
87 capability described by
88 .Vn str
89 (see
90 .b termcap (5)
91 for details).
92 .Ds
93 .Fd getyx win\*,y\*,x \*m
94 WINDOW *win;
95 int y\*,x;
96 .De
97 Puts the current \*y of
98 .Vn win
99 in the variables
100 .Vn y
101 and
102 .Vn x .
103 Since it is a macro,
104 not a function,
105 you do not pass the address
106 of
107 .Vn y
108 and
109 .Vn x .
110 .Ds
111 .Fd inch "" \*m
112 .Fd winch win \*m
113 WINDOW *win;
114 .De
115 Returns the character at the current \*(y
116 on the given window.
117 This does not make any changes to the window.
118 .Ds
119 .Fd initscr
120 .De
121 Initialize the screen routines.
122 This must be called before any of the screen routines are used.
123 It initializes the terminal-type data and such,
124 and without it none of the routines can operate.
125 If standard input is not a tty,
126 it sets the specifications to the terminal
127 whose name is pointed to by
128 .Vn Def\*_term
129 (initialy "dumb").
130 If the boolean
131 .Vn My\*_term
132 is true,
133 .Vn Def\*_term
134 is always used.
135 If the system supports the
136 .b TIOCGWINSZ
137 .Fn ioctl "" "" 2
138 call,
139 it is used to get the number of lines and columns for the terminal,
140 otherwise it is taken from the
141 .b termcap
142 description.
143 .Ds
144 .Fd killchar "" \*m
145 .De
146 Returns the line kill character
147 for the terminal,
148 .i i.e. ,
149 the character used by the user to erase an entire line from the input.
150 .Ds
151 .Fd leaveok win\*,boolf \*m
152 WINDOW *win;
153 bool boolf;
154 .De
155 Sets the boolean flag for leaving the cursor after the last change.
156 If
157 .Vn boolf
158 is TRUE,
159 the cursor will be left after the last update on the terminal,
160 and the current \*y for
161 .Vn win
162 will be changed accordingly.
163 If it is FALSE,
164 it will be moved to the current \*y.
165 This flag
166 (initialy FALSE)
167 retains its value until changed by the user.
168 .Ds
169 .Fd longname termbuf\*,name
170 char *termbuf\*,*name;
171 .Fd fullname termbuf\*,name
172 char *termbuf\*,*name;
173 .De
174 .Fn longname
175 fills in
176 .Vn name
177 with the long name of the terminal described by the
178 .b termcap
179 entry in
180 .Vn termbuf .
181 It is generally of little use,
182 but is nice for telling the user in a readable format what terminal
183 we think he has.
184 This is available in the global variable
185 .Vn ttytype .
186 .Vn termbuf
187 is usually set via the termlib routine
188 .Fn tgetent .
189 .Fn fullname
190 is the same as
191 .Fn longname ,
192 except that it gives the fullest name given in the entry,
193 which can be quite verbose.
194 .Ds
195 .Fd mvwin win\*,y\*,x
196 WINDOW *win;
197 int y, x;
198 .De
199 Move the home position of the window
200 .Vn win
201 from its current starting coordinates
202 to
203 .Vn y\*,x ). (
204 If that would put part or all of the window
205 off the edge of the terminal screen,
206 .Fn mvwin
207 returns ERR and does not change anything.
208 For subwindows,
209 .Fn mvwin
210 also returns ERR if you attempt to move it off its main window.
211 If you move a main window,
212 all subwindows are moved along with it.
213 .Ds
214 .Fd newwin lines\*,cols\*,begin\*_y\*,begin\*_x "" "WINDOW *"
215 int lines\*,cols\*,begin\*_y\*,begin\*_x;
216 .De
217 Create a new window with
218 .Vn lines
219 lines and
220 .Vn cols
221 columns starting at position
222 .Vn begin\*_y\*,begin\*_x ). (
223 If either
224 .Vn lines
225 or
226 .Vn cols
227 is 0 (zero),
228 that dimension will be set to
229 .Vn "LINES \- begin\*_y" ) (
230 or
231 .Vn "COLS \- begin\*_x" ) (
232 respectively.
233 Thus, to get a new window of dimensions
234 .Vn LINES
235 \(mu
236 .Vn COLS ,
237 use
238 .Fn newwin . "" 0\*,0\*,0\*,0
239 .Ds
240 .Fd nl "" \*m
241 .Fd nonl "" \*m
242 .De
243 Set or unset the terminal to/from nl mode,
244 .i i.e. ,
245 start/stop the system from mapping
246 .b <RETURN>
247 to
248 .b <LINE-FEED> .
249 If the mapping is not done,
250 .Fn refresh
251 can do more optimization,
252 so it is recommended, but not required, to turn it off.
253 .Ds
254 .Fd scrollok win\*,boolf \*m
255 WINDOW *win;
256 bool boolf;
257 .De
258 Set the scroll flag for the given window.
259 If
260 .Vn boolf
261 is FALSE, scrolling is not allowed.
262 This is its default setting.
263 .Ds
264 .Fd touchline win\*,y\*,startx\*,endx
265 WINDOW *win;
266 int y\*,startx\*,endx;
267 .De
268 This function performs a function similar to
269 .Fn touchwin
270 on a single line.
271 It marks the first change for the given line
272 to be
273 .Vn startx ,
274 if it is before the current first change mark,
275 and
276 the last change mark is set to be
277 .Vn endx
278 if it is currently less than
279 .Vn endx .
280 .Ds
281 .Fd touchoverlap win1\*,win2
282 WINDOW *win1, *win2;
283 .De
284 Touch the window
285 .Vn win2
286 in the area which overlaps with
287 .Vn win1 .
288 If they do not overlap,
289 no changes are made.
290 .Ds
291 .Fd touchwin win
292 WINDOW *win;
293 .De
294 Make it appear that the every location on the window
295 has been changed.
296 This is usually only needed for refreshes with overlapping windows.
297 .Ds
298 .Fd subwin win\*,lines\*,cols\*,begin\*_y\*,begin\*_x "" "WINDOW *"
299 WINDOW *win;
300 int lines\*,cols\*,begin\*_y\*,begin\*_x;
301 .De
302 Create a new window with
303 .Vn lines
304 lines and
305 .Vn cols
306 columns starting at position
307 .Vn begin\*_y\*,begin\*_x ) (
308 inside the window
309 .i win .
310 This means that any change made to either window
311 in the area covered
312 by the subwindow will be made on both windows.
313 .Vn begin\*_y\*,begin\*_x
314 are specified relative to the overall screen,
315 not the relative (0\*,0) of
316 .Vn win .
317 If either
318 .Vn lines
319 or
320 .Vn cols
321 is 0 (zero),
322 that dimension will be set to
323 .Vn "LINES \- begin\*_y" ) (
324 or
325 .Vn "COLS \- begin\*_x" ) (
326 respectively.
327 .Ds
328 .Fd unctrl ch \*m
329 char ch;
330 .De
331 This is actually a debug function for the library,
332 but it is of general usefulness.
333 It returns a string which is a representation of
334 .Vn ch .
335 Control characters become their upper-case equivalents preceded by a "^".
336 Other letters stay just as they are.
337 To use
338 .Fn unctrl ,
339 you may have to have
340 .b #include\ <unctrl.h>
341 in your file.