1.\" $NetBSD: curses.3,v 1.37 2002/03/25 13:53:43 wiz 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 296background colors of pair 297.It printw(fmt,arg1,arg2,...) printf on 298.Em stdscr 299.It raw() set raw mode 300.It refresh() make current screen look like 301.Em stdscr 302.It reset_prog_mode() restore program (in curses) terminal modes 303.It reset_shell_mode() restore shell (not in curses) terminal modes 304.It resetty() reset tty flags to stored value 305.It resizeterm(lines,cols) resize the curses terminal, application must 306redraw the screen contents after this call 307.It savetty() stored current tty flags 308.It scanw(fmt,arg1,arg2,...) scanf through 309.Em stdscr 310.It scrl(n) scroll 311.Em stdscr 312n lines 313.It scroll(win) scroll 314.Em win 315one line 316.It scrollok(win,boolf) set scroll flag for 317.Em win 318.It setscrreg(top, bottom) set scrolling region on 319.Em stdscr 320.It set_term(screen) sets the curses screen to the given one. 321Returns the previous screen. 322.It setterm(name) set term variables for name 323.It standend() end standout mode 324.It standout() start standout mode 325.It start_color() initialise color 326.It subwin(win,lines,cols,begin_y,begin_x)\ create a subwindow 327.It timeout(delay) set blocking or non-blocking read for 328.Em stdscr 329.It touchline(win,y,sx,ex) mark line 330.Em y 331.Em sx 332through 333.Em sy 334as changed 335.It touchoverlap(win1,win2) mark overlap of 336.Em win1 337on 338.Em win2 339as changed 340.It touchwin(win) \*(lqchange\*(rq all of 341.Em win 342.It unctrl(ch) printable version of 343.Em ch 344.It underend() end underscore mode 345.It underscore() start underscore mode 346.It ungetch(ch) Put character back onto input queue. 347.It untouchwin(win) Make window appear not to have been modified. 348.It vline(ch, count) Draw a vertical line of character 349.Em ch . 350.It waddch(win,ch) add char to 351.Em win 352.It waddstr(win,str) add string to 353.Em win 354.It wattron(win,attribute) turn on attribute modes for 355.Em win 356.It wattroff(win,attribute) turn off attribute modes for 357.Em win 358.It wattrset(win,attribute) set attribute modes for 359.Em win 360.It wbkgd(win, ch) set background rendition for 361.Em win 362and apply this rendition to 363.Em win 364.It wbkgdset(win, ch) set background rendition for 365.Em win 366.It wborder(win,ls,rs,ts,bs,tl,tr,bl,br) draw a border around 367.Em win 368.It wclear(win) clear 369.Em win 370.It wclrtobot(win) clear to bottom of 371.Em win 372.It wclrtoeol(win) clear to end of line on 373.Em win 374.It wdelch(win) delete char from 375.Em win 376.It wdeleteln(win) delete line from 377.Em win 378.It werase(win) erase 379.Em win 380.It wgetch(win) get a char through 381.Em win 382.It wgetnstr(win, str, len) get a string of maximun n characters through 383.Em win 384.It wgetstr(win, str) get a string through 385.Em win 386.It whline(win, ch, count) Draw a horizontal line of character 387.Em ch 388on window 389.Em win . 390.It winch(win) get char at current (y,x) in 391.Em win 392.It winchnstr(win, chstr, n) get an array of characters from 393.Em win 394.It winchstr(win, chstr) get an array of characters from 395.Em win 396.It winnstr(win, str, n) get a string of characters from 397.Em win 398.It winsch(win,c) insert char into 399.Em win 400.It winsdelln(win,n) insert/delete n lines on 401.Em win 402.It winsertln(win) insert line into 403.Em win 404.It winstr(win,str) get a string of characters from 405.Em win 406.It wmove(win,y,x) set current (y,x) co-ordinates on 407.Em win 408.It wnoutrefresh(win) add 409.Em win 410to virtual screen 411.It wprintw(win,fmt,arg1,arg2,...)\ printf on 412.Em win 413.It wrefresh(win) make screen look like 414.Em win 415.It wresize(win,lines,cols) resize 416.Em win 417.It wscanw(win,fmt,arg1,arg2,...)\ scanf through 418.Em win 419.It wscrl(win,n) scroll 420.Em win 421n lines 422.It wsetscrreg(win, top, bottom) set scrolling region on 423.Em win 424.It wstandend(win) end standout mode on 425.Em win 426.It wstandout(win) start standout mode on 427.Em win 428.It wtimeout(win,delay) set blocking or non-blocking read for 429.Em win 430.It wtouchln(win, line, n, changed) If 431.Em changed 432is 1 then touch 433.Em n 434lines starting at 435.Em line 436in window 437.Em win . 438If 439.Em changed 440is 0 then untouch 441.Em n 442lines starting at 443.Em line 444in window 445.Em win 446.It wunderend(win) end underscore mode on 447.Em win 448.It wunderscore(win) start underscore mode on 449.Em win 450.It wvline(win, ch, count) Draw a vertical line of character 451.Em ch 452on window 453.Em win . 454.El 455.Sh HISTORY 456The 457.Nm 458package appeared in 459.Bx 4.0 . 460