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). 348