creps@silver.bacs.indiana.edu (Steve Creps) (10/31/88)
Posting-number: Volume 5, Issue 27
Submitted-by: "Steve Creps" <creps@silver.bacs.indiana.edu>
Archive-name: pc-curses-1.3/Part5
#! /bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 5 (of 5)."
# Contents: curses.man
# Wrapped by creps@silver on Fri Oct 28 17:43:10 1988
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'curses.man' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'curses.man'\"
else
echo shar: Extracting \"'curses.man'\" \(14549 characters\)
sed "s/^X//" >'curses.man' <<'END_OF_FILE'
XCURSES(3) MS-DOS Programmer's Manual CURSES(3)
X
XNAME
X curses - screen/window management library
X
XDESCRIPTION
X Curses is a library of screen and window management routines. It is modeled
X after the UNIX curses and ncurses libraries. Normally, programs written for
X PCcurses should be easily ported to UNIX, and vice versa.
X
X To use the routines, the function initscr() must first be called. This cre-
X ates two 'windows' for the user: stdscr and curscr. Stdscr is the default
X window for the user to make changes on, and curscr reflects the current
X contents of the physical display screen. The user writes or edits the std-
X scr window to his liking, then calls the refresh() function to make curscr
X and the physical screen look like stdscr. When the user program terminates,
X it should call the endwin() function to restore things to normal.
X
X There are all sorts of window manipulation routines available to the pro-
X grammer: auxiliary windows may be created, edited, moved and deleted. The
X terminal may be set in many different modes, output text may be attributed
X with blink, blank, bold and reverse attributes. There are window-specific
X printf- and scanf-like routines, routines for scrolling, box-drawing, win-
X dow overlaying, clearing routines etc. Curses also handles terminal func-
X tion keys, which is enables by calling the keypad() function.
X
X The handling of character attributes is different on MGA, CGA and Hercules
X adapters. The package has been tested with them all. EGA has not been tes-
X ted, but should also work except for special screen modes.
X
X For more and detailed information, see the library source codes. All curses
X functions are preceded by a brief but complete description.
X
XCOMPILING
X All programs that use curses facilities should include the file <curses.h>,
X and during linking, the library ?curses.lib should be specified to the lin-
X ker ('?' is 's', 'c' 'm' or 'l' for small, compact, medium or large memory
X model respectively).
X
XFUNCTIONS
X Below is a list over the available functions, together with a brief de-
X scription of what they do. In general, functions whose names start with
X 'w' differ from the one without 'w' (like wmove vs. move) signify that
X a specific window is used. Without a 'w', stdscr is implied. The functions
X that start with 'mv' before the 'generic' function name signify that a
X cursor motion should be made before the actual work. 'mv' and 'w' combine
X as expected.
X
X Most routines that return an int will return the manifest constant ERR if
X there is a failure during execution. Routines that return a char actually
X return an int, so that ERR does not conflict with the character code 0xff.
X All IBM PC characters from 0 to 0xff are allowed for usage with curses.
X There are (non-portable) character output routines to write the special
X IBM fonts for characters with ASCII code less than 0x20 (control charac-
X ters).
X
X Some routines, like {mv}{w} printw() and {mv}{w}scanw() return a meaningful
X positive value if the operation is successful.
X
X The curses package uses some predefined types, variables and manifest con-
X stants that are also available to the programmer. There are also a few
X globally accessible variables that should not be touched by the applica-
X tion program. Those untouchable variables have names starting with an
X underscore (_) to avoid conflicts. The user-accessible types, variables
X and constants are (there are a number of other constants defining charac-
X ter attribute names and function key names - consult <curses.h> for de-
X tails):
X
X (manifest constants)
X
X TRUE boolean true
X FALSE boolean false
X ERR unsuccessful operation
X OK successful operation
X
X (types)
X
X WINDOW a window structure type
X bool boolean flag type
X
X (variables)
X
X WINDOW curscr physical display image
X WINDOW stdscr default user drawing board
X int LINES terminal height
X int COLS terminal width
X
X The following is an alphabetical list of the curses functions, together
X with their types, parameters and a short comment for each. Win is a win-
X dow; ch, l, r, t, b, tl, tr, bl and br are characters; buf is a character
X buffer; attrs is an attribute bit map; bf is a boolean flag. Note that
X `character' return values in this context usually can have 16 bits. Gua-
X ranteed portable functions (existing in Berkeley UNIX curses) are marked
X with an asterisk (*):
X
X
X* int addch(ch) put char in stdscr
X int addrawch(ch) put raw char in stdscr
X* int addstr(str) put string in stdscr
X void attroff(attrs) clear attribute(s) in stdscr
X void attron(attrs) add attribute(s) in stdscr
X void attrset(attrs) set stdscr char attributes
X int baudrate() dummy for compatibility
X void beep() ring the bell
X void border(l,r,t,b,tl,tr,bl,br) Set non-std box characters
X* void box(win,l,t) box in a window, with given characters
X* void cbreak() set terminal cbreak mode
X* void clear() clear stdscr
X* void clearok(win,bf) marks window for screen clear
X* int clrtobot() clear end of stdscr
X* int clrtoeol() clear end of line in stdscr
X* void crmode() set terminal cbreak mode
X void cursoff() turns off hardware cursor
X void curson() turns on hardware cursor
X void def_prog_mode() save TTY modes
X void def_shell_mode() compatibility dummy
X* int delch() delete a char in stdscr
X* int deleteln() delete a line in stdscr
X* void delwin(win) delete a window or a subwindow
X void doupdate() update physical screen
X* void echo() set terminal echo mode
X* int endwin() cleanup and curses finitialization
X* void erase() erase stdscr
X int erasechar() return char delete character
X int fixterm() dummy for compatibility
X void flash() flash terminal screen
X void flushinp() kill pending keyboard input
X* int getch() (#def macro) get character via stdscr
X* int getstr(buf) get string via stdscr to a buffer
X* void getyx(win,y,x) get a window's cursor position
X* int gettmode() dummy for compatibility
X void idlok(win,bf) dummy for compatibility
X* int initscr() curses initialization (ret 1 if OK)
X* int inch() get char at stdscr cursor
X* int insch(ch) insert character in stdscr
X int insrawch(ch) insert raw character in stdscr
X* int insertln() insert an empty line in stdscr
X void keypad(win,bf) marks a window for keypad usage
X int killchar() return line delete character
X* void leaveok(win,bf) marks window for cursor 'update leave'
X* char *longname() returns terminal description string
X void meta(win,bf) marks window for meta (dummy function)
X* int move(y,x) move cursor in stdscr
X* int mvaddch(y,x,ch) move & put char in stdscr
X int mvaddrawch(y,x,ch) move & put raw char in stdscr
X* int mvaddstr(y,x,str) move & put string in stdscr
X* int mvclrtobot(y,x) move & clear end of stdscr
X* int mvclrtoeol(y,x) move & clear lineend in stdscr
X* int mvcur(oldy,oldx,y,x) move terminal cursor to <y,x>
X* int mvdelch(y,x) move & delete a char in stdscr
X* int mvdeleteln(y,x) move & delete a line in stdscr
X* int mvgetch(y,x) move & get char to stdscr
X* int mvgetstr(y,x,buf) move & get string via stdscr to buffer
X* int mvinch(y,x,) move & get char at stdscr cursor
X* int mvinsch(y,x,ch) move & insert char in stdscr
X int mvinsrawch(y,x,ch) move & insert raw char in stdscr
X* int mvinsertln(y,x) move & insert new line in stdscr
X* int mvprintw(y,x,fmt,args) move & print string in stdscr
X* int mvscanw(y,x,fmt,args) move & get values via stdscr
X* int mvwaddch(win,y,x,ch) move & put char in a window
X int mvwaddrawch(win,y,x,ch) move & put raw char in a window
X* int mvwaddstr(win,y,x,str) move & put string in a window
X* int mvwclrtobot(win,y,x) move & clear end of a window
X* int mvwclrtoeol(win,y,x) move & clear lineend in a window
X* int mvwdelch(win,y,x) move & delete a char in a window
X* int mvwdeleteln(win,y,x) move & delete a line in a window
X* int mvwgetch(win,y,x) move & get char to a window
X* int mvwgetstr(win,y,x,str) move & get string to a window
X* int mvwinch(win,y,x) move & get char at window cursor
X* int mvwinsch(win,y,x,ch) move & insert char in a window
X int mvwinsrawch(win,y,x,ch) move & insert raw char in a window
X* int mvwinsertln(win,y,x) move & insert new line in window
X int mvwin(win,y,x) move window on physical screen
X* int mvwprintw(win,x,y,fmt,args) move & print string in a window
X* int mvwscanw(win,y,x,fmt,args) move & get values via a window
X* WINDOW *newwin(lines,cols,begy,begx) create a new window
X* void nl() set terminal cr-crlf mapping mode
X* void nocbreak() unset terminal cbreak mod
X* void nocrmode() unset terminal cbreak mode
X void nodelay(win,bf) marks window for no input wait
X* void noecho() unset terminal echo mode
X* void nonl() unset terminal cr-crlf mapping mode
X* void noraw() unset raw terminal mode
X* void overlay(win1,win2) overlay one window on another
X* void overwrite(win1,win2) overwrite one window on another
X* int printw(fmt,args) print string in stdscr
X* void raw() set raw terminal mode
X void refrbrk(bf) set screen update break mode
X* void refresh() refresh stdscr
X int resetterm() dummy for compatibility
X* int resetty() restore terminal I/O modes
X void reset_prog_mode() restore terminal I/O modes
X void reset_shell_mode() set terminal to default modes
X int saveoldterm() dummy for compatibility
X int saveterm() dummy for compatibility
X* int savetty() save terminal I/O modes
X* int scanw(fmt,args) get values via stdscr
X* void scroll(win) scroll scrolling region of a window
X* void scrollok(win,bf) marks a window to allow scroll
X int setsrcreg(miny,maxy) define stdscr's scroll region
X* int setterm() dummy for compatibility
X int setupterm(term,fd,errret) set up terminal (no-op on PC)
X* void standend() start normal chars in stdscr
X* void standout() start standout chars in stdscr
X* WINDOW *subwin(win,lines,cols,begy,begx) create a sub-window in window win
X int tabsize(ts) set/get tabsize of stdscr
X* void touchwin(win) mark a window as totally modified
X* char *unctrl(ch) char-to-string converter
X int ungetch(ch) (#def macro) push back a character to input */
X* int waddch(win,ch) put char in a window
X int waddrawch(win,ch) put raw char in a window
X* int waddstr(win,str) put string in a window
X void wattroff(win,attrs) clear attribute(s) in window
X void wattron(win,attrs) add attribute(s) in window
X void wattrset(win,attrs) set window char attributes
X void wborder(win,l,r,t,b,tl,tr,bl,br) Set non-std box characters
X* int wbox(win,miny,minx,maxy,maxx,l,r) draw a box inside a window
X* void wclear(win) clear a window
X* int wclrtobot(win) clear end of a window
X* int wclrtoeol(win) clear end of line in a window
X* int wdelch(win) delete a char in a window
X* int wdeleteln(win) delete a line in a window
X* void werase(win) erase a window
X* int wgetch(win) get char via a window
X* int wgetstr(win,buf) get string via window to a buffer
X* int winch(win) get char at window cursor
X* int winsch(win,ch) insert character in a window
X int winsrawch(win,ch) insert raw character in a window
X* int winsertln(win) insert new line in a window
X* int wmove(win,y,x) move cursor in a window
X void wnoutrefresh(win) create internal screen image
X* int wprintw(win,fmt,args) print string in a window
X* void wrefresh(win) refresh window
X* int wscanw(win,fmt,args) get values via a window
X int wsetsrcreg(win,miny,maxy) define a window's scrolling region
X* void wstandend(win) start normal chars in window
X* void wstandout(win) start standout chars in window
X int wtabsize(win,ts) set/get tabsize of a window
X int wungetch(ch) push back a character to input */
X
XMISSING FUNCTIONS
X
X The following functions existing in UNIX curses are missing in PCcurses:
X
X getcap(nam) get terminal capability 'name'
X
XFUNCTIONS UNIQUE TO PCcurses
X
X The following functions are (to the author's knowledge) unique to PCcurses:
X
X int addrawch(ch) put raw char in stdscr
X int waddrawch(win,ch) put raw char in a window
X int mvaddrawch(y,x,ch) move & put raw char in stdscr
X int mvwaddrawch(win,y,x,ch) move & put raw char in a window
X int insrawch(ch) insert raw character in stdscr
X int winsrawch(win,ch) insert raw character in a window
X int mvinsrawch(y,x,ch) move & insert raw char in stdscr
X int mvwinsrawch(win,y,x,ch) move & insert raw char in a window
X int tabsize(ts) set/get tabsize of stdscr
X int wtabsize(win,ts) set/get tabsize of a window
X
XSEE ALSO
X "Screen Updating And Cursor Movement Optimization: A Library Package" -
X Kenneth C.R.C. Arnold
X "The Ncurses Reference Manual" - Pavel Curtis, Cornell University
X
XBUGS
X The terminal raw I/O mode is implemented by reading characters directly
X from the BIOS. This means that the programmer must not use the normal
X I/O routines to the screen or from the keyboard, since they will trap the
X MS-DOS ^C, ^S, ^Q and ^P characters and thus nullify the raw input.
X
X Also, if the terminal is in normal or cbreak mode and the programmer has
X trapped CTRL-BREAK by using signal(SIGINT,ownhandler), MS-DOS will still
X echo the characters '^C' on the screen when the character is intercepted.
X There seems to be no way to avoid this under MS-DOS (use raw mode in-
X stead, or redraw the whole screen).
X
X The function key support is hardware dependent. There is a table in char-
X get.c that maps keyboard scan codes from the keyboard to function key
X names. The one supplied works for IBM PC/XT/AT, and for most clones.
X
XREVISION
X The current revision is v.1.3 (881005). If you find or correct bugs, or if
X you think up or implement enhancements, please contact the author. That way
X he can maintain an 'official' version of PCcurses, without too many local
X versions floating around.
X
XAUTHOR
X Home: Bjorn Larsson Work: INFOVOX AB
X Ynglingagatan 5,IV Box 2503
X S-113 47 Stockholm S-171 02 Solna
X SWEDEN SWEDEN
X
X UseNet: ...!seismo!mcvax!enea!infovax!bl
END_OF_FILE
if test 14549 -ne `wc -c <'curses.man'`; then
echo shar: \"'curses.man'\" unpacked with wrong size!
fi
# end of 'curses.man'
fi
echo shar: End of archive 5 \(of 5\).
cp /dev/null ark5isdone
MISSING=""
for I in 1 2 3 4 5 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked all 5 archives.
rm -f ark[1-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0