.TH CURSES 3 .SH NAME curses \- screen/window management library .SH SYNOPSIS cc demo.c -lcurses .SH DESCRIPTION Curses is a library of screen and window management routines. It is modeled after the UNIX curses and ncurses libraries. Normally, programs written for curses should be easily ported to UNIX, and vice versa. .PP To use the routines, the function initscr() must first be called. This creates two 'windows' for the user: stdscr and curscr. Stdscr is the default window for the user to make changes on, and curscr reflects the current contents of the physical display screen. The user writes or edits the stdscr window to his liking, then calls the refresh() function to make curscr and the physical screen look like stdscr. When the user program terminates, it should call the endwin() function to restore things to normal. .PP There are all sorts of window manipulation routines available to the programmer: auxiliary windows may be created, edited, moved and deleted. The terminal may be set in many different modes, output text may be attributed with blink, blank, bold and reverse attributes. Screen colors may also be set, foreground and background. There are window-specific printf- and scanf-like routines, routines for scrolling, box-drawing, window overlaying, clearing routines etc. .PP For more and detailed information, see the library source codes. All curses functions are preceded by a complete description. .SH FUNCTIONS Below is a list over the available functions, together with a brief description of what they do. In general, functions whose names start with 'w' differ from the one without 'w' (like wmove vs. move) signify that a specific window is used. Without a 'w', sdtscr is implied. The functions that start with 'mv' before the 'genereic' function name signify that a cursor motion should be made before the actual work. 'mv' and 'w' combine as expected. .PP Most routines that return an int will return the manifest constant ERR if there is a failure during execution. Routines that return a char actually return an int, so that ERR does not conflict with the character code 0xff. All characters from 0 to 0xff are allowed for usage with curses. .PP Some routines, like {mv}{w} printw() and {mv}{w}scanw() return a meaningful positive value if the operation is successful. .PP The curses package uses some predefined types, variables and manifest constants that are also available to the programmer. There are also a few globally accessible variables that should not be touched by the application program. Those untouchable variables have names starting with an underscore (_) to avoid conflicts. The user-accessible types, variables and constants are (there are a number of other constants defining character attribute names and function key names - consult for details): .sp .nf .ta 3i (manifest constants) .RS TRUE\tboolean true FALSE\tboolean false ERR\tunsuccessfull operation OK\tsuccessfull operation .RE .sp (types) .RS WINDOW\ta window structure type bool\tboolean flag type .RE .sp (variables) .RS WINDOW curscr\tphysical display image WINDOW stdscr\tdefault user drawing board int LINES\tterminal height int COLS\tterminal width int NONL\t\\n causes CR and LF when TRUE .RE .sp .fi The following is an alphabetical list of the curses functions, together with their types, parameters and a short comment for each (win is a window, ch, vc, hc are characters, buf is a character buffer, attrs is an attribute bit map, bf is a boolean flag. Note that `characters' in this context usually can have 16 bits): .nf .sp int waddch(win,ch)\tput char in stdscr int addch(ch) int mvaddch(y,x,ch) int mvwaddch(win,y,x,ch) int waddstr(win,str)\tput string in stdscr int addstr(str) int mvaddstr(y,x,str) int mvwaddstr(win,y,x,str) void wattroff(win,attrs)\tclear attribute(s) in window void attroff(attrs) void wattron(win,attrs)\tadd attribute(s) in window void attron(attrs) void wattrset(win,attrs)\tset window char attributes void attrset(attrs) int baudrate()\tdummy for compatibility void beep()\tring the bell or visible bell if no bell available void flash()\tflash terminal screen or rings bell if no visible bell available void wbox(win,miny,minx,maxy,maxx,vc,hc)\tbox in a window, with given characters void box(win,vc,hc) void cbreak()\tset terminal cbreak mode void wclear(win)\tclear stdscr void clear() void clearok(win,bf)\tmarks window for screen clear int wclrtobot(win)\tclear from cursor to end of line and all lines down this line int clrtobot() int mvclrtoeol(y,x) int mvwclrtobot(win,y,x) int wclrtoeol(win)\tclear from cursor to end of line int clrtoeol() int mvclrtoeol(y,x) int mvwclrtoeol(win,y,x) int wdelch(win)\tdelete a char in a window int delch() int mvdelch(y,x) int mvwdelch(win,y,x) int wdeleteln(win)\tdelete a line in a window int deleteln() int mvdeleteln(y,x) int mvwdeleteln(win,y,x) void delwin(win)\tdelete a window or a subwindow void doupdate()\tupdate physical screen void echo()\tset terminal echo mode int endwin()\tcleanup and curses finitialization void werase(win)\terase a window void erase() int erasechar()\treturn char delete character int fixterm()\tdummy for compatibility void flushinp()\tkill pending keyboard input int wgetch(win)\tget char via a window int getch() int mvgetch(y,x) int mvwgetch(win,y,x) int wgetstr(win,str)\tget string via window to a buffer int getstr(str) int mvgetstr(y,x,str) int mvwgetstr(win,y,x,str) void getyx(win,y,x)\tget a window's cursor position int gettmode()\tdummy for compatibility void idlok(win,bf)\tdummy for compatibility WINDOW *initscr()\tcurses initialization (ret stdscr or NULL) int winch(win)\tget char at window cursor int inch() int mvinch(y,x) int mvwinch(win,y,x) int winsch(win,ch)\tinsert character in a window int insch(ch) int mvinsch(y,x,ch) int mvwinsch(win,y,x,ch) int winsertln(win)\tinsert new line in a window int insertln() int mvinsertln(y,x) int mvwinsertln(win,y,x) void keypad(win,bf)\tmarks a window for keypad usage int killchar()\treturn line delete character char *longname()\treturns terminal description string void leaveok(win,bf)\tmarks window for cursor 'update leave' void meta(win,bf)\tmarks window for meta int move(y,x)\tmove cursor in stdscr int mvcur(oldy,oldx,y,x)\tmove terminal cursor to int mvprintw(y,x,fmt,args)\tmove & print string in stdscr int mvscanw(y,x,fmt,args)\tmove & get values via stdscr int mvwin(win,y,x)\tmove window on physical screen int mvwprintw(win,x,y,fmt,args)\tmove & print string in a window int mvwscanw(win,y,x,fmt,args)\tmove & get values via a window WINDOW *newwin(lines,cols,begy,begx)\tcreate a new window void nl()\tset terminal cr-crlf mapping mode void nocbreak()\tunset terminal cbreak mod void nodelay(win,bf)\tmarks window for no input wait void noecho()\tunset terminal echo mode void nonl()\tunset terminal cr-crlf mapping mode void noraw()\tunset raw terminal mode void overlay(win1,win2)\toverlay one window on another void overwrite(win1,win2)\toverwrite one window on another int printw(fmt,args)\tprint string in stdscr void raw()\tset raw terminal mode void refrbrk(bf)\tset screen update break mode void refresh()\trefresh stdscr int resetterm()\tdummy for compatibility int resetty()\trestore terminal I/O modes int saveoldterm()\tdummy for compatibility int saveterm()\tdummy for compatibility int savetty()\tsave terminal I/O modes int scanw(fmt,args)\tget values via stdscr void scroll(win)\tscroll scrolling region of a window void scrollok(win,bf)\tmarks a window to allow scroll void setcolors(A_COLOR(for,back))\tsets the forground and background \tcolors of stdscr void set_curs(visibility)\t0 for invisible, 1 for visible, 2 for good \tvisible int setsrcreg(miny,maxy)\tdefine stdscr's scroll region int setterm()\tdummy for compatibility int setupterm(term,fd,errret)\tset up terminal void standend()\tstart normal chars in stdscr void standout()\tstart standout chars in stdscr WINDOW *subwin(win,lines,cols,begy,begx) \tcreate a sub-window in window win int tabsize(ts)\tset/get tabsize of stdscr void touchwin(win)\tmark a window as totally modified char *unctrl(ch)\tchar-to-string converter int wmove(win,y,x)\tmove cursor in a window void wnoutrefresh(win)\tcreate internal screen image int wprintw(win,fmt,args)\tprint string in a window void wrefresh(win)\trefresh window int wscanw(win,fmt,args)\tget values via a window void wsetcolors(win,A_COLOR(for,back))\tsets the forground and \tbackground colors of the specified window int wsetsrcreg(win,miny,maxy)\tdefine a window's scrolling region void wstandend(win)\tstart normal chars in window void wstandout(win)\tstart standout chars in window int wtabsize(win,ts)\tset/get tabsize of a window .SH BUGS Function keys are not available under the MINIX version.