Category : C Source Code
Archive   : CURSESNT.ZIP
Filename : CURSES.3

CURSES(3) MS-DOS Programmer's Manual CURSES(3)

NAME
curses - screen/window management library

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
PCcurses should be easily ported to UNIX, and vice versa.

To use the routines, the function initscr() must first be called. This cre-
ates 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 std-
scr 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 pro-
grammer: 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. There are window-specific
printf- and scanf-like routines, routines for scrolling, box-drawing, win-
dow overlaying, clearing routines etc. Curses also handles terminal func-
tion keys, which is enables by calling the keypad() function.

The handling of character attributes is different on MGA, CGA and Hercules
adapters. The package has been tested with them all. EGA has not been tes-
ted, but should also work except for special screen modes.

For more and detailed information, see the library source codes. All curses
functions are preceded by a brief but complete description.

COMPILING
All programs that use curses facilities should include the file ,
and during linking, the library ?curses.lib should be specified to the lin-
ker ('?' is 's', 'c' 'm' or 'l' for small, compact, medium or large memory
model respectively).

FUNCTIONS
Below is a list over the available functions, together with a brief de-
scription 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 IBM PC characters from 0 to 0xff are allowed for usage with curses.
There are (non-portable) character output routines to write the special
IBM fonts for characters with ASCII code less than 0x20 (control charac-
ters).

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 con-
stants that are also available to the programmer. For example, the ERR and
OK macros should be used to test for failure of curses functions. Don't use
the numerical values, since those are different for different versions of
curses!

There are also a few globally accessible variables that should not be tou-
ched 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 the
and include files 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

