All rights reserved.
%sccs.include.redist.roff%
@(#)fns.doc 1.1 (Berkeley) 12/30/92
.Ds .Fd addch ch \*m char ch; .De Add the character .Vn ch on the window at the current \*y. If the character is a newline (\'\en\') the line will be cleared to the end, and the current \*y will be changed to the beginning off the next line if newline mapping is on, or to the next line at the same x co-ordinate if it is off. A return (\'\er\') will move to the beginning of the line on the window. Tabs (\'\et\') will be expanded into spaces in the normal tabstop positions of every eight characters. \*(Es .Ds .Fd addstr str \*m char *str; .De Add the string pointed to by .Vn str on the window at the current \*y. \*(Es In this case, it will put on as much as it can. .Ds .Fd baudrate "" \*m .De Returns the output baud rate of the terminal. This is a system dependent constant (defined in .b <sys/tty.h> on BSD systems, which is included by .b <curses.h> ). .Ds .Fd box win\*,vert\*,hor WINDOW *win; char vert\*,hor; .De
p Draws a box around the window using .Vn vert as the character for drawing the vertical sides, and .Vn hor for drawing the horizontal lines. If scrolling is not allowed, and the window encompasses the lower right-hand corner of the terminal, the corners are left blank to avoid a scroll. .Ds .Fd cbreak "" \*m .De Set or the terminal to cbreak mode. .Ds .Fd clear "" \*m .De Resets the entire window to blanks. If .Vn win is a screen, this sets the clear flag, which will cause a clear-screen sequence to be sent on the next .Fn refresh call. This also moves the current \*y to (0\*,0). .Ds .Fd clearok scr\*,boolf \*m WINDOW *scr; int boolf; .De Sets the clear flag for the screen .Vn scr . If .Vn boolf is TRUE, this will force a clear-screen to be printed on the next .Fn refresh , or stop it from doing so if .Vn boolf is FALSE. This only works on screens, and, unlike .Fn clear , does not alter the contents of the screen. If .Vn scr is .Vn curscr , the next .Fn refresh call will cause a clear-screen, even if the window passed to .Fn refresh is not a screen. .Ds .Fd clrtobot "" \*m .De Wipes the window clear from the current \*y to the bottom. This does not force a clear-screen sequence on the next refresh under any circumstances. \*(Nm .Ds .Fd clrtoeol "" \*m .De Wipes the window clear from the current \*y to the end of the line. \*(Nm .Ds .Fd crmode "" \*m .De Identical to .Fn cbreak . The misnamed macro .Fn crmode and .Fn nocrmode is retained for backwards compatibility with ealier versions of the library. .Ds .Fd delch .De Delete the character at the current \*y. Each character after it on the line shifts to the left, and the last character becomes blank. .Ds .Fd deleteln .De Delete the current line. Every line below the current one will move up, and the bottom line will become blank. The current \*y will remain unchanged. .Ds .Fd delwin win WINDOW *win; .De Deletes the window from existence. All resources are freed for future use by .b calloc (3). If a window has a .Fn subwin allocated window inside of it, deleting the outer window the subwindow is not affected, even though this does invalidate it. Therefore, subwindows should be deleted before their outer windows are. .Ds .Fd echo "" \*m .De Sets the terminal to echo characters. .Ds .Fd endwin .De Finish up window routines before exit. This restores the terminal to the state it was before .Fn initscr (or .Fn gettmode and .Fn setterm ) was called. It should always be called before exiting and before the final calls to .Fn delwin . It does not exit. This is especially useful for resetting tty stats when trapping rubouts via .b signal (2). .Ds .Fd erase "" \*m .De Erases the window to blanks without setting the clear flag. This is analagous to .Fn clear , except that it never causes a clear-screen sequence to be generated on a .Fn refresh . \*(Nm .Ds .Fd erasechar "" \*m .De Returns the erase character for the terminal, .i i.e. , the character used by the user to erase a single character from the input. .Ds .Fd flushok win\*,boolf \*m WINDOW *win; int boolf; .De Normally, .Fn refresh .Fn fflush 's .Vn stdout when it is finished. .Fn flushok allows you to control this. if .Vn boolf is TRUE (\c .i i.e. , non-zero) it will do the .Fn fflush ; if it is FALSE. it will not. .Ds .Fd fullname termbuf\*,name char *termbuf\*,*name; .De .Fn longname fills in .Vn name with the long name of the terminal described by the .b termcap entry in .Vn termbuf . It is generally of little use, but is nice for telling the user in a readable format what terminal we think he has. This is available in the global variable .Vn ttytype . .Vn termbuf is usually set via the termlib routine .Fn tgetent . .Fn fullname is the same as .Fn longname , except that it gives the fullest name given in the entry, which can be quite verbose. .Ds .Fd getcap str "" "char *" char *str; .De Return a pointer to the .b termcap capability described by .Vn str (see .b termcap (5) for details). .Ds .Fd getch "" \*m .De Gets a character from the terminal and (if necessary) echos it on the window. \*(Es Otherwise, the character gotten is returned. If .i noecho has been set, then the window is left unaltered. In order to retain control of the terminal, it is necessary to have one of .i noecho , .i cbreak , or .i rawmode set. If you do not set one, whatever routine you call to read characters will set .i cbreak for you, and then reset to the original mode when finished. .Ds .Fd getstr str \*m char *str; .De Get a string through the window and put it in the location pointed to by .Vn str , which is assumed to be large enough to handle it. It sets tty modes if necessary, and then calls .Fn getch (or .Fn wgetch ) "" win to get the characters needed to fill in the string until a newline or EOF is encountered. The newline stripped off the string. \*(Es .Ds .Fd gettmode .De Get the tty stats. This is normally called by .Fn initscr . .Ds .Fd getyx win\*,y\*,x \*m WINDOW *win; int y\*,x; .De Puts the current \*y of .Vn win in the variables .Vn y and .Vn x . Since it is a macro, not a function, you do not pass the address of .Vn y and .Vn x . .Ds .Fd idlok win\*,boolf WINDOW *win; int boolf; .De Reserved for future use. This will eventually signal to .Fn refresh that it is all right to use the insert and delete line sequences when updating the window. .Ds .Fd inch "" \*m .De Returns the character at the current position on the given window. This does not make any changes to the window. .Ds .Fd initscr .De Initialize the screen routines. This must be called before any of the screen routines are used. It initializes the terminal-type data and such, and without it none of the routines can operate. If standard input is not a tty, it sets the specifications to the terminal whose name is pointed to by .Vn Def\*_term (initialy "dumb"). If the boolean .Vn My\*_term is true, .Vn Def\*_term is always used. If the system supports the .b TIOCGWINSZ .Fn ioctl "" "" 2 call, it is used to get the number of lines and columns for the terminal, otherwise it is taken from the .b termcap description. .Ds .Fd insch c char c; .De Insert .Vn c at the current \*y Each character after it shifts to the right, and the last character disappears. \*(Es .Ds .Fd insertln .De Insert a line above the current one. Every line below the current line will be shifted down, and the bottom line will disappear. The current line will become blank, and the current \*y will remain unchanged. .Ds .Fd killchar "" \*m .De Returns the line kill character for the terminal, .i i.e. , the character used by the user to erase an entire line from the input. .Ds .Fd leaveok win\*,boolf \*m WINDOW *win; int boolf; .De Sets the boolean flag for leaving the cursor after the last change. If .Vn boolf is TRUE, the cursor will be left after the last update on the terminal, and the current \*y for .Vn win will be changed accordingly. If it is FALSE, it will be moved to the current \*y. This flag (initialy FALSE) retains its value until changed by the user. .Ds .Fd longname termbuf\*,name char *termbuf\*,*name; .De .Ds .Fd move y\*,x \*m int y\*,x; .De Change the current \*y of the window to .Vn y\*,x ). ( \*(Es .Ds .Fd mvcur lasty\*,lastx\*,newy\*,newx int lasty\*,lastx\*,newy\*,newx; .De Moves the terminal's cursor from .Vn lasty\*,lastx ) ( to .Vn newy\*,newx ) ( in an approximation of optimal fashion. This routine uses the functions borrowed from .i ex version 2.6. It is possible to use this optimization without the benefit of the screen routines. With the screen routines, this should not be called by the user. .Fn move and .Fn refresh should be used to move the cursor position, so that the routines know what's going on. .Ds .Fd mvwin win\*,y\*,x WINDOW *win; int y, x; .De Move the home position of the window .Vn win from its current starting coordinates to .Vn y\*,x ). ( If that would put part or all of the window off the edge of the terminal screen, .Fn mvwin returns ERR and does not change anything. For subwindows, .Fn mvwin also returns ERR if you attempt to move it off its main window. If you move a main window, all subwindows are moved along with it. .Ds .Fd newwin lines\*,cols\*,begin\*_y\*,begin\*_x "" "WINDOW *" int lines\*,cols\*,begin\*_y\*,begin\*_x; .De Create a new window with .Vn lines lines and .Vn cols columns starting at position .Vn begin\*_y\*,begin\*_x ). ( If either .Vn lines or .Vn cols is 0 (zero), that dimension will be set to .Vn "LINES - begin\*_y" ) ( or .Vn "COLS - begin\*_x" ) ( respectively. Thus, to get a new window of dimensions .Vn LINES \(mu .Vn COLS , use .Fn newwin . "" 0\*,0\*,0\*,0 .Ds .Fd nl "" \*m .De Set the terminal to nl mode, .i i.e. , start/stop the system from mapping .b <RETURN> to .b <LINE-FEED> . If the mapping is not done, .Fn refresh can do more optimization, so it is recommended, but not required, to turn it off. .Ds .Fd nocbreak "" \*m .De Unset the terminal from cbreak mode. .Ds .Fd nocrmode "" \*m .De Identical to .Fn nocbreak . The misnamed macro .Fn nocrmode is retained for backwards compatibility with ealier versions of the library. .Ds .Fd noecho "" \*m .De Turn echoing of characters off. .Ds .Fd nonl "" \*m .De Unset the terminal to from nl mode. See .Fn nl . .Ds .Fd noraw "" \*m .De Unset the terminal from raw mode. See .Fn raw . .Ds .Fd overlay win1\*,win2 WINDOW *win1\*,*win2; .De Overlay .Vn win1 on .Vn win2 . The contents of .Vn win1 , insofar as they fit, are placed on .Vn win2 at their starting \*y. This is done non-destructively, i.e., blanks on .Vn win1 leave the contents of the space on .Vn win2 untouched. .Ds .Fd overwrite win1\*,win2 WINDOW *win1\*,*win2; .De Overwrite .Vn win1 on .Vn win2 . The contents of .Vn win1 , insofar as they fit, are placed on .Vn win2 at their starting \*y. This is done destructively, .i i.e. , blanks on .Vn win1 become blank on .Vn win2 . .Ds .Fd printw fmt\*,arg1\*,arg2\*,... char *fmt; .De Performs a .Fn printf on the window starting at the current \*y. It uses .Fn addstr to add the string on the window. It is often advisable to use the field width options of .Fn printf to avoid leaving things on the window from earlier calls. \*(Es .Ds .Fd \*_putchar c char c; .De Put out a character using the .Fn putchar macro. This function is used to output every character that .b curses generates. Thus, it can be redefined by the user who wants to do non-standard things with the output. It is named with an initial \*(lq\*_\*(rq because it usually should be invisible to the programmer. .Ds .Fd raw "" \*m .De Set the terminal to raw mode. On version 7 n \** .(f \** n is a trademark of Bell Laboratories. .)f this also turns of newline mapping (see .Fn nl ). .Ds .Fd refresh "" \*m .De Synchronize the terminal screen with the desired window. If the window is not a screen, only that part covered by it is updated. \*(Es In this case, it will update whatever it can without causing the scroll. As a special case, if .Fn wrefresh is called with the window .Vn curscr the screen is cleared and repainted as it is currently. This is very useful for allowing the redrawing of the screen when the user has garbage dumped on his terminal. .Ds .Fd resetty "" \*m .De .Fn resetty restores them to what .Fn savetty stored. These functions are performed automatically by .Fn initscr and .Fn endwin . .Ds .Fd savetty "" \*m .De .Fn savetty saves the current tty characteristic flags. See .Fn resetty . .Ds .Fd scanw fmt\*,arg1\*,arg2\*,... char *fmt; .De Perform a .Fn scanf through the window using .Vn fmt . It does this using consecutive .Fn getch 's (or .Fn wgetch 's). "" win \*(Es .Ds .Fd scroll win WINDOW *win; .De Scroll the window upward one line. This is normally not used by the user. .Ds .Fd scrollok win\*,boolf \*m WINDOW *win; int boolf; .De Set the scroll flag for the given window. If .Vn boolf is FALSE, scrolling is not allowed. This is its default setting. .Ds .Fd setterm name char *name; .De Set the terminal characteristics to be those of the terminal named .Vn name , getting the terminal size from the .b TIOCGWINSZ .Fn ioctl "" "" 2 if it exists, otherwise from the environment. This is normally called by .Fn initscr . .Ds .Fd standend "" \*m .De End standout mode initiated by .Fn standout . .Ds .Fd standout "" \*m .De Causes any characters added to the window to be put in standout mode on the terminal (if it has that capability). .Ds .Fd subwin win\*,lines\*,cols\*,begin\*_y\*,begin\*_x "" "WINDOW *" WINDOW *win; int lines\*,cols\*,begin\*_y\*,begin\*_x; .De Create a new window with .Vn lines lines and .Vn cols columns starting at position .Vn begin\*_y\*,begin\*_x ) ( inside the window .i win . This means that any change made to either window in the area covered by the subwindow will be made on both windows. .Vn begin\*_y\*,begin\*_x are specified relative to the overall screen, not the relative (0\*,0) of .Vn win . If either .Vn lines or .Vn cols is 0 (zero), that dimension will be set to .Vn "LINES - begin\*_y" ) ( or .Vn "COLS - begin\*_x" ) ( respectively. .Ds .Fd touchline win\*,y\*,startx\*,endx WINDOW *win; int y\*,startx\*,endx; .De This function performs a function similar to .Fn touchwin on a single line. It marks the first change for the given line to be .Vn startx , if it is before the current first change mark, and the last change mark is set to be .Vn endx if it is currently less than .Vn endx . .Ds .Fd touchoverlap win1\*,win2 WINDOW *win1, *win2; .De Touch the window .Vn win2 in the area which overlaps with .Vn win1 . If they do not overlap, no changes are made. .Ds .Fd touchwin win WINDOW *win; .De Make it appear that the every location on the window has been changed. This is usually only needed for refreshes with overlapping windows. .Ds .Fd unctrl ch \*m char ch; .De This is actually a debug function for the library, but it is of general usefulness. It returns a string which is a representation of .Vn ch . Control characters become their upper-case equivalents preceded by a "^". Other letters stay just as they are. To use .Fn unctrl , you may have to have .b #include <unctrl.h> in your file. .Ds .Fd tstp .De If the new .b tty (4) driver is in use, this function will save the current tty state and then put the process to sleep. When the process gets restarted, it restores the tty state and then calls .Fn wrefresh "" "" curscr to redraw the screen. .Fn initscr sets the signal SIGTSTP to trap to this routine. .Ds .Fd vwprintw win\*,fmt\*,ap WINDOW *win; const char *fmt; va_list ap; .De Identical to .Fn printw except that it takes both a window specification and a pointer to a variable length argument list. .Ds .Fd vwscanw win\*,fmt\*,ap WINDOW *win; const char *fmt; va_list ap; .De Identical to .Fn scanw except that it takes both a window specification and a pointer to a variable length argument list. .pp The following functions differ from the standard functions only in their specification of a window, rather than the use of the default .Vn stdscr. .Ds .Fd waddch win\*,ch WINDOW *win; char ch; .Dg .Ds .Fd waddstr win\*,str WINDOW *win; char *str; .Dg .Ds .Fd wclear win WINDOW *win; .Dg .Ds .Fd wclrtobot win WINDOW *win; .Dg .Ds .Fd wclrtoeol win WINDOW *win; .Dg .Ds .Fd wdelch win WINDOW *win; .Dg .Ds .Fd wdeleteln win WINDOW *win; .Dg .Ds .Fd werase win WINDOW *win; .Dg .Ds .Fd wgetch win WINDOW *win; .Dg .Ds .Fd wgetstr win\*,str WINDOW *win; char *str; .Dg .Ds .Fd winch win \*m WINDOW *win; .Dg .Ds .Fd winsch win\*,c WINDOW *win; char c; .Dg .Ds .Fd winsertln win WINDOW *win; .Dg .Ds .Fd wmove win\*,y\*,x WINDOW *win; int y\*,x; .Dg .Ds .Fd wprintw win\*,fmt\*,arg1\*,arg2\*,... WINDOW *win; char *fmt; .Dg .Ds .Fd wrefresh win WINDOW *win; .Dg .Ds .Fd wscanw win\*,fmt\*,arg1\*,arg2\*,... WINDOW *win; char *fmt; .Dg .Ds .Fd wstandend win WINDOW *win; .Dg .Ds .Fd wstandout win WINDOW *win; .Dg