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