1.\" $NetBSD: curses.3,v 1.31 2001/04/20 13:06:35 jdc 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 getnstr(str, len) get a string of maximun len characters through 164.Em stdscr 165.It getstr(str) get a string through 166.Em stdscr 167.It gettmode() get tty modes 168.It getyx(win,y,x) get (y,x) co-ordinates 169.It has_colors() check if terminal has colors 170.It has_ic() check if terminal has insert/delete character 171.It has_il() check if terminal has insert/delete line 172.It hline(ch, count) draw a horizontal line of character ch. 173.It idlok(win,boolf) set insert/deleteln flags for 174.Em win 175.It inch() get char at current (y,x) co-ordinates 176.It inchnstr(chstr, n) get an array of characters from 177.Em stdscr 178.It inchstr(chstr) get an array of characters from 179.Em stdscr 180.It innstr(str, n) get a string of characters from 181.Em stdscr 182.It init_color(c, r, g, b) set rgb values of color 183.It init_pair(p, f, b) set foreground and background colors of pair 184.It initscr() initialize screens 185.It insch(c) insert a char 186.It insdelln(n) insert/delete n lines on 187.Em stdstr 188.It insertln() insert a line 189.It instr(str) get a string of characters from 190.Em stdscr 191.It intrflush(win,boolf) set flush on interrupt terminal mode 192.It is_linetouched(win, line) check if line has been modified since 193last refresh. 194.It is_wintouched(win) Check if window has been modified since last 195refresh. 196.It isendwin() check if endwin() or wrefresh() was called latest 197.It keypad(win,boolf) set keypad flag for 198.Em win 199.It killchar() Return the terminal kill character. 200.It leaveok(win,boolf) set leave flag for 201.Em win 202.It longname(termbuf,name) get long name from 203.Em termbuf 204.It meta(win,boolf) turn terminal meta mode on and off. Note 205.Em win 206is always ignored. 207.It move(y,x) move to (y,x) on 208.Em stdscr 209.It mvcur(lasty,lastx,newy,newx) actually move cursor 210.It mvgetnstr(str, len) move to 211.Em y , 212.Em x 213and get a string of maximun n characters through 214.Em stdscr 215.It mvgetstr(str, n) move to 216.Em y , 217.Em x 218and get a string through 219.Em stdscr 220.It mvhline(y, x, ch, count) move to 221.Em y , 222.Em x 223and draw a horizontal line of character 224.Em ch 225for 226.Em count 227characters. 228.It mvvline(y, x, ch, count) move to 229.Em y , 230.Em x 231and draw a vertical line of character 232.Em ch 233for 234.Em count 235characters. 236.It mvwgetnstr(str, len) move to 237.Em y , 238.Em x 239and get a string of maximun n characters through 240.Em win 241.It mvwgetstr(str, n) move to 242.Em y , 243.Em x 244and get a string through 245.Em win 246.It mvwhline(win, y, x, ch, count) move to 247.Em y , 248.Em x 249and draw a horizontal line of character 250.Em ch 251for 252.Em count 253characters on window 254.Em win . 255.It mvwvline(win, y, x, ch, count) move to 256.Em y , 257.Em x 258and draw a vertical line of character 259.Em ch 260for 261.Em count 262characters on window 263.Em win . 264.It napms(ms) sleep for 265.Em ms 266milliseconds. 267.It newwin(lines,cols,begin_y,begin_x)\ create a new window 268.It nl() set newline mapping 269.It nocbreak() unset cbreak mode 270.It nodelay(win,boolf) unset blocking reads for 271.Em win 272.It noecho() unset echo mode 273.It nonl() unset newline mapping 274.It noraw() unset raw mode 275.It notimeout(win, boolf) unset infinite timeout on keypad assembly for 276.Em win 277.It overlay(win1,win2) overlay win1 on win2 278.It overwrite(win1,win2) overwrite win1 on top of win2 279.It pair_content(p, r, g, b) get foreground and background colors of pair 280.It printw(fmt,arg1,arg2,...) printf on 281.Em stdscr 282.It raw() set raw mode 283.It refresh() make current screen look like 284.Em stdscr 285.It reset_prog_mode() restore program (in curses) terminal modes 286.It reset_shell_mode() restore shell (not in curses) terminal modes 287.It resetty() reset tty flags to stored value 288.It savetty() stored current tty flags 289.It scanw(fmt,arg1,arg2,...) scanf through 290.Em stdscr 291.It scrl(n) scroll 292.Em stdscr 293n lines 294.It scroll(win) scroll 295.Em win 296one line 297.It scrollok(win,boolf) set scroll flag for 298.Em win 299.It setscrreg(top, bottom) set scrolling region on 300.Em stdscr 301.It setterm(name) set term variables for name 302.It standend() end standout mode 303.It standout() start standout mode 304.It start_color() initialise color 305.It subwin(win,lines,cols,begin_y,begin_x)\ create a subwindow 306.It timeout(delay) set blocking or non-blocking read for 307.Em stdscr 308.It touchline(win,y,sx,ex) mark line 309.Em y 310.Em sx 311through 312.Em sy 313as changed 314.It touchoverlap(win1,win2) mark overlap of 315.Em win1 316on 317.Em win2 318as changed 319.It touchwin(win) \*(lqchange\*(rq all of 320.Em win 321.It unctrl(ch) printable version of 322.Em ch 323.It underend() end underscore mode 324.It underscore() start underscore mode 325.It ungetch(ch) Put character back onto input queue. 326.It untouchwin(win) Make window appear not to have been modified. 327.It vline(ch, count) Draw a vertical line of character 328.Em ch . 329.It waddch(win,ch) add char to 330.Em win 331.It waddstr(win,str) add string to 332.Em win 333.It wattron(win,attribute) turn on attribute modes for 334.Em win 335.It wattroff(win,attribute) turn off attribute modes for 336.Em win 337.It wattrset(win,attribute) set attribute modes for 338.Em win 339.It wbkgd(win, ch) set background rendition for 340.Em win and apply this rendition to 341.Em win 342.It wbkgdset(win, ch) set background rendition for 343.Em win 344.It wborder(win,ls,rs,ts,bs,tl,tr,bl,br) draw a border around 345.Em win 346.It wclear(win) clear 347.Em win 348.It wclrtobot(win) clear to bottom of 349.Em win 350.It wclrtoeol(win) clear to end of line on 351.Em win 352.It wdelch(win) delete char from 353.Em win 354.It wdeleteln(win) delete line from 355.Em win 356.It werase(win) erase 357.Em win 358.It wgetch(win) get a char through 359.Em win 360.It wgetnstr(win, str, len) get a string of maximun n characters through 361.Em win 362.It wgetstr(win, str) get a string through 363.Em win 364.It whline(win, ch, count) Draw a horizontal line of character 365.Em ch 366on window 367.Em win . 368.It winch(win) get char at current (y,x) in 369.Em win 370.It winchnstr(win, chstr, n) get an array of characters from 371.Em win 372.It winchstr(win, chstr) get an array of characters from 373.Em win 374.It winnstr(win, str, n) get a string of characters from 375.Em win 376.It winsch(win,c) insert char into 377.Em win 378.It winsdelln(win,n) insert/delete n lines on 379.Em win 380.It winsertln(win) insert line into 381.Em win 382.It winstr(win,str) get a string of characters from 383.Em win 384.It wmove(win,y,x) set current (y,x) co-ordinates on 385.Em win 386.It wnoutrefresh(win) add 387.Em win 388to virtual screen 389.It wprintw(win,fmt,arg1,arg2,...)\ printf on 390.Em win 391.It wrefresh(win) make screen look like 392.Em win 393.It wscanw(win,fmt,arg1,arg2,...)\ scanf through 394.Em win 395.It wscrl(win,n) scroll 396.Em win 397n lines 398.It wsetscrreg(win, top, bottom) set scrolling region on 399.Em win 400.It wstandend(win) end standout mode on 401.Em win 402.It wstandout(win) start standout mode on 403.Em win 404.It wtimeout(win,delay) set blocking or non-blocking read for 405.Em win 406.It wtouchln(win, line, n, changed) If 407.Em changed 408is 1 then touch 409.Em n 410lines starting at 411.Em line 412in window 413.Em win . 414If 415.Em changed 416is 0 then untouch 417.Em n 418lines starting at 419.Em line 420in window 421.Em win 422.It wunderend(win) end underscore mode on 423.Em win 424.It wunderscore(win) start underscore mode on 425.Em win 426.It wvline(win, ch, count) Draw a vertical line of character 427.Em ch 428on window 429.Em win . 430.El 431.Sh HISTORY 432The 433.Nm 434package appeared in 435.Bx 4.0 . 436