1.\" $NetBSD: curses.3,v 1.30 2001/01/01 10:36:12 simonb Exp $ 2.\" 3.\" Copyright (c) 1985, 1991, 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)curses.3 8.1 (Berkeley) 6/4/93 35.\" 36.Dd March 11, 1999 37.Dt CURSES 3 38.Os 39.Sh NAME 40.Nm curses 41.Nd screen functions with 42.Dq optimal 43cursor motion 44.Sh LIBRARY 45.Lb libcurses 46.Sh SYNOPSIS 47.Nm cc 48.Op Ar flags 49.Ar files 50.Fl lcurses ltermcap 51.Op Ar libraries 52.Sh DESCRIPTION 53These routines give the user a method of updating screens with reasonable 54optimization. They keep an image of the current screen, 55and the user sets up an image of a new one. Then the 56.Fn refresh 57tells the routines to make the current screen look like the new one. 58In order to initialize the routines, the routine 59.Fn initscr 60must be called before any of the other routines that deal with windows and 61screens are used. The routine 62.Fn endwin 63should be called before exiting. The routine 64.Fn start_color 65must be called before any of the other routines that deal with color are used. 66.Sh SEE ALSO 67.Xr ioctl 2 , 68.Xr getenv 3 , 69.Xr tty 4 , 70.Xr termcap 5 71.Rs 72.%T Screen Updating and Cursor Movement Optimization: A Library Package 73.%A Ken Arnold 74.Re 75.Sh AUTHOR 76.An Ken Arnold 77.Sh FUNCTIONS 78.Bl -column "subwin(win,lines,cols,begin_y,begin_x)" 79.It addch(ch) add a character to 80.Em stdscr 81.It addstr(str) add a string to 82.Em stdscr 83.It addnstr(str,len) add no more than len chars of string to 84.Em stdscr 85.It attron(attribute) turn on attribute modes 86.It attroff(attribute) turn off attribute modes 87.It attrset(attribute) set attribute modes 88.It beep() sound the terminal bell 89.It bkgd(ch) set background rendition for 90.Em stdscr 91and applies this rendition to 92.Em stdscr 93.It bkgdset(ch) set background rendition for 94.Em stdscr 95.It border(ls,rs,ts,bs,tl,tr,bl,br) draw a border around 96.Em stdscr 97.It box(win,vert,hor) draw a box around a window 98.It can_change_colors() check if terminal can change colors 99.It cbreak() set cbreak mode 100.It clear() clear 101.Em stdscr 102.It clearok(win,boolf) set clear flag for 103.Em win 104.It clrtobot() clear to bottom on 105.Em stdscr 106.It clrtoeol() clear to end of line on 107.Em stdscr 108.It color_content(c, r, g, b) get rgb values of color 109.It copywin(srcwin, dstwin, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol, overlay) 110 Copy rectangle from 111.Em srcwin 112to 113.Em dstwin. 114If overlay is true then copy is nondestructive. 115.It curs_set(vis) change cursor visibility, 0 is invisible, 1 is 116normal, 2 is high visibility. Returns previous value on success. 117.It delay_output(ms) pause output for 118.Em ms 119milliseconds using terminal pad character. 120.It def_prog_mode() define program (in curses) terminal modes 121.It def_shell_mode() define shell (not in curses) terminal modes 122.It delch() delete a character 123.It deleteln() delete a line 124.It delwin(win) delete 125.Em win 126.It derwin(win,lines,cols,begin_y,begin_x)\ create a subwindow 127relative to 128.Em win. 129.It doupdate() make current screen look like virtual screen 130.It dupwin(win) duplicate 131.Em win 132.It echo() set echo mode 133.It endwin() end window modes 134.It erase() erase 135.Em stdscr 136.It erasechar() Return the terminal erase character 137.It flash() flash the terminal screen 138.It flushinp() flush terminal input 139.It flushok(win,boolf) set flush-on-refresh flag for 140.Em win 141.It fullname(termbuf,name) get full name from 142.Em termbuf 143.It getattrs(win) get attributes for 144.Em win 145.It getbkgd(win) get background rendition for 146.Em win 147.It getcap(name) get terminal capability 148.Em name 149.It getch() get a char through 150.Em stdscr 151.It getcury(win) get current y position on 152.Em win 153.It getcurx(win) get current x position on 154.Em win 155.It getbegy(win) get start y position on 156.Em win 157.It getbegx(win) get start x position on 158.Em win 159.It getmaxy(win) get maximum y position on 160.Em win 161.It getmaxx(win) get maximum x position on 162.Em win 163.It getstr(str) get a string through 164.Em stdscr 165.It gettmode() get tty modes 166.It getyx(win,y,x) get (y,x) co-ordinates 167.It has_colors() check if terminal has colors 168.It hline(ch, count) draw a horizontal line of character ch. 169.It idlok(win,boolf) set insert/deleteln flags for 170.Em win 171.It inch() get char at current (y,x) co-ordinates 172.It inchnstr(chstr, n) get an array of characters from 173.Em stdscr 174.It inchstr(chstr) get an array of characters from 175.Em stdscr 176.It innstr(str, n) get a string of characters from 177.Em stdscr 178.It init_color(c, r, g, b) set rgb values of color 179.It init_pair(p, f, b) set foreground and background colors of pair 180.It initscr() initialize screens 181.It insch(c) insert a char 182.It insdelln(n) insert/delete n lines on 183.Em stdstr 184.It insertln() insert a line 185.It instr(str) get a string of characters from 186.Em stdscr 187.It intrflush(win,boolf) set flush on interrupt terminal mode 188.It is_linetouched(win, line) check if line has been modified since 189last refresh. 190.It is_wintouched(win) Check if window has been modified since last 191refresh. 192.It isendwin() check if endwin() or wrefresh() was called latest 193.It keypad(win,boolf) set keypad flag for 194.Em win 195.It killchar() Return the terminal kill character. 196.It leaveok(win,boolf) set leave flag for 197.Em win 198.It longname(termbuf,name) get long name from 199.Em termbuf 200.It meta(win,boolf) turn terminal meta mode on and off. Note 201.Em win 202is always ignored. 203.It move(y,x) move to (y,x) on 204.Em stdscr 205.It mvcur(lasty,lastx,newy,newx) actually move cursor 206.It mvhline(y, x, ch, count) move to 207.Em y , 208.Em x 209and draw a horizontal line of character 210.Em ch 211for 212.Em count 213characters. 214.It mvvline(y, x, ch, count) move to 215.Em y , 216.Em x 217and draw a vertical line of character 218.Em ch 219for 220.Em count 221characters. 222.It mvwhline(win, y, x, ch, count) move to 223.Em y , 224.Em x 225and draw a horizontal line of character 226.Em ch 227for 228.Em count 229characters on window 230.Em win . 231.It mvwvline(win, y, x, ch, count) move to 232.Em y , 233.Em x 234and draw a vertical line of character 235.Em ch 236for 237.Em count 238characters on window 239.Em win . 240.It napms(ms) sleep for 241.Em ms 242milliseconds. 243.It newwin(lines,cols,begin_y,begin_x)\ create a new window 244.It nl() set newline mapping 245.It nocbreak() unset cbreak mode 246.It nodelay(win,boolf) unset blocking reads for 247.Em win 248.It noecho() unset echo mode 249.It nonl() unset newline mapping 250.It noraw() unset raw mode 251.It notimeout(win, boolf) unset infinite timeout on keypad assembly for 252.Em win 253.It overlay(win1,win2) overlay win1 on win2 254.It overwrite(win1,win2) overwrite win1 on top of win2 255.It pair_content(p, r, g, b) get foreground and background colors of pair 256.It printw(fmt,arg1,arg2,...) printf on 257.Em stdscr 258.It raw() set raw mode 259.It refresh() make current screen look like 260.Em stdscr 261.It reset_prog_mode() restore program (in curses) terminal modes 262.It reset_shell_mode() restore shell (not in curses) terminal modes 263.It resetty() reset tty flags to stored value 264.It savetty() stored current tty flags 265.It scanw(fmt,arg1,arg2,...) scanf through 266.Em stdscr 267.It scrl(n) scroll 268.Em stdscr 269n lines 270.It scroll(win) scroll 271.Em win 272one line 273.It scrollok(win,boolf) set scroll flag for 274.Em win 275.It setterm(name) set term variables for name 276.It standend() end standout mode 277.It standout() start standout mode 278.It start_color() initialise color 279.It subwin(win,lines,cols,begin_y,begin_x)\ create a subwindow 280.It timeout(delay) set blocking or non-blocking read for 281.Em stdscr 282.It touchline(win,y,sx,ex) mark line 283.Em y 284.Em sx 285through 286.Em sy 287as changed 288.It touchoverlap(win1,win2) mark overlap of 289.Em win1 290on 291.Em win2 292as changed 293.It touchwin(win) \*(lqchange\*(rq all of 294.Em win 295.It unctrl(ch) printable version of 296.Em ch 297.It underend() end underscore mode 298.It underscore() start underscore mode 299.It ungetch(ch) Put character back onto input queue. 300.It untouchwin(win) Make window appear not to have been modified. 301.It vline(ch, count) Draw a vertical line of character 302.Em ch . 303.It waddch(win,ch) add char to 304.Em win 305.It waddstr(win,str) add string to 306.Em win 307.It wattron(win,attribute) turn on attribute modes for 308.Em win 309.It wattroff(win,attribute) turn off attribute modes for 310.Em win 311.It wattrset(win,attribute) set attribute modes for 312.Em win 313.It wbkgd(win, ch) set background rendition for 314.Em win and apply this rendition to 315.Em win 316.It wbkgdset(win, ch) set background rendition for 317.Em win 318.It wborder(win,ls,rs,ts,bs,tl,tr,bl,br) draw a border around 319.Em win 320.It wclear(win) clear 321.Em win 322.It wclrtobot(win) clear to bottom of 323.Em win 324.It wclrtoeol(win) clear to end of line on 325.Em win 326.It wdelch(win) delete char from 327.Em win 328.It wdeleteln(win) delete line from 329.Em win 330.It werase(win) erase 331.Em win 332.It wgetch(win) get a char through 333.Em win 334.It wgetstr(win,str) get a string through 335.Em win 336.It whline(win, ch, count) Draw a horizontal line of character 337.Em ch 338on window 339.Em win . 340.It winch(win) get char at current (y,x) in 341.Em win 342.It winchnstr(win, chstr, n) get an array of characters from 343.Em win 344.It winchstr(win, chstr) get an array of characters from 345.Em win 346.It winnstr(win, str, n) get a string of characters from 347.Em win 348.It winsch(win,c) insert char into 349.Em win 350.It winsdelln(win,n) insert/delete n lines on 351.Em win 352.It winsertln(win) insert line into 353.Em win 354.It winstr(win,str) get a string of characters from 355.Em win 356.It wmove(win,y,x) set current (y,x) co-ordinates on 357.Em win 358.It wnoutrefresh(win) add 359.Em win 360to virtual screen 361.It wprintw(win,fmt,arg1,arg2,...)\ printf on 362.Em win 363.It wrefresh(win) make screen look like 364.Em win 365.It wscanw(win,fmt,arg1,arg2,...)\ scanf through 366.Em win 367.It wscrl(win,n) scroll 368.Em win 369n lines 370.It wstandend(win) end standout mode on 371.Em win 372.It wstandout(win) start standout mode on 373.Em win 374.It wtimeout(win,delay) set blocking or non-blocking read for 375.Em win 376.It wtouchln(win, line, n, changed) If 377.Em changed 378is 1 then touch 379.Em n 380lines starting at 381.Em line 382in window 383.Em win . 384If 385.Em changed 386is 0 then untouch 387.Em n 388lines starting at 389.Em line 390in window 391.Em win 392.It wunderend(win) end underscore mode on 393.Em win 394.It wunderscore(win) start underscore mode on 395.Em win 396.It wvline(win, ch, count) Draw a vertical line of character 397.Em ch 398on window 399.Em win . 400.El 401.Sh HISTORY 402The 403.Nm 404package appeared in 405.Bx 4.0 . 406