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