The following is an alphabetical list of the curses functions, together
with their types, parameters and a short comment for each. Win is a win-
dow; ch, l, r, t, b, tl, tr, bl and br are characters; buf is a character
buffer; attrs is an attribute bit map; bf is a boolean flag. Note that
`character' return values in this context usually are 16 bits. Guaranteed
portable functions are marked with an asterisk (*):


* int addch(ch) put char in stdscr
int addrawch(ch) put raw char in stdscr
* int addstr(str) put string in stdscr
void attroff(attrs) clear attribute(s) in stdscr
void attron(attrs) add attribute(s) in stdscr
void attrset(attrs) set stdscr char attributes
int baudrate() dummy for compatibility
void beep() ring the bell
void border(l,r,t,b,tl,tr,bl,br) Set non-std box characters
* void box(win,l,t) box in a window, with given characters
* void cbreak() set terminal cbreak mode
* void clear() clear stdscr
* void clearok(win,bf) marks window for screen clear
* int clrtobot() clear end of stdscr
* int clrtoeol() clear end of line in stdscr
* void crmode() set terminal cbreak mode
void cursoff() turns off hardware cursor
void curson() turns on hardware cursor
void def_prog_mode() save TTY modes
void def_shell_mode() compatibility dummy
* int delch() delete a char in stdscr
* int deleteln() delete a line in stdscr
* 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 erase() erase stdscr
int erasechar() return char delete character
int fixterm() dummy for compatibility
void flash() flash terminal screen
void flushinp() kill pending keyboard input
* int getch() (#def macro) get character via stdscr
* int getstr(buf) get string via stdscr to a buffer
* void getyx(win,y,x) get a window's cursor position
* int gettmode() dummy for compatibility
void idlok(win,bf) dummy for compatibility
* int initscr() curses initialization (ret 1 if OK)
* int inch() get char at stdscr cursor
* int insch(ch) insert character in stdscr
int insrawch(ch) insert raw character in stdscr
* int insertln() insert an empty line in stdscr
void keypad(win,bf) marks a window for keypad usage
int killchar() return line delete character
* void leaveok(win,bf) marks window for cursor 'update leave'
* char *longname() returns terminal description string
void meta(win,bf) marks window for meta (dummy function)
* int move(y,x) move cursor in stdscr
* int mvaddch(y,x,ch) move & put char in stdscr
int mvaddrawch(y,x,ch) move & put raw char in stdscr
* int mvaddstr(y,x,str) move & put string in stdscr
int mvclrtobot(y,x) move & clear end of stdscr
int mvclrtoeol(y,x) move & clear lineend in stdscr
* int mvcur(oldy,oldx,y,x) move terminal cursor to
* int mvdelch(y,x) move & delete a char in stdscr
int mvdeleteln(y,x) move & delete a line in stdscr
* int mvgetch(y,x) move & get char to stdscr
* int mvgetstr(y,x,buf) move & get string via stdscr to buffer
* int mvinch(y,x,) move & get char at stdscr cursor
* int mvinsch(y,x,ch) move & insert char in stdscr
int mvinsrawch(y,x,ch) move & insert raw char in stdscr
int mvinsertln(y,x) move & insert new line in stdscr
* int mvprintw(y,x,fmt,args) move & print string in stdscr
* int mvscanw(y,x,fmt,args) move & get values via stdscr
* int mvwaddch(win,y,x,ch) move & put char in a window
int mvwaddrawch(win,y,x,ch) move & put raw char in a window
* int mvwaddstr(win,y,x,str) move & put string in a window
int mvwclrtobot(win,y,x) move & clear end of a window
int mvwclrtoeol(win,y,x) move & clear lineend in a window
* int mvwdelch(win,y,x) move & delete a char in a window
int mvwdeleteln(win,y,x) move & delete a line in a window
* int mvwgetch(win,y,x) move & get char to a window
* int mvwgetstr(win,y,x,str) move & get string to a window
* int mvwinch(win,y,x) move & get char at window cursor
* int mvwinsch(win,y,x,ch) move & insert char in a window
int mvwinsrawch(win,y,x,ch) move & insert raw char in a window
int mvwinsertln(win,y,x) move & insert new line in window
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 nocrmode() unset terminal cbreak mode
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
void reset_prog_mode() restore terminal I/O modes
void reset_shell_mode() set terminal to default 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
int setscrreg(miny,maxy) define stdscr's scroll region
* int setterm() dummy for compatibility
int setupterm(term,fd,errret) set up terminal (no-op on PC)
* 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 ungetch(ch) (#def macro) push back a character to input */
* int waddch(win,ch) put char in a window
int waddrawch(win,ch) put raw char in a window
* int waddstr(win,str) put string in a window
void wattroff(win,attrs) clear attribute(s) in window
void wattron(win,attrs) add attribute(s) in window
void wattrset(win,attrs) set window char attributes
void wborder(win,l,r,t,b,tl,tr,bl,br) Set non-std box characters
int wbox(win,miny,minx,maxy,maxx,l,r) draw a box inside a window
* void wclear(win) clear a window
* int wclrtobot(win) clear end of a window
* int wclrtoeol(win) clear end of line in a window
* int wdelch(win) delete a char in a window
* int wdeleteln(win) delete a line in a window
* void werase(win) erase a window
* int wgetch(win) get char via a window
* int wgetstr(win,buf) get string via window to a buffer
* int winch(win) get char at window cursor
* int winsch(win,ch) insert character in a window
int winsrawch(win,ch) insert raw character in a window
* int winsertln(win) insert new line in a window
* 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
int wsetscrreg(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
int wungetch(ch) push back a character to input */

MISSING FUNCTIONS

The following functions existing in UNIX cursees are missing in PCcurses:

getcap(nam) get terminal capability 'name'

FUNCTIONS UNIQUE TO PCcurses

The following functions are (to the author's knowledge) unique to PCcurses:

int addrawch(ch) put raw char in stdscr
int waddrawch(win,ch) put raw char in a window
int mvaddrawch(y,x,ch) move & put raw char in stdscr
int mvwaddrawch(win,y,x,ch) move & put raw char in a window
int insrawch(ch) insert raw character in stdscr
int winsrawch(win,ch) insert raw character in a window
int mvinsrawch(y,x,ch) move & insert raw char in stdscr
int mvwinsrawch(win,y,x,ch) move & insert raw char in a window
int tabsize(ts) set/get tabsize of stdscr
int wtabsize(win,ts) set/get tabsize of a window

SEE ALSO
"Screen Updating And Cursor Movement Optimization: A Library Package" -
Kenneth C.R.C. Arnold
"The Ncurses Reference Manual" - Pavel Curtis, Cornell University

BUGS
The terminal raw I/O mode is implemented by reading characters directly
from the BIOS. This means that the programmer must not use the normal
I/O routines to the screen or from the keyboard, since they will trap the
MS-DOS ^C, ^S, ^Q and ^P characters and thus nullify the raw input.

Also, if the terminal is in normal or cbreak mode and the programmer has
trapped CTRL-BREAK by using signal(SIGINT,ownhandler), MS-DOS will still
echo the characters '^C' on the screen when the character is intercepted.
There seems to be no way to avoid this under MS-DOS (use raw mode in-
stead, or redraw the whole screen).

The function key support is hardware dependent. There is a table in char-
get.c that maps keyboard scan codes from the keyboard to function key
names. The one supplied works for IBM PC/XT/AT, and for most clones.

REVISION
The current revision is v.1.4 (900114). If you find or correct bugs, or if
you think up or implement enhancements, please contact the author. That way
he can maintain an 'official' version of PCcurses, without too many local
versions floating around.

AUTHOR
Home: Bjorn Larsson Work: INFOVOX AB
Ynglingagatan 5,IV Box 2503
S-113 47 Stockholm S-171 02 Solna
SWEDEN SWEDEN

UseNet: [email protected]