curses(3)
NAME
curses - screen/window management library
SYNOPSIS
cc demo.c -lcurses
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.
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.
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.
For more and detailed information, see the library source codes. All
curses functions are preceded by a complete description.
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.
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.
Some routines, like {mv}{w} printw() and {mv}{w}scanw() return a
meaningful positive value if the operation is successful.
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
<curses.h> for details):
(manifest constants)
TRUE boolean true
FALSE boolean false
ERR unsuccessfull operation
OK successfull operation
(types)
WINDOW a window structure type
bool boolean flag type
(variables)
WINDOW curscr physical display image
WINDOW stdscr default user drawing board
int LINES terminal height
int COLS terminal width
int NONL \n causes CR and LF when TRUE
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):
int waddch(win,ch) put char in stdscr
int addch(ch)
int mvaddch(y,x,ch)
int mvwaddch(win,y,x,ch)
int waddstr(win,str) put string in stdscr
int addstr(str)
int mvaddstr(y,x,str)
int mvwaddstr(win,y,x,str)
void wattroff(win,attrs) clear attribute(s) in window
void attroff(attrs)
void wattron(win,attrs) add attribute(s) in window
void attron(attrs)
void wattrset(win,attrs) set window char attributes
void attrset(attrs)
int baudrate() dummy for compatibility
void beep() ring the bell or visible bell if no
bell available
void flash() flash terminal screen or rings bell
if no visible bell available
void wbox(win,miny,minx,maxy,maxx,vc,hc) box in a window, with given
characters
void box(win,vc,hc)
void cbreak() set terminal cbreak mode
void wclear(win) clear stdscr
void clear()
void clearok(win,bf) marks window for screen clear
int wclrtobot(win) clear 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) clear from cursor to end of line
int clrtoeol()
int mvclrtoeol(y,x)
int mvwclrtoeol(win,y,x)
int wdelch(win) delete a char in a window
int delch()
int mvdelch(y,x)
int mvwdelch(win,y,x)
int wdeleteln(win) delete a line in a window
int deleteln()
int mvdeleteln(y,x)
int mvwdeleteln(win,y,x)
void delwin(win) delete a window or a subwindow
void doupdate() update physical screen
void echo() set terminal echo mode
int endwin() cleanup and curses finitialization
void werase(win) erase a window
void erase()
int erasechar() return char delete character
int fixterm() dummy for compatibility
void flushinp() kill pending keyboard input
int wgetch(win) get char via a window
int getch()
int mvgetch(y,x)
int mvwgetch(win,y,x)
int wgetstr(win,str) get 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) get a window's cursor position
int gettmode() dummy for compatibility
void idlok(win,bf) dummy for compatibility
WINDOW *initscr() curses initialization (ret stdscr or
NULL)
int winch(win) get char at window cursor
int inch()
int mvinch(y,x)
int mvwinch(win,y,x)
int winsch(win,ch) insert character in a window
int insch(ch)
int mvinsch(y,x,ch)
int mvwinsch(win,y,x,ch)
int winsertln(win) insert new line in a window
int insertln()
int mvinsertln(y,x)
int mvwinsertln(win,y,x)
void keypad(win,bf) marks a window for keypad usage
int killchar() return line delete character
char *longname() returns terminal description string
void leaveok(win,bf) marks window for cursor 'update
leave'
void meta(win,bf) marks window for meta
int move(y,x) move cursor in stdscr
int mvcur(oldy,oldx,y,x) move terminal cursor to <y,x>
int mvprintw(y,x,fmt,args) move & print string in stdscr
int mvscanw(y,x,fmt,args) move & get values via stdscr
int mvwin(win,y,x) move window on physical screen
int mvwprintw(win,x,y,fmt,args) move & print string in a window
int mvwscanw(win,y,x,fmt,args) move & get values via a window
WINDOW *newwin(lines,cols,begy,begx) create a new window
void nl() set terminal cr-crlf mapping mode
void nocbreak() unset terminal cbreak mod
void nodelay(win,bf) marks window for no input wait
void noecho() unset terminal echo mode
void nonl() unset terminal cr-crlf mapping mode
void noraw() unset raw terminal mode
void overlay(win1,win2) overlay one window on another
void overwrite(win1,win2) overwrite one window on another
int printw(fmt,args) print string in stdscr
void raw() set raw terminal mode
void refrbrk(bf) set screen update break mode
void refresh() refresh stdscr
int resetterm() dummy for compatibility
int resetty() restore terminal I/O modes
int saveoldterm() dummy for compatibility
int saveterm() dummy for compatibility
int savetty() save terminal I/O modes
int scanw(fmt,args) get values via stdscr
void scroll(win) scroll scrolling region of a window
void scrollok(win,bf) marks a window to allow scroll
void setcolors(A_COLOR(for,back)) sets the forground and background
colors of stdscr
void set_curs(visibility) 0 for invisible, 1 for visible, 2 for
good
visible
int setsrcreg(miny,maxy) define stdscr's scroll region
int setterm() dummy for compatibility
int setupterm(term,fd,errret) set up terminal
void standend() start normal chars in stdscr
void standout() start standout chars in stdscr
WINDOW *subwin(win,lines,cols,begy,begx)
create a sub-window in window win
int tabsize(ts) set/get tabsize of stdscr
void touchwin(win) mark a window as totally modified
char *unctrl(ch) char-to-string converter
int wmove(win,y,x) move cursor in a window
void wnoutrefresh(win) create internal screen image
int wprintw(win,fmt,args) print string in a window
void wrefresh(win) refresh window
int wscanw(win,fmt,args) get values via a window
void wsetcolors(win,A_COLOR(for,back)) sets the forground and
background colors of the specified
window
int wsetsrcreg(win,miny,maxy) define a window's scrolling region
void wstandend(win) start normal chars in window
void wstandout(win) start standout chars in window
int wtabsize(win,ts) set/get tabsize of a window
BUGS
Function keys are not available under the MINIX version.