PDCurses User's Guide
=====================

Curses Overview
---------------

The X/Open Curses Interface Definition describes a set of C-Language
functions that provide screen-handling and updating, which are
collectively known as the curses library.

The curses library permits manipulation of data structures called
windows which may be thought of as two-dimensional arrays of
characters representing all or part of a terminal's screen.  The
windows are manipulated using a procedural interface described
elsewhere.  The curses package maintains a record of what characters
are on the screen.  At the most basic level, manipulation is done with
the routines move() and addch() which are used to "move" the curses
around and add characters to the default window, stdscr, which
represents the whole screen.

An application may use these routines to add data to the window in any
convenient order.  Once all data have been added, the routine
refresh() is called.  The package then determines what changes have
been made which affect the screen.  The screen contents are then
changed to reflect those characters now in the window, using a
sequence of operations optimized for the type of terminal in use. 

At a higher level routines combining the actions of move() and addch()
are defined, as are routines to add whole strings and to perform
format conversions in the manner of printf(). 

Interfaces are also defined to erase the entire window and to specify
the attributes of individual characters in the window.  Attributes
such as inverse video, underline and blink can be used on a
per-character basis. 

New windows can be created by allowing the application to build
several images of the screen and display the appropriate one very
quickly.  New windows are created using the routine newwin().  For
each routine that manipulates the default window, stdscr, there is a
corresponding routine prefixed with w to manipulate the contents of a
specified window; for example, move() and wmove().  In fact, move(...)
is functionally equivalent to wmove( stdscr, ...).  This is similar to
the interface offered by printf(...) and fprintf(stdout, ...). 

Windows do not have to correspond to the entire screen.  It is
possible to create smaller windows, and also to indicate that the
window is only partially visible on the screen.  Furthermore, large
windows or pads, which are bigger than the actual screen size, may be
created. 

Interfaces are also defined to allow input character manipulation and
to disable and enable many input attributes: character echo, single
character input with or without signal processing (cbreak or raw
modes), carriage returns mapping to newlines, screen scrolling, etc. 


Data Types and the <curses.h> Header
------------------------------------

The data types supported by curses are described in this section.

As the library supports a procedural interface to the data types, actual 
structure contents are not described.  All curses data are manipulated 
using the routines provided.


THE <curses.h> HEADER

The <curses.h> header defines various constants and declares the data 
types that are available to the application.


DATA TYPES

The following data types are declared:

	WINDOW *	pointer to screen representation
	SCREEN *	pointer to terminal descriptor
	bool		boolean data type
	chtype		representation of a character in a window
	cchar_t		the wide-character equivalent of chtype
	attr_t		for WA_-style attributes

The actual WINDOW and SCREEN objects used to store information are 
created by the corresponding routines and a pointer to them is provided.  
All manipulation is through that pointer.


VARIABLES

The following variables are defined:

	LINES		number of lines on terminal screen
	COLS		number of columns on terminal screen
	stdscr		pointer to the default screen window    
	curscr		pointer to the current screen image
	SP		pointer to the current SCREEN struct
	Mouse_status	status of the mouse
	COLORS		number of colors available
	COLOR_PAIRS	number of color pairs available
	TABSIZE		size of one TAB block
	acs_map[]	alternate character set map  
	ttytype[]	terminal name/description    


CONSTANTS

The following constants are defined:

GENERAL

	FALSE		boolean false value
	TRUE		boolean true value
	NULL		zero pointer value
	ERR		value returned on error condition
	OK		value returned on successful completion

VIDEO ATTRIBUTES

Normally, attributes are a property of the character. 

For chtype:

	A_ALTCHARSET	use the alternate character set
	A_BLINK		bright background or blinking
	A_BOLD		bright foreground or bold
	A_DIM		half bright -- no effect in PDCurses
	A_INVIS		invisible
	A_ITALIC	italic
	A_LEFTLINE	line along the left edge
	A_PROTECT 	protected (?) -- PDCurses renders this as a 
			combination of the *LINE attributes
	A_REVERSE	reverse video
	A_RIGHTLINE	line along the right edge
	A_STANDOUT	terminal's best highlighting mode
	A_UNDERLINE	underline

	A_ATTRIBUTES	bit-mask to extract attributes
	A_CHARTEXT	bit-mask to extract a character
	A_COLOR		bit-mask to extract a color-pair

Not all attributes will work on all terminals. A_RIGHTLINE, A_LEFTLINE 
and A_ITALIC are specific to PDCurses. A_INVIS and A_ITALIC are given 
the same value in PDCurses.

For attr_t:

	WA_ALTCHARSET	same as A_ALTCHARSET
	WA_BLINK	same as A_BLINK
	WA_BOLD		same as A_BOLD
	WA_DIM		same as A_DIM
	WA_INVIS	same as A_INVIS
	WA_LEFT		same as A_LEFTLINE
	WA_PROTECT	same as A_PROTECT
	WA_REVERSE	same as A_REVERSE
	WA_RIGHT	same as A_RIGHTLINE
	WA_STANDOUT	same as A_STANDOUT
	WA_UNDERLINE	same as A_UNDERLINE

Note that while A_LEFTLINE and A_RIGHTLINE are PDCurses-specific, 
WA_LEFT and WA_RIGHT are standard. The following are also defined, for 
compatibility, but currently have no effect in PDCurses: WA_HORIZONTAL, 
WA_LOW, WA_TOP, WA_VERTICAL.

THE ALTERNATE CHARACTER SET

For use in chtypes and with related functions. These are a portable way 
to represent graphics characters on different terminals.

VT100-compatible symbols -- box characters:

	ACS_ULCORNER	upper left box corner
	ACS_LLCORNER	lower left box corner
	ACS_URCORNER	upper right box corner
	ACS_LRCORNER	lower right box corner
	ACS_RTEE	right "T"
	ACS_LTEE	left "T"
	ACS_BTEE	bottom "T"
	ACS_TTEE	top "T"
	ACS_HLINE	horizontal line
	ACS_VLINE	vertical line
	ACS_PLUS	plus sign, cross, or four-corner piece

VT100-compatible symbols -- other:

	ACS_S1		scan line 1
	ACS_S9		scan line 9
	ACS_DIAMOND	diamond
	ACS_CKBOARD	checkerboard -- 50% grey
	ACS_DEGREE	degree symbol
	ACS_PLMINUS	plus/minus sign
	ACS_BULLET	bullet

Teletype 5410v1 symbols -- these are defined in SysV curses, but
are not well-supported by most terminals. Stick to VT100 characters
for optimum portability:

	ACS_LARROW	left arrow
	ACS_RARROW	right arrow
	ACS_DARROW	down arrow
	ACS_UARROW	up arrow
	ACS_BOARD	checkerboard -- lighter (less dense) than 
			ACS_CKBOARD
	ACS_LANTERN	lantern symbol
	ACS_BLOCK	solid block

That goes double for these -- undocumented SysV symbols. Don't use
them:

	ACS_S3		scan line 3
	ACS_S7		scan line 7
	ACS_LEQUAL	less than or equal
	ACS_GEQUAL	greater than or equal
	ACS_PI		pi
	ACS_NEQUAL	not equal
	ACS_STERLING	pounds sterling symbol

Box character aliases:

	ACS_BSSB	same as ACS_ULCORNER
	ACS_SSBB	same as ACS_LLCORNER
	ACS_BBSS	same as ACS_URCORNER
	ACS_SBBS	same as ACS_LRCORNER
	ACS_SBSS	same as ACS_RTEE
	ACS_SSSB	same as ACS_LTEE
	ACS_SSBS	same as ACS_BTEE
	ACS_BSSS	same as ACS_TTEE
	ACS_BSBS	same as ACS_HLINE
	ACS_SBSB	same as ACS_VLINE
	ACS_SSSS	same as ACS_PLUS

For cchar_t and wide-character functions, WACS_ equivalents are also 
defined.

COLORS

For use with init_pair(), color_set(), etc.:

	COLOR_BLACK
	COLOR_BLUE
	COLOR_GREEN
	COLOR_CYAN
	COLOR_RED
	COLOR_MAGENTA
	COLOR_YELLOW
	COLOR_WHITE

Use these instead of numeric values. The definition of the colors 
depends on the implementation of curses.


INPUT VALUES

The following constants might be returned by getch() if keypad() has
been enabled.  Note that not all of these may be supported on a
particular terminal:

	KEY_BREAK	break key
	KEY_DOWN	the four arrow keys
	KEY_UP
	KEY_LEFT
	KEY_RIGHT
	KEY_HOME	home key (upward+left arrow)
	KEY_BACKSPACE	backspace
	KEY_F0		function keys; space for 64 keys is reserved
	KEY_F(n)	(KEY_F0+(n))
	KEY_DL		delete line
	KEY_IL		insert line
	KEY_DC		delete character
	KEY_IC		insert character
	KEY_EIC		exit insert character mode
	KEY_CLEAR	clear screen
	KEY_EOS		clear to end of screen
	KEY_EOL		clear to end of line
	KEY_SF		scroll 1 line forwards
	KEY_SR		scroll 1 line backwards (reverse)
	KEY_NPAGE	next page
	KEY_PPAGE	previous page
	KEY_STAB	set tab
	KEY_CTAB	clear tab
	KEY_CATAB	clear all tabs
	KEY_ENTER	enter or send
	KEY_SRESET	soft (partial) reset
	KEY_RESET	reset or hard reset
	KEY_PRINT	print or copy
	KEY_LL		home down or bottom (lower left)
	KEY_A1		upper left of virtual keypad
	KEY_A3		upper right of virtual keypad
	KEY_B2		center of virtual keypad
	KEY_C1		lower left of virtual keypad
	KEY_C3		lower right of virtual keypad

	KEY_BTAB 	Back tab key
	KEY_BEG 	Beginning key
	KEY_CANCEL 	Cancel key
	KEY_CLOSE 	Close key
	KEY_COMMAND 	Cmd (command) key
	KEY_COPY 	Copy key
	KEY_CREATE 	Create key
	KEY_END 	End key
	KEY_EXIT 	Exit key
	KEY_FIND 	Find key
	KEY_HELP 	Help key
	KEY_MARK 	Mark key
	KEY_MESSAGE 	Message key
	KEY_MOVE 	Move key
	KEY_NEXT 	Next object key
	KEY_OPEN 	Open key
	KEY_OPTIONS 	Options key
	KEY_PREVIOUS 	Previous object key
	KEY_REDO 	Redo key
	KEY_REFERENCE 	Reference key
	KEY_REFRESH 	Refresh key
	KEY_REPLACE 	Replace key
	KEY_RESTART 	Restart key
	KEY_RESUME 	Resume key
	KEY_SAVE 	Save key
	KEY_SBEG 	Shifted beginning key
	KEY_SCANCEL 	Shifted cancel key
	KEY_SCOMMAND 	Shifted command key
	KEY_SCOPY 	Shifted copy key
	KEY_SCREATE 	Shifted create key
	KEY_SDC 	Shifted delete char key
	KEY_SDL 	Shifted delete line key
	KEY_SELECT 	Select key
	KEY_SEND 	Shifted end key
	KEY_SEOL 	Shifted clear line key
	KEY_SEXIT 	Shifted exit key
	KEY_SFIND 	Shifted find key
	KEY_SHELP 	Shifted help key
	KEY_SHOME 	Shifted home key
	KEY_SIC 	Shifted input key
	KEY_SLEFT 	Shifted left arrow key
	KEY_SMESSAGE 	Shifted message key
	KEY_SMOVE 	Shifted move key
	KEY_SNEXT 	Shifted next key
	KEY_SOPTIONS 	Shifted options key
	KEY_SPREVIOUS 	Shifted prev key
	KEY_SPRINT 	Shifted print key
	KEY_SREDO 	Shifted redo key
	KEY_SREPLACE 	Shifted replace key
	KEY_SRIGHT 	Shifted right arrow
	KEY_SRSUME 	Shifted resume key
	KEY_SSAVE 	Shifted save key
	KEY_SSUSPEND 	Shifted suspend key
	KEY_SUNDO 	Shifted undo key
	KEY_SUSPEND 	Suspend key
	KEY_UNDO 	Undo key

The virtual keypad is arranged like this:

	A1	up	A3
	left	B2	right
	C1	down	C3

This list is incomplete -- see curses.h for the full list, and use the 
testcurs demo to see what values are actually returned. The above are 
just the keys required by X/Open. In particular, PDCurses defines many 
CTL_ and ALT_ combinations; these are not portable.


FUNCTIONS

The following table lists each curses routine and the name of the manual 
page on which it is described.

Functions from the X/Open curses standard -- complete, except for 
getch() and ungetch(), which are implemented as macros for DOS 
compatibility:

   Curses Function        Manual Page Name

	addch			addch
	addchnstr		addchstr
	addchstr		addchstr
	addnstr			addstr
	addstr			addstr
	attroff			attr
	attron			attr
	attrset			attr
	attr_get		attr
	attr_off		attr
	attr_on			attr
	attr_set		attr
	baudrate		termattr
	beep			beep
	bkgd			bkgd
	bkgdset			bkgd
	border			border
	box			border
	can_change_color	color
	cbreak			inopts
	chgat			attr
	clearok			outopts
	clear			clear
	clrtobot		clear
	clrtoeol		clear
	color_content		color
	color_set		attr
	copywin			overlay
	curs_set		kernel
	def_prog_mode		kernel
	def_shell_mode		kernel
	del_curterm		terminfo
	delay_output		util
	delch			delch
	deleteln		deleteln
	delscreen		initscr
	delwin			window
	derwin			window
	doupdate		refresh
	dupwin			window
	echochar		addch
	echo			inopts
	endwin			initscr
	erasechar		termattr
	erase			clear
	filter			util
	flash			beep
	flushinp		getch
	getbkgd			bkgd
	getnstr			getstr
	getstr			getstr
	getwin			scr_dump
	halfdelay		inopts
	has_colors		color
	has_ic			termattr
	has_il			termattr
	hline			border
	idcok			outopts
	idlok			outopts
	immedok			outopts
	inchnstr		inchstr
	inchstr			inchstr
	inch			inch
	init_color		color
	init_pair		color
	initscr			initscr
	innstr			instr
	insch			insch
	insdelln		deleteln
	insertln		deleteln
	insnstr			innstr
	insstr			innstr
	instr			instr
	intrflush		inopts
	isendwin		initscr
	is_linetouched		touch
	is_wintouched		touch
	keyname			keyname
	keypad			inopts
	killchar		termattr
	leaveok			outopts
	longname		termattr
	meta			inopts
	move			move
	mvaddch			addch
	mvaddchnstr		addchstr
	mvaddchstr		addchstr
	mvaddnstr		addstr
	mvaddstr		addstr
	mvchgat			attr
	mvcur			terminfo
	mvdelch			delch
	mvderwin		window
	mvgetch			getch
	mvgetnstr		getstr
	mvgetstr		getstr
	mvhline			border
	mvinch			inch
	mvinchnstr		inchstr
	mvinchstr		inchstr
	mvinnstr		instr
	mvinsch			insch
	mvinsnstr		insstr
	mvinsstr		insstr
	mvinstr			instr
	mvprintw		printw
	mvscanw			scanw
	mvvline			border
	mvwaddchnstr		addchstr
	mvwaddchstr		addchstr
	mvwaddch		addch
	mvwaddnstr		addstr
	mvwaddstr		addstr
	mvwchgat		attr
	mvwdelch		delch
	mvwgetch		getch
	mvwgetnstr		getstr
	mvwgetstr		getstr
	mvwhline		border
	mvwinchnstr		inchstr
	mvwinchstr		inchstr
	mvwinch			inch
	mvwinnstr		instr
	mvwinsch		insch
	mvwinsnstr		insstr
	mvwinsstr		insstr
	mvwinstr		instr
	mvwin			window
	mvwprintw		printw
	mvwscanw		scanw
	mvwvline		border
	napms			kernel
	newpad			pad
	newterm			initscr
	newwin			window
	nl			inopts
	nocbreak		inopts
	nodelay			inopts
	noecho			inopts
	nonl			inopts
	noqiflush		inopts
	noraw			inopts
	notimeout		inopts
	overlay			overlay
	overwrite		overlay
	pair_content		color
	pechochar		pad
	pnoutrefresh		pad
	prefresh		pad
	printw			printw
	putp			terminfo
	putwin			scr_dump
	qiflush			inopts
	raw			inopts
	redrawwin		refresh
	refresh			refresh
	reset_prog_mode		kernel
	reset_shell_mode	kernel
	resetty			kernel
	restartterm		terminfo
	ripoffline		kernel
	savetty			kernel
	scanw			scanw
	scr_dump		scr_dump
	scr_init		scr_dump
	scr_restore		scr_dump
	scr_set			scr_dump
	scrl			scroll
	scroll			scroll
	scrollok		outopts
	set_term		initscr
	setscrreg		outopts
	setterm			terminfo
	setupterm		terminfo
	slk_attroff		slk
	slk_attr_off		slk
	slk_attron		slk
	slk_attr_on		slk
	slk_attrset		slk
	slk_attr_set		slk
	slk_clear		slk
	slk_color		slk
	slk_init		slk
	slk_label		slk
	slk_noutrefresh		slk
	slk_refresh		slk
	slk_restore		slk
	slk_set			slk
	slk_touch		slk
	standend		attr
	standout		attr
	start_color		color
	subpad			pad
	subwin			window
	syncok			window
	termattrs		termattrs
	term_attrs		termattrs
	termname		termattrs
	tgetent			termcap
	tgetflag		termcap
	tgetnum			termcap
	tgetstr			termcap
	tgoto			termcap
	tigetflag		terminfo
	tigetnum		terminfo
	tigetstr		terminfo
	timeout			inopts
	touchline		touch
	touchwin		touch
	tparm			terminfo
	tputs			terminfo
	typeahead		inopts
	untouchwin		touch
	use_env			util
	vidattr			terminfo
	vid_attr		terminfo
	vidputs			terminfo
	vid_puts		terminfo
	vline			border
	vw_printw		printw
	vwprintw		printw
	vw_scanw		scanw
	vwscanw			scanw
	waddchnstr		addchstr
	waddchstr		addchstr
	waddch			addch
	waddnstr		addstr
	waddstr			addstr
	wattroff		attr
	wattron			attr
	wattrset		attr
	wattr_get		attr
	wattr_off		attr
	wattr_on		attr
	wattr_set		attr
	wbkgdset		bkgd
	wbkgd			bkgd
	wborder			border
	wchgat			attr
	wclear			clear
	wclrtobot		clear
	wclrtoeol		clear
	wcolor_set		attr
	wcursyncup		window
	wdelch			delch
	wdeleteln		deleteln
	wechochar		addch
	werase			clear
	wgetch			getch
	wgetnstr		getstr
	wgetstr			getstr
	whline			border
	winchnstr		inchstr
	winchstr		inchstr
	winch			inch
	winnstr			instr
	winsch			insch
	winsdelln		deleteln
	winsertln		deleteln
	winsnstr		insstr
	winsstr			insstr
	winstr			instr
	wmove			move
	wnoutrefresh		refresh
	wprintw			printw
	wredrawln		refresh
	wrefresh		refresh
	wscanw			scanw
	wscrl			scroll
	wsetscrreg		outopts
	wstandend		attr
	wstandout		attr
	wsyncdown		window
	wsyncup			window
	wtimeout		inopts
	wtouchln		touch
	wvline			border

Wide-character functions from the X/Open standard -- these are only 
available when PDCurses is built with PDC_WIDE defined, and the 
prototypes are only available from curses.h when PDC_WIDE is defined 
before its inclusion in your app:

	addnwstr		addstr
	addwstr			addstr
	add_wch			addch
	add_wchnstr		addchstr
	add_wchstr		addchstr
	border_set		border
	box_set			border
	echo_wchar		addch
	erasewchar		termattr
	getbkgrnd		bkgd
	getcchar		util
	getn_wstr		getstr
	get_wch			getch
	get_wstr		getstr
	hline_set		border
	innwstr			instr
	ins_nwstr		insstr
	ins_wch			insch
	ins_wstr		insstr
	inwstr			instr
	in_wch			inch
	in_wchnstr		inchstr
	in_wchstr		inchstr
	key_name		keyname
	killwchar		termattr
	mvaddnwstr		addstr
	mvaddwstr		addstr
	mvadd_wch		addch
	mvadd_wchnstr		addchstr
	mvadd_wchstr		addchstr
	mvgetn_wstr		getstr
	mvget_wch		getch
	mvget_wstr		getstr
	mvhline_set		border
	mvinnwstr		instr
	mvins_nwstr		insstr
	mvins_wch		insch
	mvins_wstr		insstr
	mvinwstr		instr
	mvwaddnwstr		addstr
	mvwaddwstr		addstr
	mvwadd_wch		addch
	mvwadd_wchnstr		addchstr
	mvwadd_wchstr		addchstr
	mvwgetn_wstr		getstr
	mvwget_wch		getch
	mvwget_wstr		getstr
	mvwhline_set		border
	mvwinnwstr		instr
	mvwins_nwstr		insstr
	mvwins_wch		insch
	mvwins_wstr		insstr
	mvwin_wch		inch
	mvwin_wchnstr		inchstr
	mvwin_wchstr		inchstr
	mvwinwstr		instr
	mvwvline_set		border
	pecho_wchar		pad
	setcchar		util
	slk_wset		slk
	unget_wch		getch
	vline_set		border
	waddnwstr		addstr
	waddwstr		addstr
	wadd_wch		addch
	wadd_wchnstr		addchstr
	wadd_wchstr		addchstr
	wbkgrnd			bkgd
	wbkgrndset		bkgd
	wborder_set		border
	wecho_wchar		addch
	wgetbkgrnd		bkgd
	wgetn_wstr		getstr
	wget_wch		getch
	wget_wstr		getstr
	whline_set		border
	winnwstr		instr
	wins_nwstr		insstr
	wins_wch		insch
	wins_wstr		insstr
	winwstr			instr
	win_wch			inch
	win_wchnstr		inchstr
	win_wchstr		inchstr
	wunctrl			util
	wvline_set		border

Quasi-standard functions, from Sys V or BSD curses:

	getattrs		attr
	getbegx			getyx
	getbegy			getyx
	getmaxx			getyx
	getmaxy			getyx
	getparx			getyx
	getparx			getyx
	traceoff		debug
	traceon			debug
	unctrl			util

Classic PDCurses mouse functions, based on Sys V:

	mouse_set		mouse
	mouse_on		mouse
	mouse_off		mouse
	request_mouse_pos	mouse
	map_button		mouse
	wmouse_position		mouse
	getmouse		mouse
	getbmap			mouse

Functions from ncurses:

	assume_default_colors	color
	curses_version		initscr
	has_key			keyname
	use_default_colors	color
	wresize			window

	mouseinterval		mouse
	mousemask		mouse
	mouse_trafo		mouse
	nc_getmouse		mouse
	ungetmouse		mouse
	wenclose		mouse
	wmouse_trafo		mouse

PDCurses-specific functions -- avoid these in code that's intended to be 
portable:

	addrawch		addch
	insrawch		insch
	is_termresized		initscr
	mvaddrawch		addch
	mvdeleteln		deleteln
	mvinsertln		deleteln
	mvinsrawch		insch
	mvwaddrawch		addch
	mvwdeleteln		deleteln
	mvwinsertln		deleteln
	mvwinsrawch		insch
	raw_output		outopts
	resize_term		initscr
	resize_window		window
	slk_wlabel		slk
	waddrawch		addch
	winsrawch		insch
	wordchar		termattr

	PDC_debug		debug
	PDC_ungetch		getch
	PDC_set_blink		pdcsetsc
	PDC_set_line_color	color
	PDC_set_title		pdcsetsc

	PDC_clearclipboard	pdcclip
	PDC_freeclipboard	pdcclip
	PDC_getclipboard	pdcclip
	PDC_setclipboard	pdcclip

	PDC_get_input_fd	pdckbd
	PDC_get_key_modifiers	getch
	PDC_return_key_modifiers getch
	PDC_save_key_modifiers	getch

Functions specific to the X11 port of PDCurses:

	Xinitscr		initscr
	XCursesExit		-
	sb_init			sb
	sb_set_horz		sb
	sb_set_vert		sb
	sb_get_horz		sb
	sb_get_vert		sb
	sb_refresh		sb

--------------------------------------------------------------------------

PDCurses Definitions and Variables
==================================

PDCurses definitions list:  (Only define those needed)

    XCURSES         True if compiling for X11.
    PDC_RGB         True if you want to use RGB color definitions
                    (Red = 1, Green = 2, Blue = 4) instead of BGR.
    PDC_WIDE        True if building wide-character support.
    PDC_DLL_BUILD   True if building a Win32 DLL.
    NCURSES_MOUSE_VERSION   Use the ncurses mouse API instead
                            of PDCurses' traditional mouse API.

PDCurses portable platform definitions list:

    PDC_BUILD       Defines API build version.
    PDCURSES        Enables access to PDCurses-only routines.
    XOPEN           Always true.
    SYSVcurses      True if you are compiling for SYSV portability.
    BSDcurses       True if you are compiling for BSD portability.



--------------------------------------------------------------------------


PDCurses Text Attributes
========================

Originally, PDCurses used a short (16 bits) for its chtype. To include 
color, a number of things had to be sacrificed from the strict Unix and 
System V support. The main problem was fitting all character attributes 
and color into an unsigned char (all 8 bits!).

Today, PDCurses by default uses a long (32 bits) for its chtype, as in 
System V. The short chtype is still available, by undefining CHTYPE_LONG 
and rebuilding the library.

The following is the structure of a win->_attrs chtype:

short form:

-------------------------------------------------
|15|14|13|12|11|10| 9| 8| 7| 6| 5| 4| 3| 2| 1| 0|
-------------------------------------------------
  color number |  attrs |   character eg 'a'

The available non-color attributes are bold, reverse and blink. Others 
have no effect. The high order char is an index into an array of 
physical colors (defined in color.c) -- 32 foreground/background color 
pairs (5 bits) plus 3 bits for other attributes.

long form:

----------------------------------------------------------------------------
|31|30|29|28|27|26|25|24|23|22|21|20|19|18|17|16|15|14|13|12|..| 3| 2| 1| 0|
----------------------------------------------------------------------------
      color number      |     modifiers         |      character eg 'a'

The available non-color attributes are bold, underline, invisible, 
right-line, left-line, protect, reverse and blink. 256 color pairs (8 
bits), 8 bits for other attributes, and 16 bits for character data.



--------------------------------------------------------------------------

PDCurses Functions
==================

  Name:                                                         addch

  Synopsis:
        int addch(const chtype ch);
        int waddch(WINDOW *win, const chtype ch);
        int mvaddch(int y, int x, const chtype ch);
        int mvwaddch(WINDOW *win, int y, int x, const chtype ch);
        int echochar(const chtype ch);
        int wechochar(WINDOW *win, const chtype ch);

        int addrawch(chtype ch);
        int waddrawch(WINDOW *win, chtype ch);
        int mvaddrawch(int y, int x, chtype ch);
        int mvwaddrawch(WINDOW *win, int y, int x, chtype ch);

        int add_wch(const cchar_t *wch);
        int wadd_wch(WINDOW *win, const cchar_t *wch);
        int mvadd_wch(int y, int x, const cchar_t *wch);
        int mvwadd_wch(WINDOW *win, int y, int x, const cchar_t *wch);
        int echo_wchar(const cchar_t *wch);
        int wecho_wchar(WINDOW *win, const cchar_t *wch);

  Description:
        addch() adds the chtype ch to the default window (stdscr) at the
        current cursor position, and advances the cursor. Note that
        chtypes can convey both text (a single character) and
        attributes, including a color pair. add_wch() is the wide-
        character version of this function, taking a pointer to a
        cchar_t instead of a chtype.

        waddch() is like addch(), but also lets you specify the window.
        (This is in fact the core output routine.) wadd_wch() is the
        wide version.

        mvaddch() moves the cursor to the specified (y, x) position, and
        adds ch to stdscr. mvadd_wch() is the wide version.

        mvwaddch() moves the cursor to the specified position and adds 
        ch to the specified window. mvwadd_wch() is the wide version.

        echochar() adds ch to stdscr at the current cursor position and 
        calls refresh(). echo_wchar() is the wide version.

        wechochar() adds ch to the specified window and calls 
        wrefresh(). wecho_wchar() is the wide version.

        addrawch(), waddrawch(), mvaddrawch() and mvwaddrawch() are
        PDCurses-specific wrappers for addch() etc. that disable the 
        translation of control characters.

        The following applies to all these functions:

        If the cursor moves on to the right margin, an automatic newline 
        is performed.  If scrollok is enabled, and a character is added 
        to the bottom right corner of the window, the scrolling region 
        will be scrolled up one line.  If scrolling is not allowed, ERR 
        will be returned.

        If ch is a tab, newline, or backspace, the cursor will be moved 
        appropriately within the window.  If ch is a newline, the 
        clrtoeol routine is called before the cursor is moved to the 
        beginning of the next line.  If newline mapping is off, the 
        cursor will be moved to the next line, but the x coordinate will 
        be unchanged.  If ch is a tab the cursor is moved to the next 
        tab position within the window.  If ch is another control 
        character, it will be drawn in the ^X notation.  Calling the 
        inch() routine after adding a control character returns the 
        representation of the control character, not the control 
        character.

        Video attributes can be combined with a character by ORing them 
        into the parameter. Text, including attributes, can be copied 
        from one place to another by using inch() and addch().

        Note that in PDCurses, for now, a cchar_t and a chtype are the
        same. The text field is 16 bits wide, and is treated as Unicode
        (UCS-2) when PDCurses is built with wide-character support
        (define PDC_WIDE). So, in functions that take a chtype, like
        addch(), both the wide and narrow versions will handle Unicode.
        But for portability, you should use the wide functions.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        addch                                   Y       Y       Y
        waddch                                  Y       Y       Y
        mvaddch                                 Y       Y       Y
        mvwaddch                                Y       Y       Y
        echochar                                Y       -      3.0
        wechochar                               Y       -      3.0
        addrawch                                -       -       -
        waddrawch                               -       -       -
        mvaddrawch                              -       -       -
        mvwaddrawch                             -       -       -
        add_wch                                 Y
        wadd_wch                                Y
        mvadd_wch                               Y
        mvwadd_wch                              Y
        echo_wchar                              Y
        wecho_wchar                             Y



--------------------------------------------------------------------------


  Name:                                                         addchstr

  Synopsis:
        int addchstr(const chtype *ch);
        int addchnstr(const chtype *ch, int n);
        int waddchstr(WINDOW *win, const chtype *ch);
        int waddchnstr(WINDOW *win, const chtype *ch, int n);
        int mvaddchstr(int y, int x, const chtype *ch);
        int mvaddchnstr(int y, int x, const chtype *ch, int n);
        int mvwaddchstr(WINDOW *, int y, int x, const chtype *ch);
        int mvwaddchnstr(WINDOW *, int y, int x, const chtype *ch, int n);

        int add_wchstr(const cchar_t *wch);
        int add_wchnstr(const cchar_t *wch, int n);
        int wadd_wchstr(WINDOW *win, const cchar_t *wch);
        int wadd_wchnstr(WINDOW *win, const cchar_t *wch, int n);
        int mvadd_wchstr(int y, int x, const cchar_t *wch);
        int mvadd_wchnstr(int y, int x, const cchar_t *wch, int n);
        int mvwadd_wchstr(WINDOW *win, int y, int x, const cchar_t *wch);
        int mvwadd_wchnstr(WINDOW *win, int y, int x, const cchar_t *wch,
                int n);

  Description:
        These routines write a chtype or cchar_t string directly into 
        the window structure, starting at the current or specified 
        position. The four routines with n as the last argument copy at 
        most n elements, but no more than will fit on the line. If n = 
        -1 then the whole string is copied, up to the maximum number 
        that will fit on the line.

        The cursor position is not advanced. These routines do not check 
        for newline or other special characters, nor does any line 
        wrapping occur.

  Return Value:
        All functions return OK or ERR.

  Portability                                X/Open    BSD    SYS V
        addchstr                                Y       -      4.0
        waddchstr                               Y       -      4.0
        mvaddchstr                              Y       -      4.0
        mvwaddchstr                             Y       -      4.0
        addchnstr                               Y       -      4.0
        waddchnstr                              Y       -      4.0
        mvaddchnstr                             Y       -      4.0
        mvwaddchnstr                            Y       -      4.0
        add_wchstr                              Y
        wadd_wchstr                             Y
        mvadd_wchstr                            Y
        mvwadd_wchstr                           Y
        add_wchnstr                             Y
        wadd_wchnstr                            Y
        mvadd_wchnstr                           Y
        mvwadd_wchnstr                          Y



--------------------------------------------------------------------------


  Name:                                                         addstr

  Synopsis:
        int addstr(const char *str);
        int addnstr(const char *str, int n);
        int waddstr(WINDOW *win, const char *str);
        int waddnstr(WINDOW *win, const char *str, int n);
        int mvaddstr(int y, int x, const char *str);
        int mvaddnstr(int y, int x, const char *str, int n);
        int mvwaddstr(WINDOW *win, int y, int x, const char *str);
        int mvwaddnstr(WINDOW *win, int y, int x, const char *str, int n);

        int addwstr(const wchar_t *wstr);
        int addnwstr(const wchar_t *wstr, int n);
        int waddwstr(WINDOW *win, const wchar_t *wstr);
        int waddnwstr(WINDOW *win, const wchar_t *wstr, int n);
        int mvaddwstr(int y, int x, const wchar_t *wstr);
        int mvaddnwstr(int y, int x, const wchar_t *wstr, int n);
        int mvwaddwstr(WINDOW *win, int y, int x, const wchar_t *wstr);
        int mvwaddnwstr(WINDOW *win, int y, int x, const wchar_t *wstr, int n);

  Description:
        These routines write all the characters of the null-terminated
        string str or wide-character string wstr to the given window.
        The functionality is similar to calling waddch() once for each
        character in the string; except that, when PDCurses is built
        with wide-character support enabled, the narrow-character
        functions treat the string as a multibyte string in the current
        locale, and convert it. The routines with n as the last
        argument write at most n characters; if n is negative, then the
        entire string will be added.

  Return Value:
        All functions return OK or ERR.

  Portability                                X/Open    BSD    SYS V
        addstr                                  Y       Y       Y
        waddstr                                 Y       Y       Y
        mvaddstr                                Y       Y       Y
        mvwaddstr                               Y       Y       Y
        addnstr                                 Y       -      4.0
        waddnstr                                Y       -      4.0
        mvaddnstr                               Y       -      4.0
        mvwaddnstr                              Y       -      4.0
        addwstr                                 Y
        waddwstr                                Y
        mvaddwstr                               Y
        mvwaddwstr                              Y
        addnwstr                                Y
        waddnwstr                               Y
        mvaddnwstr                              Y
        mvwaddnwstr                             Y



--------------------------------------------------------------------------


  Name:                                                         attr

  Synopsis:
        int attroff(chtype attrs);
        int wattroff(WINDOW *win, chtype attrs);
        int attron(chtype attrs);
        int wattron(WINDOW *win, chtype attrs);
        int attrset(chtype attrs);
        int wattrset(WINDOW *win, chtype attrs);
        int standend(void);
        int wstandend(WINDOW *win);
        int standout(void);
        int wstandout(WINDOW *win);

        int color_set(short color_pair, void *opts);
        int wcolor_set(WINDOW *win, short color_pair, void *opts);

        int attr_get(attr_t *attrs, short *color_pair, void *opts);
        int attr_off(attr_t attrs, void *opts);
        int attr_on(attr_t attrs, void *opts);
        int attr_set(attr_t attrs, short color_pair, void *opts);
        int wattr_get(WINDOW *win, attr_t *attrs, short *color_pair,
                void *opts);
        int wattr_off(WINDOW *win, attr_t attrs, void *opts);
        int wattr_on(WINDOW *win, attr_t attrs, void *opts);
        int wattr_set(WINDOW *win, attr_t attrs, short color_pair,
                void *opts);

        int chgat(int n, attr_t attr, short color, const void *opts);
        int mvchgat(int y, int x, int n, attr_t attr, short color,
                const void *opts);
        int mvwchgat(WINDOW *win, int y, int x, int n, attr_t attr,
                short color, const void *opts);
        int wchgat(WINDOW *win, int n, attr_t attr, short color,
                const void *opts);

        chtype getattrs(WINDOW *win);

  Description:
        These functions manipulate the current attributes and/or colors 
        of the named window.  These attributes can be any combination 
        of A_STANDOUT, A_REVERSE, A_BOLD, A_DIM, A_BLINK, A_UNDERLINE.

        These constants are defined in <curses.h> and can be combined
        with the bitwise-OR operator (|).

        The current attributes of a window are applied to all chtypes 
        that are written into the window with waddch(). Attributes are 
        a property of the chtype, and move with the character through 
        any scrolling or insert/delete operations.

        attrset() sets the current attributes of the given window to 
        attrs. attroff() turns off the named attributes without 
        affecting any other attributes; attron() turns them on. 
        color_set() sets the window color to the value of color_pair.

        standout() is the same as attron(A_STANDOUT). standend() is the 
        same as attrset(A_NORMAL); that is, it turns off all attributes.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        attroff                                 Y       Y       Y
        wattroff                                Y       Y       Y
        attron                                  Y       Y       Y
        wattron                                 Y       Y       Y
        attrset                                 Y       Y       Y
        wattrset                                Y       Y       Y
        standend                                Y       Y       Y
        wstandend                               Y       Y       Y
        standout                                Y       Y       Y
        wstandout                               Y       Y       Y
        color_set                               Y
        wcolor_set                              Y
        attr_get                                Y
        wattr_get                               Y
        attr_on                                 Y
        wattr_on                                Y
        attr_off                                Y
        wattr_off                               Y
        attr_set                                Y
        wattr_set                               Y
        chgat                                   Y
        wchgat                                  Y
        mvchgat                                 Y
        mvwchgat                                Y
        getattrs                                -



--------------------------------------------------------------------------


  Name:                                                         beep

  Synopsis:
        int beep(void);
        int flash(void);

  Description:
        beep() sounds the audible bell on the terminal, if possible;
        if not, it calls flash().

        flash() "flashes" the screen, by inverting the foreground and
        background of every cell, pausing, and then restoring the
        original attributes.

  Return Value:
        These functions return OK.

  Portability                                X/Open    BSD    SYS V
        beep                                    Y       Y       Y
        flash                                   Y       Y       Y



--------------------------------------------------------------------------


  Name:                                                         bkgd

  Synopsis:
        int bkgd(chtype ch);
        void bkgdset(chtype ch);
        chtype getbkgd(WINDOW *win);
        int wbkgd(WINDOW *win, chtype ch);
        void wbkgdset(WINDOW *win, chtype ch);

        int bkgrnd(const cchar_t *wch);
        void bkgrndset(const cchar_t *wch);
        int getbkgrnd(cchar_t *wch);
        int wbkgrnd(WINDOW *win, const cchar_t *wch);
        void wbkgrndset(WINDOW *win, const cchar_t *wch);
        int wgetbkgrnd(WINDOW *win, cchar_t *wch);

  Description:
        bkgdset() and wbkgdset() manipulate the background of a window.
        The background is a chtype consisting of any combination of
        attributes and a character; it is combined with each chtype
        added or inserted to the window by waddch() or winsch(). Only
        the attribute part is used to set the background of non-blank
        characters, while both character and attributes are used for
        blank positions.

        bkgd() and wbkgd() not only change the background, but apply it
        immediately to every cell in the window.

        The attributes that are defined with the attrset()/attron() set
        of functions take precedence over the background attributes if
        there is a conflict (e.g., different color pairs).

  Return Value:
        bkgd() and wbkgd() return OK, unless the window is NULL, in 
        which case they return ERR.

  Portability                                X/Open    BSD    SYS V
        bkgd                                    Y       -      4.0
        bkgdset                                 Y       -      4.0
        getbkgd                                 Y
        wbkgd                                   Y       -      4.0
        wbkgdset                                Y       -      4.0
        bkgrnd                                  Y
        bkgrndset                               Y
        getbkgrnd                               Y
        wbkgrnd                                 Y
        wbkgrndset                              Y
        wgetbkgrnd                              Y



--------------------------------------------------------------------------


  Name:                                                         border

  Synopsis:
        int border(chtype ls, chtype rs, chtype ts, chtype bs, chtype tl, 
                   chtype tr, chtype bl, chtype br);
        int wborder(WINDOW *win, chtype ls, chtype rs, chtype ts, 
                    chtype bs, chtype tl, chtype tr, chtype bl, chtype br);
        int box(WINDOW *win, chtype verch, chtype horch);
        int hline(chtype ch, int n);
        int vline(chtype ch, int n);
        int whline(WINDOW *win, chtype ch, int n);
        int wvline(WINDOW *win, chtype ch, int n);
        int mvhline(int y, int x, chtype ch, int n);
        int mvvline(int y, int x, chtype ch, int n);
        int mvwhline(WINDOW *win, int y, int x, chtype ch, int n);
        int mvwvline(WINDOW *win, int y, int x, chtype ch, int n);

        int border_set(const cchar_t *ls, const cchar_t *rs,
                       const cchar_t *ts, const cchar_t *bs,
                       const cchar_t *tl, const cchar_t *tr,
                       const cchar_t *bl, const cchar_t *br);
        int wborder_set(WINDOW *win, const cchar_t *ls, const cchar_t *rs,
                        const cchar_t *ts, const cchar_t *bs,
                        const cchar_t *tl, const cchar_t *tr,
                        const cchar_t *bl, const cchar_t *br);
        int box_set(WINDOW *win, const cchar_t *verch, const cchar_t *horch);
        int hline_set(const cchar_t *wch, int n);
        int vline_set(const cchar_t *wch, int n);
        int whline_set(WINDOW *win, const cchar_t *wch, int n);
        int wvline_set(WINDOW *win, const cchar_t *wch, int n);
        int mvhline_set(int y, int x, const cchar_t *wch, int n);
        int mvvline_set(int y, int x, const cchar_t *wch, int n);
        int mvwhline_set(WINDOW *win, int y, int x, const cchar_t *wch, int n);
        int mvwvline_set(WINDOW *win, int y, int x, const cchar_t *wch, int n);

  Description:
        border(), wborder(), and box() draw a border around the edge of 
        the window. If any argument is zero, an appropriate default is 
        used:

                ls      left side of border             ACS_VLINE
                rs      right side of border            ACS_VLINE
                ts      top side of border              ACS_HLINE
                bs      bottom side of border           ACS_HLINE
                tl      top left corner of border       ACS_ULCORNER
                tr      top right corner of border      ACS_URCORNER
                bl      bottom left corner of border    ACS_LLCORNER
                br      bottom right corner of border   ACS_LRCORNER

        hline() and whline() draw a horizontal line, using ch, starting 
        from the current cursor position. The cursor position does not 
        change. The line is at most n characters long, or as many as 
        will fit in the window.

        vline() and wvline() draw a vertical line, using ch, starting 
        from the current cursor position. The cursor position does not 
        change. The line is at most n characters long, or as many as 
        will fit in the window.

  Return Value:
        These functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        border                                  Y       -      4.0
        wborder                                 Y       -      4.0
        box                                     Y       Y       Y
        hline                                   Y       -      4.0
        vline                                   Y       -      4.0
        whline                                  Y       -      4.0
        wvline                                  Y       -      4.0
        mvhline                                 Y
        mvvline                                 Y
        mvwhline                                Y
        mvwvline                                Y
        border_set                              Y
        wborder_set                             Y
        box_set                                 Y
        hline_set                               Y
        vline_set                               Y
        whline_set                              Y
        wvline_set                              Y
        mvhline_set                             Y
        mvvline_set                             Y
        mvwhline_set                            Y
        mvwvline_set                            Y



--------------------------------------------------------------------------


  Name:                                                         clear

  Synopsis:
        int clear(void);
        int wclear(WINDOW *win);
        int erase(void);
        int werase(WINDOW *win);
        int clrtobot(void);
        int wclrtobot(WINDOW *win);
        int clrtoeol(void);
        int wclrtoeol(WINDOW *win);

  Description:
        erase() and werase() copy blanks (i.e. the background chtype) to 
        every cell of the window.

        clear() and wclear() are similar to erase() and werase(), but
        they also call clearok() to ensure that the the window is 
        cleared on the next wrefresh().

        clrtobot() and wclrtobot() clear the window from the current 
        cursor position to the end of the window.

        clrtoeol() and wclrtoeol() clear the window from the current
        cursor position to the end of the current line.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        clear                                   Y       Y       Y
        wclear                                  Y       Y       Y
        erase                                   Y       Y       Y
        werase                                  Y       Y       Y
        clrtobot                                Y       Y       Y
        wclrtobot                               Y       Y       Y
        clrtoeol                                Y       Y       Y
        wclrtoeol                               Y       Y       Y



--------------------------------------------------------------------------


  Name:                                                         color

  Synopsis:
        int start_color(void);
        int init_pair(short pair, short fg, short bg);
        int init_color(short color, short red, short green, short blue);
        bool has_colors(void);
        bool can_change_color(void);
        int color_content(short color, short *red, short *green, short *blue);
        int pair_content(short pair, short *fg, short *bg);

        int assume_default_colors(int f, int b);
        int use_default_colors(void);

        int PDC_set_line_color(short color);

  Description:
        To use these routines, start_color() must be called, usually
        immediately after initscr(). Colors are always used in pairs, 
        referred to as color-pairs. A color-pair consists of a 
        foreground color and a background color. A color-pair is 
        initialized via init_pair(). After initialization, COLOR_PAIR(n) 
        can be used like any other video attribute.

        start_color() initializes eight basic colors (black, red, green,
        yellow, blue, magenta, cyan, and white), and two global
        variables; COLORS and COLOR_PAIRS (respectively defining the
        maximum number of colors and color-pairs the terminal is capable
        of displaying).

        init_pair() changes the definition of a color-pair. It takes 
        three arguments: the number of the color-pair to be redefined, 
        and the new values of the foreground and background colors. The 
        pair number must be between 0 and COLOR_PAIRS - 1, inclusive. 
        The foreground and background must be between 0 and COLORS - 1, 
        inclusive. If the color pair was previously initialized, the 
        screen is refreshed, and all occurrences of that color-pair are 
        changed to the new definition.

        has_colors() indicates if the terminal supports, and can 
        maniplulate color. It returns TRUE or FALSE.

        can_change_color() indicates if the terminal has the capability
        to change the definition of its colors.

        pair_content() is used to determine what the colors of a given
        color-pair consist of.

        assume_default_colors() and use_default_colors() emulate the
        ncurses extensions of the same names. assume_default_colors(f,
        b) is essentially the same as init_pair(0, f, b) (which isn't
        allowed); it redefines the default colors. use_default_colors()
        allows the use of -1 as a foreground or background color with
        init_pair(), and calls assume_default_colors(-1, -1); -1
        represents the foreground or background color that the terminal
        had at startup. If the environment variable PDC_ORIGINAL_COLORS
        is set at the time start_color() is called, that's equivalent to
        calling use_default_colors().

        PDC_set_line_color() is used to set the color, globally, for
        the color of the lines drawn for the attributes: A_UNDERLINE,
        A_OVERLINE, A_LEFTLINE and A_RIGHTLINE. A value of -1 (the
        default) indicates that the current foreground color should be
        used.

        NOTE: COLOR_PAIR() and PAIR_NUMBER() are implemented as macros.

  Return Value:
        All functions return OK on success and ERR on error, except for
        has_colors() and can_change_colors(), which return TRUE or FALSE.

  Portability                                X/Open    BSD    SYS V
        start_color                             Y       -      3.2
        init_pair                               Y       -      3.2
        init_color                              Y       -      3.2
        has_colors                              Y       -      3.2
        can_change_color                        Y       -      3.2
        color_content                           Y       -      3.2
        pair_content                            Y       -      3.2
        assume_default_colors                   -       -       -
        use_default_colors                      -       -       -
        PDC_set_line_color                      -       -       -



--------------------------------------------------------------------------


  Name:                                                         debug

  Synopsis:
        void traceon(void);
        void traceoff(void);
        void PDC_debug(const char *, ...);

  Description:
        traceon() and traceoff() toggle the recording of debugging 
        information to the file "trace". Although not standard, similar 
        functions are in some other curses implementations.

        PDC_debug() is the function that writes to the file, based on 
        whether traceon() has been called. It's used from the PDC_LOG() 
        macro.

  Portability                                X/Open    BSD    SYS V
        traceon                                 -       -       -
        traceoff                                -       -       -
        PDC_debug                               -       -       -



--------------------------------------------------------------------------


  Name:                                                         delch

  Synopsis:
        int delch(void);
        int wdelch(WINDOW *win);
        int mvdelch(int y, int x);
        int mvwdelch(WINDOW *win, int y, int x);

  Description:
        The character under the cursor in the window is deleted.  All
        characters to the right on the same line are moved to the left
        one position and the last character on the line is filled with
        a blank.  The cursor position does not change (after moving to
        y, x if coordinates are specified).

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        delch                                   Y       Y       Y
        wdelch                                  Y       Y       Y
        mvdelch                                 Y       Y       Y
        mvwdelch                                Y       Y       Y



--------------------------------------------------------------------------


  Name:                                                         deleteln

  Synopsis:
        int deleteln(void);
        int wdeleteln(WINDOW *win);
        int insdelln(int n);
        int winsdelln(WINDOW *win, int n);
        int insertln(void);
        int winsertln(WINDOW *win);

        int mvdeleteln(int y, int x);
        int mvwdeleteln(WINDOW *win, int y, int x);
        int mvinsertln(int y, int x);
        int mvwinsertln(WINDOW *win, int y, int x);

  Description:
        With the deleteln() and wdeleteln() functions, the line under
        the cursor in the window is deleted.  All lines below the
        current line are moved up one line.  The bottom line of the
        window is cleared.  The cursor position does not change.

        With the insertln() and winsertn() functions, a blank line is 
        inserted above the current line and the bottom line is lost.

        mvdeleteln(), mvwdeleteln(), mvinsertln() and mvwinsertln() 
        allow moving the cursor and inserting/deleting in one call.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        deleteln                                Y       Y       Y
        wdeleteln                               Y       Y       Y
        mvdeleteln                              -       -       -
        mvwdeleteln                             -       -       -
        insdelln                                Y       -      4.0
        winsdelln                               Y       -      4.0
        insertln                                Y       Y       Y
        winsertln                               Y       Y       Y
        mvinsertln                              -       -       -
        mvwinsertln                             -       -       -



--------------------------------------------------------------------------


  Name:                                                         getch

  Synopsis:
        int getch(void);
        int wgetch(WINDOW *win);
        int mvgetch(int y, int x);
        int mvwgetch(WINDOW *win, int y, int x);
        int ungetch(int ch);
        int flushinp(void);

        int get_wch(wint_t *wch);
        int wget_wch(WINDOW *win, wint_t *wch);
        int mvget_wch(int y, int x, wint_t *wch);
        int mvwget_wch(WINDOW *win, int y, int x, wint_t *wch);
        int unget_wch(const wchar_t wch);

        unsigned long PDC_get_key_modifiers(void);
        int PDC_save_key_modifiers(bool flag);
        int PDC_return_key_modifiers(bool flag);

  Description:
        With the getch(), wgetch(), mvgetch(), and mvwgetch() functions, 
        a character is read from the terminal associated with the window. 
        In nodelay mode, if there is no input waiting, the value ERR is 
        returned. In delay mode, the program will hang until the system 
        passes text through to the program. Depending on the setting of 
        cbreak(), this will be after one character or after the first 
        newline.  Unless noecho() has been set, the character will also 
        be echoed into the designated window.

        If keypad() is TRUE, and a function key is pressed, the token for
        that function key will be returned instead of the raw characters.
        Possible function keys are defined in <curses.h> with integers
        beginning with 0401, whose names begin with KEY_.

        If nodelay(win, TRUE) has been called on the window and no input
        is waiting, the value ERR is returned.

        ungetch() places ch back onto the input queue to be returned by 
        the next call to wgetch().

        flushinp() throws away any type-ahead that has been typed by the 
        user and has not yet been read by the program.

        PDC_get_key_modifiers() returns the keyboard modifiers (shift, 
        control, alt, numlock) effective at the time of the last getch() 
        call, if PDC_save_key_modifiers(TRUE) has been called before the 
        getch(). Use the macros PDC_KEY_MODIFIER_* to determine which 
        modifier(s) were set. PDC_return_key_modifiers() tells getch() 
        to return modifier keys pressed alone as keystrokes (KEY_ALT_L, 
        etc.). These may not work on all platforms.

        NOTE: getch() and ungetch() are implemented as macros, to avoid 
        conflict with many DOS compiler's runtime libraries.

  Return Value:
        These functions return ERR or the value of the character, meta 
        character or function key token.

  Portability                                X/Open    BSD    SYS V
        getch                                   Y       Y       Y
        wgetch                                  Y       Y       Y
        mvgetch                                 Y       Y       Y
        mvwgetch                                Y       Y       Y
        ungetch                                 Y       Y       Y
        flushinp                                Y       Y       Y
        get_wch                                 Y
        wget_wch                                Y
        mvget_wch                               Y
        mvwget_wch                              Y
        unget_wch                               Y
        PDC_get_key_modifiers                   -       -       -



--------------------------------------------------------------------------


  Name:                                                         getstr

  Synopsis:
        int getstr(char *str);
        int wgetstr(WINDOW *win, char *str);
        int mvgetstr(int y, int x, char *str);
        int mvwgetstr(WINDOW *win, int y, int x, char *str);
        int getnstr(char *str, int n);
        int wgetnstr(WINDOW *win, char *str, int n);
        int mvgetnstr(int y, int x, char *str, int n);
        int mvwgetnstr(WINDOW *win, int y, int x, char *str, int n);

        int get_wstr(wint_t *wstr);
        int wget_wstr(WINDOW *win, wint_t *wstr);
        int mvget_wstr(int y, int x, wint_t *wstr);
        int mvwget_wstr(WINDOW *win, int, int, wint_t *wstr);
        int getn_wstr(wint_t *wstr, int n);
        int wgetn_wstr(WINDOW *win, wint_t *wstr, int n);
        int mvgetn_wstr(int y, int x, wint_t *wstr, int n);
        int mvwgetn_wstr(WINDOW *win, int y, int x, wint_t *wstr, int n);

  Description:
        These routines call wgetch() repeatedly to build a string, 
        interpreting erase and kill characters along the way, until a 
        newline or carriage return is received. When PDCurses is built 
        with wide-character support enabled, the narrow-character 
        functions convert the wgetch()'d values into a multibyte string 
        in the current locale before returning it. The resulting string 
        is placed in the area pointed to by *str. The routines with n as 
        the last argument read at most n characters.

        Note that there's no way to know how long the buffer passed to 
        wgetstr() is, so use wgetnstr() to avoid buffer overflows.

  Return Value:
        This functions return ERR on failure or any other value on 
        success.

  Portability                                X/Open    BSD    SYS V
        getstr                                  Y       Y       Y
        wgetstr                                 Y       Y       Y
        mvgetstr                                Y       Y       Y
        mvwgetstr                               Y       Y       Y
        getnstr                                 Y       -      4.0
        wgetnstr                                Y       -      4.0
        mvgetnstr                               Y       -       -
        mvwgetnstr                              Y       -       -
        get_wstr                                Y
        wget_wstr                               Y
        mvget_wstr                              Y
        mvwget_wstr                             Y
        getn_wstr                               Y
        wgetn_wstr                              Y
        mvgetn_wstr                             Y
        mvwgetn_wstr                            Y



--------------------------------------------------------------------------


  Name:                                                         getyx

  Synopsis:
        void getyx(WINDOW *win, int y, int x);
        void getparyx(WINDOW *win, int y, int x);
        void getbegyx(WINDOW *win, int y, int x);
        void getmaxyx(WINDOW *win, int y, int x);

        void getsyx(int y, int x);
        int setsyx(int y, int x);

        int getbegy(WINDOW *win);
        int getbegx(WINDOW *win);
        int getcury(WINDOW *win);
        int getcurx(WINDOW *win);
        int getpary(WINDOW *win);
        int getparx(WINDOW *win);
        int getmaxy(WINDOW *win);
        int getmaxx(WINDOW *win);

  Description:
        The getyx() macro (defined in curses.h -- the prototypes here 
        are merely illustrative) puts the current cursor position of the 
        specified window into y and x. getbegyx() and getmaxyx() return 
        the starting coordinates and size of the specified window, 
        respectively. getparyx() returns the starting coordinates of the 
        parent's window, if the specified window is a subwindow; 
        otherwise it sets y and x to -1. These are all macros.

        getsyx() gets the coordinates of the virtual screen cursor, and
        stores them in y and x. If leaveok() is TRUE, it returns -1, -1.
        If lines have been removed with ripoffline(), then getsyx()
        includes these lines in its count; so, the returned y and x
        values should only be used with setsyx().

        setsyx() sets the virtual screen cursor to the y, x coordinates.
        If y, x are -1, -1, leaveok() is set TRUE.

        getsyx() and setsyx() are meant to be used by a library routine
        that manipulates curses windows without altering the position of
        the cursor. Note that getsyx() is defined only as a macro.

        getbegy(), getbegx(), getcurx(), getcury(), getmaxy(),
        getmaxx(), getpary(), and getparx() return the appropriate
        coordinate or size values, or ERR in the case of a NULL window.

  Portability                                X/Open    BSD    SYS V
        getyx                                   Y       Y       Y
        getparyx                                -       -      4.0
        getbegyx                                -       -      3.0
        getmaxyx                                -       -      3.0
        getsyx                                  -       -      3.0
        setsyx                                  -       -      3.0
        getbegy                                 -       -       -
        getbegx                                 -       -       -
        getcury                                 -       -       -
        getcurx                                 -       -       -
        getpary                                 -       -       -
        getparx                                 -       -       -
        getmaxy                                 -       -       -
        getmaxx                                 -       -       -



--------------------------------------------------------------------------


  Name:                                                         inch

  Synopsis:
        chtype inch(void);
        chtype winch(WINDOW *win);
        chtype mvinch(int y, int x);
        chtype mvwinch(WINDOW *win, int y, int x);

        int in_wch(cchar_t *wcval);
        int win_wch(WINDOW *win, cchar_t *wcval);
        int mvin_wch(int y, int x, cchar_t *wcval);
        int mvwin_wch(WINDOW *win, int y, int x, cchar_t *wcval);

  Description:
        The inch() functions retrieve the character and attribute from 
        the current or specified window position, in the form of a 
        chtype. If a NULL window is specified, (chtype)ERR is returned.

        The in_wch() functions are the wide-character versions; instead 
        of returning a chtype, they store a cchar_t at the address 
        specified by wcval, and return OK or ERR. (No value is stored 
        when ERR is returned.) Note that in PDCurses, chtype and cchar_t 
        are the same.

  Portability                                X/Open    BSD    SYS V
        inch                                    Y       Y       Y
        winch                                   Y       Y       Y
        mvinch                                  Y       Y       Y
        mvwinch                                 Y       Y       Y
        in_wch                                  Y
        win_wch                                 Y
        mvin_wch                                Y
        mvwin_wch                               Y



--------------------------------------------------------------------------


  Name:                                                         inchstr

  Synopsis:
        int inchstr(chtype *ch);
        int inchnstr(chtype *ch, int n);
        int winchstr(WINDOW *win, chtype *ch);
        int winchnstr(WINDOW *win, chtype *ch, int n);
        int mvinchstr(int y, int x, chtype *ch);
        int mvinchnstr(int y, int x, chtype *ch, int n);
        int mvwinchstr(WINDOW *, int y, int x, chtype *ch);
        int mvwinchnstr(WINDOW *, int y, int x, chtype *ch, int n);

        int in_wchstr(cchar_t *wch);
        int in_wchnstr(cchar_t *wch, int n);
        int win_wchstr(WINDOW *win, cchar_t *wch);
        int win_wchnstr(WINDOW *win, cchar_t *wch, int n);
        int mvin_wchstr(int y, int x, cchar_t *wch);
        int mvin_wchnstr(int y, int x, cchar_t *wch, int n);
        int mvwin_wchstr(WINDOW *win, int y, int x, cchar_t *wch);
        int mvwin_wchnstr(WINDOW *win, int y, int x, cchar_t *wch, int n);

  Description:
        These routines read a chtype or cchar_t string from the window, 
        starting at the current or specified position, and ending at the 
        right margin, or after n elements, whichever is less.

  Return Value:
        All functions return the number of elements read, or ERR on 
        error.

  Portability                                X/Open    BSD    SYS V
        inchstr                                 Y       -      4.0
        winchstr                                Y       -      4.0
        mvinchstr                               Y       -      4.0
        mvwinchstr                              Y       -      4.0
        inchnstr                                Y       -      4.0
        winchnstr                               Y       -      4.0
        mvinchnstr                              Y       -      4.0
        mvwinchnstr                             Y       -      4.0
        in_wchstr                               Y
        win_wchstr                              Y
        mvin_wchstr                             Y
        mvwin_wchstr                            Y
        in_wchnstr                              Y
        win_wchnstr                             Y
        mvin_wchnstr                            Y
        mvwin_wchnstr                           Y



--------------------------------------------------------------------------


  Name:                                                         initscr

  Synopsis:
        WINDOW *initscr(void);
        WINDOW *Xinitscr(int argc, char *argv[]);
        int endwin(void);
        bool isendwin(void);
        SCREEN *newterm(const char *type, FILE *outfd, FILE *infd);
        SCREEN *set_term(SCREEN *new);
        void delscreen(SCREEN *sp);

        int resize_term(int nlines, int ncols);
        bool is_termresized(void);
        const char *curses_version(void);

  Description:
        initscr() should be the first curses routine called.  It will 
        initialize all curses data structures, and arrange that the 
        first call to refresh() will clear the screen.  In case of 
        error, initscr() will write a message to standard error and end 
        the program.

        endwin() should be called before exiting or escaping from curses 
        mode temporarily.  It will restore tty modes, move the cursor to 
        the lower left corner of the screen and reset the terminal into 
        the proper non-visual mode.  To resume curses after a temporary 
        escape, call refresh() or doupdate().

        isendwin() returns TRUE if endwin() has been called without a 
        subsequent refresh, unless SP is NULL.

        In some implementations of curses, newterm() allows the use of 
        multiple terminals. Here, it's just an alternative interface for 
        initscr(). It always returns SP, or NULL.

        delscreen() frees the memory allocated by newterm() or
        initscr(), since it's not freed by endwin(). This function is
        usually not needed. In PDCurses, the parameter must be the
        value of SP, and delscreen() sets SP to NULL.

        set_term() does nothing meaningful in PDCurses, but is included 
        for compatibility with other curses implementations.

        resize_term() is effectively two functions: When called with 
        nonzero values for nlines and ncols, it attempts to resize the 
        screen to the given size. When called with (0, 0), it merely 
        adjusts the internal structures to match the current size after 
        the screen is resized by the user. On the currently supported 
        platforms, this functionality is mutually exclusive: X11 allows 
        user resizing, while DOS, OS/2 and Win32 allow programmatic 
        resizing. If you want to support user resizing, you should check 
        for getch() returning KEY_RESIZE, and/or call is_termresized() 
        at appropriate times; if either condition occurs, call 
        resize_term(0, 0). Then, with either user or programmatic 
        resizing, you'll have to resize any windows you've created, as 
        appropriate; resize_term() only handles stdscr and curscr.

        is_termresized() returns TRUE if the curses screen has been
        resized by the user, and a call to resize_term() is needed. 
        Checking for KEY_RESIZE is generally preferable, unless you're 
        not handling the keyboard.

        curses_version() returns a string describing the version of 
        PDCurses.

  Return Value:
        All functions return NULL on error, except endwin(), which
        returns ERR on error.

  Portability                                X/Open    BSD    SYS V
        initscr                                 Y       Y       Y
        endwin                                  Y       Y       Y
        isendwin                                Y       -      3.0
        newterm                                 Y       -       Y
        set_term                                Y       -       Y
        delscreen                               Y       -      4.0
        resize_term                             -       -       -
        is_termresized                          -       -       -
        curses_version                          -       -       -



--------------------------------------------------------------------------


  Name:                                                         inopts

  Synopsis:
        int cbreak(void);
        int nocbreak(void);
        int echo(void);
        int noecho(void);
        int halfdelay(int tenths);
        int intrflush(WINDOW *win, bool bf);
        int keypad(WINDOW *win, bool bf);
        int meta(WINDOW *win, bool bf);
        int nl(void);
        int nonl(void);
        int nodelay(WINDOW *win, bool bf);
        int notimeout(WINDOW *win, bool bf);
        int raw(void);
        int noraw(void);
        void noqiflush(void);
        void qiflush(void);
        void timeout(int delay);
        void wtimeout(WINDOW *win, int delay);
        int typeahead(int fildes);

        int crmode(void);
        int nocrmode(void);

  Description:
        cbreak() and nocbreak() toggle cbreak mode. In cbreak mode, 
        characters typed by the user are made available immediately, and 
        erase/kill character processing is not performed.  In nocbreak 
        mode, typed characters are buffered until a newline or carriage 
        return. Interrupt and flow control characters are unaffected by 
        this mode. PDCurses always starts in cbreak mode.

        echo() and noecho() control whether typed characters are echoed 
        by the input routine.  Initially, input characters are echoed.  
        Subsequent calls to echo() and noecho() do not flush type-ahead.

        halfdelay() is similar to cbreak(), but allows for a time limit 
        to be specified, in tenths of a second. This causes getch() to 
        block for that period before returning ERR if no key has been 
        received.  tenths must be between 1 and 255.

        keypad() controls whether getch() returns function/special keys 
        as single key codes (e.g., the left arrow key as KEY_LEFT). Per 
        X/Open, the default for keypad mode is OFF. You'll probably want 
        it on. With keypad mode off, if a special key is pressed, 
        getch() does nothing or returns ERR.

        nodelay() controls whether wgetch() is a non-blocking call. If 
        the option is enabled, and no input is ready, wgetch() will 
        return ERR. If disabled, wgetch() will hang until input is 
        ready.

        nl() enables the translation of a carriage return into a newline 
        on input. nonl() disables this. Initially, the translation does 
        occur.

        raw() and noraw() toggle raw mode. Raw mode is similar to cbreak 
        mode, in that characters typed are immediately passed through to 
        the user program.  The difference is that in raw mode, the INTR, 
        QUIT, SUSP, and STOP characters are passed through without being 
        interpreted, and without generating a signal.

        In PDCurses, the meta() function sets raw mode on or off.

        timeout() and wtimeout() set blocking or non-blocking reads for 
        the specified window. The delay is measured in milliseconds. If 
        it's negative, a blocking read is used; if zero, then non- 
        blocking reads are done -- if no input is waiting, ERR is 
        returned immediately. If the delay is positive, the read blocks 
        for the delay period; if the period expires, ERR is returned.

        intrflush(), notimeout(), noqiflush(), qiflush() and typeahead()
        do nothing in PDCurses, but are included for compatibility with 
        other curses implementations.

        crmode() and nocrmode() are archaic equivalents to cbreak() and 
        nocbreak(), respectively.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        cbreak                                  Y       Y       Y
        nocbreak                                Y       Y       Y
        echo                                    Y       Y       Y
        noecho                                  Y       Y       Y
        halfdelay                               Y       -       Y
        intrflush                               Y       -       Y
        keypad                                  Y       -       Y
        meta                                    Y       -       Y
        nl                                      Y       Y       Y
        nonl                                    Y       Y       Y
        nodelay                                 Y       -       Y
        notimeout                               Y       -       Y
        raw                                     Y       Y       Y
        noraw                                   Y       Y       Y
        noqiflush                               Y       -       Y
        qiflush                                 Y       -       Y
        timeout                                 Y       -       Y
        wtimeout                                Y       -       Y
        typeahead                               Y       -       Y
        crmode                                  -
        nocrmode                                -



--------------------------------------------------------------------------


  Name:                                                         insch

  Synopsis:
        int insch(chtype ch);
        int winsch(WINDOW *win, chtype ch);
        int mvinsch(int y, int x, chtype ch);
        int mvwinsch(WINDOW *win, int y, int x, chtype ch);

        int insrawch(chtype ch);
        int winsrawch(WINDOW *win, chtype ch);
        int mvinsrawch(int y, int x, chtype ch);
        int mvwinsrawch(WINDOW *win, int y, int x, chtype ch);

        int ins_wch(const cchar_t *wch);
        int wins_wch(WINDOW *win, const cchar_t *wch);
        int mvins_wch(int y, int x, const cchar_t *wch);
        int mvwins_wch(WINDOW *win, int y, int x, const cchar_t *wch);

  Description:
        The insch() functions insert a chtype into the window at the 
        current or specified cursor position. The cursor is NOT 
        advanced. A newline is equivalent to clrtoeol(); tabs are 
        expanded; other control characters are converted as with 
        unctrl().

        The ins_wch() functions are the wide-character
        equivalents, taking cchar_t pointers rather than chtypes.

        Video attributes can be combined with a character by ORing
        them into the parameter. Text, including attributes, can be 
        copied from one place to another using inch() and insch().

        insrawch() etc. are PDCurses-specific wrappers for insch() etc. 
        that disable the translation of control characters.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        insch                                   Y       Y       Y
        winsch                                  Y       Y       Y
        mvinsch                                 Y       Y       Y
        mvwinsch                                Y       Y       Y
        insrawch                                -       -       -
        winsrawch                               -       -       -
        ins_wch                                 Y
        wins_wch                                Y
        mvins_wch                               Y
        mvwins_wch                              Y



--------------------------------------------------------------------------


  Name:                                                         insstr

  Synopsis:
        int insstr(const char *str);
        int insnstr(const char *str, int n);
        int winsstr(WINDOW *win, const char *str);
        int winsnstr(WINDOW *win, const char *str, int n);
        int mvinsstr(int y, int x, const char *str);
        int mvinsnstr(int y, int x, const char *str, int n);
        int mvwinsstr(WINDOW *win, int y, int x, const char *str);
        int mvwinsnstr(WINDOW *win, int y, int x, const char *str, int n);

        int ins_wstr(const wchar_t *wstr);
        int ins_nwstr(const wchar_t *wstr, int n);
        int wins_wstr(WINDOW *win, const wchar_t *wstr);
        int wins_nwstr(WINDOW *win, const wchar_t *wstr, int n);
        int mvins_wstr(int y, int x, const wchar_t *wstr);
        int mvins_nwstr(int y, int x, const wchar_t *wstr, int n);
        int mvwins_wstr(WINDOW *win, int y, int x, const wchar_t *wstr);
        int mvwins_nwstr(WINDOW *win, int y, int x, const wchar_t *wstr, int n);

  Description:
        The insstr() functions insert a character string into a window
        at the current cursor position, by repeatedly calling winsch().
        When PDCurses is built with wide-character support enabled, the
        narrow-character functions treat the string as a multibyte
        string in the current locale, and convert it first. All 
        characters to the right of the cursor are moved to the right, 
        with the possibility of the rightmost characters on the line 
        being lost.  The cursor position does not change (after moving 
        to y, x, if specified).  The routines with n as the last 
        argument insert at most n characters; if n is negative, then the 
        entire string is inserted.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        insstr                                  Y       -      4.0
        winsstr                                 Y       -      4.0
        mvinsstr                                Y       -      4.0
        mvwinsstr                               Y       -      4.0
        insnstr                                 Y       -      4.0
        winsnstr                                Y       -      4.0
        mvinsnstr                               Y       -      4.0
        mvwinsnstr                              Y       -      4.0
        ins_wstr                                Y
        wins_wstr                               Y
        mvins_wstr                              Y
        mvwins_wstr                             Y
        ins_nwstr                               Y
        wins_nwstr                              Y
        mvins_nwstr                             Y
        mvwins_nwstr                            Y



--------------------------------------------------------------------------


  Name:                                                         instr

  Synopsis:
        int instr(char *str);
        int innstr(char *str, int n);
        int winstr(WINDOW *win, char *str);
        int winnstr(WINDOW *win, char *str, int n);
        int mvinstr(int y, int x, char *str);
        int mvinnstr(int y, int x, char *str, int n);
        int mvwinstr(WINDOW *win, int y, int x, char *str);
        int mvwinnstr(WINDOW *win, int y, int x, char *str, int n);

        int inwstr(wchar_t *wstr);
        int innwstr(wchar_t *wstr, int n);
        int winwstr(WINDOW *win, wchar_t *wstr);
        int winnwstr(WINDOW *win, wchar_t *wstr, int n);
        int mvinwstr(int y, int x, wchar_t *wstr);
        int mvinnwstr(int y, int x, wchar_t *wstr, int n);
        int mvwinwstr(WINDOW *win, int y, int x, wchar_t *wstr);
        int mvwinnwstr(WINDOW *win, int y, int x, wchar_t *wstr, int n);

  Description:
        These functions take characters (or wide characters) from the 
        current or specified position in the window, and return them as 
        a string in str (or wstr). Attributes are ignored. The functions 
        with n as the last argument return a string at most n characters 
        long.

  Return Value:
        Upon successful completion, innstr(), mvinnstr(), mvwinnstr() 
        and winnstr() return the number of characters actually read into
        the string; instr(), mvinstr(), mvwinstr() and winstr() return 
        OK. Otherwise, all these functions return ERR.

  Portability                                X/Open    BSD    SYS V
        instr                                   Y       -      4.0
        winstr                                  Y       -      4.0
        mvinstr                                 Y       -      4.0
        mvwinstr                                Y       -      4.0
        innstr                                  Y       -      4.0
        winnstr                                 Y       -      4.0
        mvinnstr                                Y       -      4.0
        mvwinnstr                               Y       -      4.0
        inwstr                                  Y
        winwstr                                 Y
        mvinwstr                                Y
        mvwinwstr                               Y
        innwstr                                 Y
        winnwstr                                Y
        mvinnwstr                               Y
        mvwinnwstr                              Y



--------------------------------------------------------------------------


  Name:                                                         kernel

  Synopsis:
        int def_prog_mode(void);
        int def_shell_mode(void);
        int reset_prog_mode(void);
        int reset_shell_mode(void);
        int resetty(void);
        int savetty(void);
        int ripoffline(int line, int (*init)(WINDOW *, int));
        int curs_set(int visibility);
        int napms(int ms);

        int draino(int ms);
        int resetterm(void);
        int fixterm(void);
        int saveterm(void);

  Description:
        def_prog_mode() and def_shell_mode() save the current terminal
        modes as the "program" (in curses) or "shell" (not in curses)
        state for use by the reset_prog_mode() and reset_shell_mode()
        functions.  This is done automatically by initscr().

        reset_prog_mode() and reset_shell_mode() restore the terminal to
        "program" (in curses) or "shell" (not in curses) state.  These
        are done automatically by endwin() and doupdate() after an
        endwin(), so they would normally not be called before these
        functions.

        savetty() and resetty() save and restore the state of the
        terminal modes. savetty() saves the current state in a buffer,
        and resetty() restores the state to what it was at the last call
        to savetty().

        curs_set() alters the appearance of the cursor. A visibility of
        0 makes it disappear; 1 makes it appear "normal" (usually an
        underline) and 2 makes it "highly visible" (usually a block).

        ripoffline() reduces the size of stdscr by one line.  If the 
        "line" parameter is positive, the line is removed from the top 
        of the screen; if negative, from the bottom. Up to 5 lines can 
        be ripped off stdscr by calling ripoffline() repeatedly. The 
        function argument, init, is called from within initscr() or 
        newterm(), so ripoffline() must be called before either of these 
        functions.  The init function receives a pointer to a one-line 
        WINDOW, and the width of the window. Calling ripoffline() with a 
        NULL init function pointer is an error.

        napms() suspends the program for the specified number of 
        milliseconds. draino() is an archaic equivalent.

        resetterm(), fixterm() and saveterm() are archaic equivalents
        for reset_shell_mode(), reset_prog_mode() and def_prog_mode(),
        respectively.

  Return Value:
        All functions return OK on success and ERR on error, except
        curs_set(), which returns the previous visibility.

  Portability                                X/Open    BSD    SYS V
        def_prog_mode                           Y       Y       Y
        def_shell_mode                          Y       Y       Y
        reset_prog_mode                         Y       Y       Y
        reset_shell_mode                        Y       Y       Y
        resetty                                 Y       Y       Y
        savetty                                 Y       Y       Y
        ripoffline                              Y       -      3.0
        curs_set                                Y       -      3.0
        napms                                   Y       Y       Y
        draino                                  -
        resetterm                               -
        fixterm                                 -
        saveterm                                -



--------------------------------------------------------------------------


  Name:                                                         keyname

  Synopsis:
        char *keyname(int key);

        char *key_name(wchar_t c);

        bool has_key(int key);

  Description:
        keyname() returns a string corresponding to the argument key. 
        key may be any key returned by wgetch().

        key_name() is the wide-character version. It takes a wchar_t 
        parameter, but still returns a char *.

        has_key() returns TRUE for recognized keys, FALSE otherwise. 
        This function is an ncurses extension.

  Portability                                X/Open    BSD    SYS V
        keyname                                 Y       -      3.0
        key_name                                Y
        has_key                                 -       -       -



--------------------------------------------------------------------------


  Name:                                                         mouse

  Synopsis:
        int mouse_set(unsigned long mbe);
        int mouse_on(unsigned long mbe);
        int mouse_off(unsigned long mbe);
        int request_mouse_pos(void);
        int map_button(unsigned long button);
        void wmouse_position(WINDOW *win, int *y, int *x);
        unsigned long getmouse(void);
        unsigned long getbmap(void);

        int mouseinterval(int wait);
        bool wenclose(const WINDOW *win, int y, int x);
        bool wmouse_trafo(const WINDOW *win, int *y, int *x, bool to_screen);
        bool mouse_trafo(int *y, int *x, bool to_screen);
        mmask_t mousemask(mmask_t mask, mmask_t *oldmask);
        int nc_getmouse(MEVENT *event);
        int ungetmouse(MEVENT *event);

  Description:
        As of PDCurses 3.0, there are two separate mouse interfaces: the
        classic interface, which is based on the undocumented Sys V
        mouse functions; and an ncurses-compatible interface. Both are
        active at all times, and you can mix and match functions from
        each, though it's not recommended. The ncurses interface is
        essentially an emulation layer built on top of the classic
        interface; it's here to allow easier porting of ncurses apps.

        The classic interface: mouse_set(), mouse_on(), mouse_off(),
        request_mouse_pos(), map_button(), wmouse_position(),
        getmouse(), and getbmap(). An application using this interface
        would start by calling mouse_set() or mouse_on() with a non-zero
        value, often ALL_MOUSE_EVENTS. Then it would check for a
        KEY_MOUSE return from getch(). If found, it would call
        request_mouse_pos() to get the current mouse status.

        mouse_set(), mouse_on() and mouse_off() are analagous to
        attrset(), attron() and attroff().  These functions set the
        mouse button events to trap.  The button masks used in these
        functions are defined in curses.h and can be or'ed together.
        They are the group of masks starting with BUTTON1_RELEASED.

        request_mouse_pos() requests curses to fill in the Mouse_status
        structure with the current state of the mouse.

        map_button() enables the specified mouse action to activate the
        Soft Label Keys if the action occurs over the area of the screen
        where the Soft Label Keys are displayed.  The mouse actions are
        defined in curses.h in the group that starts with BUTTON_RELEASED.

        wmouse_position() determines if the current mouse position is
        within the window passed as an argument.  If the mouse is
        outside the current window, -1 is returned in the y and x
        arguments; otherwise the y and x coordinates of the mouse
        (relative to the top left corner of the window) are returned in
        y and x.

        getmouse() returns the current status of the trapped mouse
        buttons as set by mouse_set() or mouse_on().

        getbmap() returns the current status of the button action used
        to map a mouse action to the Soft Label Keys as set by the
        map_button() function.

        The ncurses interface: mouseinterval(), wenclose(),
        wmouse_trafo(), mouse_trafo(), mousemask(), nc_getmouse(), and
        ungetmouse(). A typical application using this interface would
        start by calling mousemask() with a non-zero value, often
        ALL_MOUSE_EVENTS. Then it would check for a KEY_MOUSE return
        from getch(). If found, it would call nc_getmouse() to get the
        current mouse status.

        mouseinterval() sets the timeout for a mouse click. On all
        current platforms, PDCurses receives mouse button press and
        release events, but must synthesize click events. It does this
        by checking whether a release event is queued up after a press
        event. If it gets a press event, and there are no more events
        waiting, it will wait for the timeout interval, then check again
        for a release. A press followed by a release is reported as
        BUTTON_CLICKED; otherwise it's passed through as BUTTON_PRESSED.
        The default timeout is 150ms; valid values are 0 (no clicks
        reported) through 1000ms. In x11, the timeout can also be set
        via the clickPeriod resource. The return value from
        mouseinterval() is the old timeout. To check the old value
        without setting a new one, call it with a parameter of -1. Note 
        that although there's no classic equivalent for this function 
        (apart from the clickPeriod resource), the value set applies in 
        both interfaces.

        wenclose() reports whether the given screen-relative y, x
        coordinates fall within the given window.

        wmouse_trafo() converts between screen-relative and window-
        relative coordinates. A to_screen parameter of TRUE means to
        convert from window to screen; otherwise the reverse. The
        function returns FALSE if the coordinates aren't within the
        window, or if any of the parameters are NULL. The coordinates
        have been converted when the function returns TRUE.

        mouse_trafo() is the stdscr version of wmouse_trafo().

        mousemask() is nearly equivalent to mouse_set(), but instead of
        OK/ERR, it returns the value of the mask after setting it. (This
        isn't necessarily the same value passed in, since the mask could
        be altered on some platforms.) And if the second parameter is a 
        non-null pointer, mousemask() stores the previous mask value 
        there. Also, since the ncurses interface doesn't work with 
        PDCurses' BUTTON_MOVED events, mousemask() filters them out.

        nc_getmouse() returns the current mouse status in an MEVENT 
        struct. This is equivalent to ncurses' getmouse(), renamed to 
        avoid conflict with PDCurses' getmouse(). But if you define 
        NCURSES_MOUSE_VERSION (preferably as 2) before including 
        curses.h, it defines getmouse() to nc_getmouse(), along with a 
        few other redefintions needed for compatibility with ncurses 
        code. nc_getmouse() calls request_mouse_pos(), which (not 
        getmouse()) is the classic equivalent.

        ungetmouse() is the mouse equivalent of ungetch(). However, 
        PDCurses doesn't maintain a queue of mouse events; only one can 
        be pushed back, and it can overwrite or be overwritten by real 
        mouse events.

  Portability                                X/Open    BSD    SYS V
        mouse_set                               -       -      4.0
        mouse_on                                -       -      4.0
        mouse_off                               -       -      4.0
        request_mouse_pos                       -       -      4.0
        map_button                              -       -      4.0
        wmouse_position                         -       -      4.0
        getmouse                                -       -      4.0
        getbmap                                 -       -      4.0
        mouseinterval                           -       -       -
        wenclose                                -       -       -
        wmouse_trafo                            -       -       -
        mouse_trafo                             -       -       -
        mousemask                               -       -       -
        nc_getmouse                             -       -       -
        ungetmouse                              -       -       -



--------------------------------------------------------------------------


  Name:                                                         move

  Synopsis:
        int move(int y, int x);
        int wmove(WINDOW *win, int y, int x);

  Description:
        The cursor associated with the window is moved to the given
        location.  This does not move the physical cursor of the
        terminal until refresh() is called.  The position specified is
        relative to the upper left corner of the window, which is (0,0).

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        move                                    Y       Y       Y
        wmove                                   Y       Y       Y



--------------------------------------------------------------------------


  Name:                                                         outopts

  Synopsis:
        int clearok(WINDOW *win, bool bf);
        int idlok(WINDOW *win, bool bf);
        void idcok(WINDOW *win, bool bf);
        void immedok(WINDOW *win, bool bf);
        int leaveok(WINDOW *win, bool bf);
        int setscrreg(int top, int bot);
        int wsetscrreg(WINDOW *win, int top, int bot);
        int scrollok(WINDOW *win, bool bf);

        int raw_output(bool bf);

  Description:
        With clearok(), if bf is TRUE, the next call to wrefresh() with 
        this window will clear the screen completely and redraw the 
        entire screen.

        immedok(), called with a second argument of TRUE, causes an 
        automatic wrefresh() every time a change is made to the 
        specified window.

        Normally, the hardware cursor is left at the location of the
        window being refreshed.  leaveok() allows the cursor to be
        left wherever the update happens to leave it.  It's useful
        for applications where the cursor is not used, since it reduces
        the need for cursor motions.  If possible, the cursor is made
        invisible when this option is enabled.

        wsetscrreg() sets a scrolling region in a window; "top" and 
        "bot" are the line numbers for the top and bottom margins. If 
        this option and scrollok() are enabled, any attempt to move off 
        the bottom margin will cause all lines in the scrolling region 
        to scroll up one line. setscrreg() is the stdscr version.

        idlok() and idcok() do nothing in PDCurses, but are provided for 
        compatibility with other curses implementations.

        raw_output() enables the output of raw characters using the 
        standard *add* and *ins* curses functions (that is, it disables 
        translation of control characters).

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        clearok                                 Y       Y       Y
        idlok                                   Y       Y       Y
        idcok                                   Y       -      4.0
        immedok                                 Y       -      4.0
        leaveok                                 Y       Y       Y
        setscrreg                               Y       Y       Y
        wsetscrreg                              Y       Y       Y
        scrollok                                Y       Y       Y
        raw_output                              -       -       -



--------------------------------------------------------------------------


  Name:                                                         overlay

  Synopsis:
        int overlay(const WINDOW *src_w, WINDOW *dst_w)
        int overwrite(const WINDOW *src_w, WINDOW *dst_w)
        int copywin(const WINDOW *src_w, WINDOW *dst_w, int src_tr,
                    int src_tc, int dst_tr, int dst_tc, int dst_br,
                    int dst_bc, bool overlay)

  Description:
        overlay() and overwrite() copy all the text from src_w into
        dst_w. The windows need not be the same size. Those characters
        in the source window that intersect with the destination window
        are copied, so that the characters appear in the same physical
        position on the screen. The difference between the two functions
        is that overlay() is non-destructive (blanks are not copied)
        while overwrite() is destructive (blanks are copied).

        copywin() is similar, but doesn't require that the two windows
        overlap. The arguments src_tc and src_tr specify the top left
        corner of the region to be copied. dst_tc, dst_tr, dst_br, and
        dst_bc specify the region within the destination window to copy
        to. The argument "overlay", if TRUE, indicates that the copy is
        done non-destructively (as in overlay()); blanks in the source
        window are not copied to the destination window. When overlay is
        FALSE, blanks are copied.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        overlay                                 Y       Y       Y
        overwrite                               Y       Y       Y
        copywin                                 Y       -      3.0



--------------------------------------------------------------------------


  Name:                                                         pad

  Synopsis:
        WINDOW *newpad(int nlines, int ncols);
        WINDOW *subpad(WINDOW *orig, int nlines, int ncols,
                       int begy, int begx);
        int prefresh(WINDOW *win, int py, int px, int sy1, int sx1,
                     int sy2, int sx2);
        int pnoutrefresh(WINDOW *w, int py, int px, int sy1, int sx1,
                         int sy2, int sx2);
        int pechochar(WINDOW *pad, chtype ch);
        int pecho_wchar(WINDOW *pad, const cchar_t *wch);

  Description:
        A pad is a special kind of window, which is not restricted by
        the screen size, and is not necessarily associated with a
        particular part of the screen.  You can use a pad when you need
        a large window, and only a part of the window will be on the
        screen at one time.  Pads are not refreshed automatically (e.g.,
        from scrolling or echoing of input).  You can't call wrefresh()
        with a pad as an argument; use prefresh() or pnoutrefresh()
        instead.  Note that these routines require additional parameters
        to specify the part of the pad to be displayed, and the location
        to use on the screen.

        newpad() creates a new pad data structure.  

        subpad() creates a new sub-pad within a pad, at position (begy,
        begx), with dimensions of nlines lines and ncols columns. This 
        position is relative to the pad, and not to the screen as with 
        subwin.  Changes to either the parent pad or sub-pad will affect 
        both.  When using sub-pads, you may need to call touchwin() 
        before calling prefresh().

        pnoutrefresh() copies the specified pad to the virtual screen.

        prefresh() calls pnoutrefresh(), followed by doupdate().

        These routines are analogous to wnoutrefresh() and wrefresh().
        (py, px) specifies the upper left corner of the part of the pad
        to be displayed; (sy1, sx1) and (sy2, sx2) describe the screen 
        rectangle that will contain the selected part of the pad.

        pechochar() is functionally equivalent to addch() followed by
        a call to prefresh(), with the last-used coordinates and
        dimensions. pecho_wchar() is the wide-character version.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        newpad                                  Y       -       Y
        subpad                                  Y       -       Y
        prefresh                                Y       -       Y
        pnoutrefresh                            Y       -       Y
        pechochar                               Y       -      3.0
        pecho_wchar                             Y



--------------------------------------------------------------------------


  Name:                                                         panel

  Synopsis:
        int bottom_panel(PANEL *pan);
        int del_panel(PANEL *pan);
        int hide_panel(PANEL *pan);
        int move_panel(PANEL *pan, int starty, int startx);
        PANEL *new_panel(WINDOW *win);
        PANEL *panel_above(const PANEL *pan);
        PANEL *panel_below(const PANEL *pan);
        int panel_hidden(const PANEL *pan);
        const void *panel_userptr(const PANEL *pan);
        WINDOW *panel_window(const PANEL *pan);
        int replace_panel(PANEL *pan, WINDOW *win);
        int set_panel_userptr(PANEL *pan, const void *uptr);
        int show_panel(PANEL *pan);
        int top_panel(PANEL *pan);
        void update_panels(void);

  Description:
        The panel library is built using the curses library, and any
        program using panels routines must call one of the curses
        initialization routines such as initscr(). A program using these
        routines must be linked with the panels and curses libraries.
        The header <panel.h> includes the header <curses.h>.

        The panels package gives the applications programmer a way to
        have depth relationships between curses windows; a curses window
        is associated with every panel. The panels routines allow curses
        windows to overlap without making visible the overlapped
        portions of underlying windows. The initial curses window,
        stdscr, lies beneath all panels. The set of currently visible
        panels is the 'deck' of panels.

        The panels package allows the applications programmer to create
        panels, fetch and set their associated windows, shuffle panels
        in the deck, and manipulate panels in other ways.

        bottom_panel() places pan at the bottom of the deck. The size, 
        location and contents of the panel are unchanged.

        del_panel() deletes pan, but not its associated winwow.

        hide_panel() removes a panel from the deck and thus hides it 
        from view.

        move_panel() moves the curses window associated with pan, so 
        that its upper lefthand corner is at the supplied coordinates. 
        (Do not use mvwin() on the window.)

        new_panel() creates a new panel associated with win and returns 
        the panel pointer. The new panel is placed at the top of the 
        deck.

        panel_above() returns a pointer to the panel in the deck above 
        pan, or NULL if pan is the top panel. If the value of pan passed 
        is NULL, this function returns a pointer to the bottom panel in 
        the deck.

        panel_below() returns a pointer to the panel in the deck below 
        pan, or NULL if pan is the bottom panel. If the value of pan 
        passed is NULL, this function returns a pointer to the top panel 
        in the deck.

        panel_hidden() returns OK if pan is hidden and ERR if it is not.

        panel_userptr() - Each panel has a user pointer available for 
        maintaining relevant information. This function returns a 
        pointer to that information previously set up by 
        set_panel_userptr().

        panel_window() returns a pointer to the curses window associated 
        with the panel.

        replace_panel() replaces the current window of pan with win.

        set_panel_userptr() - Each panel has a user pointer available 
        for maintaining relevant information. This function sets the 
        value of that information.

        show_panel() makes a previously hidden panel visible and places 
        it back in the deck on top.

        top_panel() places pan on the top of the deck. The size, 
        location and contents of the panel are unchanged.

        update_panels() refreshes the virtual screen to reflect the 
        depth relationships between the panels in the deck. The user 
        must use doupdate() to refresh the physical screen.

  Return Value:
        Each routine that returns a pointer to an object returns NULL if 
        an error occurs. Each panel routine that returns an integer, 
        returns OK if it executes successfully and ERR if it does not.

  Portability                                X/Open    BSD    SYS V
        bottom_panel                            -       -       Y
        del_panel                               -       -       Y
        hide_panel                              -       -       Y
        move_panel                              -       -       Y
        new_panel                               -       -       Y
        panel_above                             -       -       Y
        panel_below                             -       -       Y
        panel_hidden                            -       -       Y
        panel_userptr                           -       -       Y
        panel_window                            -       -       Y
        replace_panel                           -       -       Y
        set_panel_userptr                       -       -       Y
        show_panel                              -       -       Y
        top_panel                               -       -       Y
        update_panels                           -       -       Y

  Credits:
        Original Author - Warren Tucker <wht@n4hgf.mt-park.ga.us>



--------------------------------------------------------------------------


  Name:                                                         printw

  Synopsis:
        int printw(const char *fmt, ...);
        int wprintw(WINDOW *win, const char *fmt, ...);
        int mvprintw(int y, int x, const char *fmt, ...);
        int mvwprintw(WINDOW *win, int y, int x, const char *fmt,...);
        int vwprintw(WINDOW *win, const char *fmt, va_list varglist);
        int vw_printw(WINDOW *win, const char *fmt, va_list varglist);

  Description:
        The printw() functions add a formatted string to the window at 
        the current or specified cursor position. The format strings are 
        the same as used in the standard C library's printf(). (printw() 
        can be used as a drop-in replacement for printf().)

  Return Value:
        All functions return the number of characters printed, or 
        ERR on error.

  Portability                                X/Open    BSD    SYS V
        printw                                  Y       Y       Y
        wprintw                                 Y       Y       Y
        mvprintw                                Y       Y       Y
        mvwprintw                               Y       Y       Y
        vwprintw                                Y       -      4.0
        vw_printw                               Y



--------------------------------------------------------------------------


  Name:                                                         refresh

  Synopsis:
        int refresh(void);
        int wrefresh(WINDOW *win);
        int wnoutrefresh(WINDOW *win);
        int doupdate(void);
        int redrawwin(WINDOW *win);
        int wredrawln(WINDOW *win, int beg_line, int num_lines);

  Description:
        wrefresh() copies the named window to the physical terminal 
        screen, taking into account what is already there in order to 
        optimize cursor movement. refresh() does the same, using stdscr. 
        These routines must be called to get any output on the terminal, 
        as other routines only manipulate data structures. Unless 
        leaveok() has been enabled, the physical cursor of the terminal 
        is left at the location of the window's cursor.

        wnoutrefresh() and doupdate() allow multiple updates with more 
        efficiency than wrefresh() alone. wrefresh() works by first 
        calling wnoutrefresh(), which copies the named window to the 
        virtual screen.  It then calls doupdate(), which compares the 
        virtual screen to the physical screen and does the actual 
        update. A series of calls to wrefresh() will result in 
        alternating calls to wnoutrefresh() and doupdate(), causing 
        several bursts of output to the screen.  By first calling 
        wnoutrefresh() for each window, it is then possible to call 
        doupdate() only once.

        In PDCurses, redrawwin() is equivalent to touchwin(), and 
        wredrawln() is the same as touchline(). In some other curses 
        implementations, there's a subtle distinction, but it has no 
        meaning in PDCurses.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        refresh                                 Y       Y       Y
        wrefresh                                Y       Y       Y
        wnoutrefresh                            Y       Y       Y
        doupdate                                Y       Y       Y
        redrawwin                               Y       -      4.0
        wredrawln                               Y       -      4.0



--------------------------------------------------------------------------


  Name:                                                         scanw

  Synopsis:
        int scanw(const char *fmt, ...);
        int wscanw(WINDOW *win, const char *fmt, ...);
        int mvscanw(int y, int x, const char *fmt, ...);
        int mvwscanw(WINDOW *win, int y, int x, const char *fmt, ...);
        int vwscanw(WINDOW *win, const char *fmt, va_list varglist);
        int vw_scanw(WINDOW *win, const char *fmt, va_list varglist);

  Description:
        These routines correspond to the standard C library's scanf()
        family. Each gets a string from the window via wgetnstr(), and
        uses the resulting line as input for the scan.

  Return Value:
        On successful completion, these functions return the number of
        items successfully matched.  Otherwise they return ERR.

  Portability                                X/Open    BSD    SYS V
        scanw                                   Y       Y       Y
        wscanw                                  Y       Y       Y
        mvscanw                                 Y       Y       Y
        mvwscanw                                Y       Y       Y
        vwscanw                                 Y       -      4.0
        vw_scanw                                Y



--------------------------------------------------------------------------


  Name:                                                         scr_dump

  Synopsis:
        int putwin(WINDOW *win, FILE *filep);
        WINDOW *getwin(FILE *filep);
        int scr_dump(const char *filename);
        int scr_init(const char *filename);
        int scr_restore(const char *filename);
        int scr_set(const char *filename);

  Description:
        getwin() reads window-related data previously stored in a file 
        by putwin(). It then creates and initialises a new window using 
        that data.

        putwin() writes all data associated with a window into a file, 
        using an unspecified format. This information can be retrieved 
        later using getwin().

        scr_dump() writes the current contents of the virtual screen to 
        the file named by filename in an unspecified format.

        scr_restore() function sets the virtual screen to the contents 
        of the file named by filename, which must have been written 
        using scr_dump(). The next refresh operation restores the screen 
        to the way it looked in the dump file.

        In PDCurses, scr_init() does nothing, and scr_set() is a synonym 
        for scr_restore(). Also, scr_dump() and scr_restore() save and 
        load from curscr. This differs from some other implementations, 
        where scr_init() works with curscr, and scr_restore() works with 
        newscr; but the effect should be the same. (PDCurses has no 
        newscr.)

  Return Value:
        On successful completion, getwin() returns a pointer to the 
        window it created. Otherwise, it returns a null pointer. Other 
        functions return OK or ERR.

  Portability                                X/Open    BSD    SYS V
        putwin                                  Y
        getwin                                  Y
        scr_dump                                Y
        scr_init                                Y
        scr_restore                             Y
        scr_set                                 Y



--------------------------------------------------------------------------


  Name:                                                         scroll

  Synopsis:
        int scroll(WINDOW *win);
        int scrl(int n);
        int wscrl(WINDOW *win, int n);

  Description:
        scroll() causes the window to scroll up one line.  This involves 
        moving the lines in the window data strcture.
 
        With a positive n, scrl() and wscrl() scroll the window up n 
        lines (line i + n becomes i); otherwise they scroll the window 
        down n lines.
 
        For these functions to work, scrolling must be enabled via 
        scrollok(). Note also that scrolling is not allowed if the 
        supplied window is a pad.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        scroll                                  Y       Y       Y
        scrl                                    Y       -      4.0
        wscrl                                   Y       -      4.0



--------------------------------------------------------------------------


  Name:                                                         slk

  Synopsis:
        int slk_init(int fmt);
        int slk_set(int labnum, const char *label, int justify);
        int slk_refresh(void);
        int slk_noutrefresh(void);
        char *slk_label(int labnum);
        int slk_clear(void);
        int slk_restore(void);
        int slk_touch(void);
        int slk_attron(const chtype attrs);
        int slk_attr_on(const attr_t attrs, void *opts);
        int slk_attrset(const chtype attrs);
        int slk_attr_set(const attr_t attrs, short color_pair, void *opts);
        int slk_attroff(const chtype attrs);
        int slk_attr_off(const attr_t attrs, void *opts);
        int slk_color(short color_pair);

        int slk_wset(int labnum, const wchar_t *label, int justify);

        int PDC_mouse_in_slk(int y, int x);
        void PDC_slk_free(void);
        void PDC_slk_initialize(void);

        wchar_t *slk_wlabel(int labnum)

  Description:
        These functions manipulate a window that contain Soft Label Keys 
        (SLK). To use the SLK functions, a call to slk_init() must be 
        made BEFORE initscr() or newterm(). slk_init() removes 1 or 2 
        lines from the useable screen, depending on the format selected.

        The line(s) removed from the screen are used as a separate 
        window, in which SLKs are displayed.

        slk_init() requires a single parameter which describes the 
        format of the SLKs as follows:
 
                0       3-2-3 format
                1       4-4 format
                2       4-4-4 format (ncurses extension)
                3       4-4-4 format with index line (ncurses extension)
                        2 lines used
                55      5-5 format (pdcurses format)

        slk_refresh(), slk_noutrefresh() and slk_touch() are analogous
        to refresh(), noutrefresh() and touch().

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        slk_init                                Y       -       Y
        slk_set                                 Y       -       Y
        slk_refresh                             Y       -       Y
        slk_noutrefresh                         Y       -       Y
        slk_label                               Y       -       Y
        slk_clear                               Y       -       Y
        slk_restore                             Y       -       Y
        slk_touch                               Y       -       Y
        slk_attron                              Y       -       Y
        slk_attrset                             Y       -       Y
        slk_attroff                             Y       -       Y
        slk_attr_on                             Y
        slk_attr_set                            Y
        slk_attr_off                            Y
        slk_wset                                Y
        PDC_mouse_in_slk                        -       -       -
        PDC_slk_free                            -       -       -
        PDC_slk_initialize                      -       -       -
        slk_wlabel                              -       -       -



--------------------------------------------------------------------------


  Name:                                                         termattr

  Synopsis:
        int baudrate(void);
        char erasechar(void);
        bool has_ic(void);
        bool has_il(void);
        char killchar(void);
        char *longname(void);
        chtype termattrs(void);
        attr_t term_attrs(void);
        char *termname(void);

        int erasewchar(wchar_t *ch);
        int killwchar(wchar_t *ch);

        char wordchar(void);

  Description:
        baudrate() is supposed to return the output speed of the 
        terminal. In PDCurses, it simply returns INT_MAX.

        has_ic and has_il() return TRUE. These functions have meaning in 
        some other implementations of curses.

        erasechar() and killchar() return ^H and ^U, respectively -- the 
        ERASE and KILL characters. In other curses implementations, 
        these may vary by terminal type. erasewchar() and killwchar() 
        are the wide-character versions; they take a pointer to a 
        location in which to store the character, and return OK or ERR.

        longname() returns a pointer to a static area containing a
        verbose description of the current terminal. The maximum length
        of the string is 128 characters.  It is defined only after the
        call to initscr() or newterm().

        termname() returns a pointer to a static area containing a
        short description of the current terminal (14 characters).

        termattrs() returns a logical OR of all video attributes
        supported by the terminal.

        wordchar() is a PDCurses extension of the concept behind the 
        functions erasechar() and killchar(), returning the "delete 
        word" character, ^W.

  Portability                                X/Open    BSD    SYS V
        baudrate                                Y       Y       Y
        erasechar                               Y       Y       Y
        has_ic                                  Y       Y       Y
        has_il                                  Y       Y       Y
        killchar                                Y       Y       Y
        longname                                Y       Y       Y
        termattrs                               Y       Y       Y
        termname                                Y       Y       Y
        erasewchar                              Y
        killwchar                               Y
        term_attrs                              Y
        wordchar                                -       -       -



--------------------------------------------------------------------------


  Name:                                                         terminfo

  Synopsis:
        int mvcur(int oldrow, int oldcol, int newrow, int newcol);
        int vidattr(chtype attr);
        int vid_attr(attr_t attr, short color_pair, void *opt);
        int vidputs(chtype attr, int (*putfunc)(int));
        int vid_puts(attr_t attr, short color_pair, void *opt,
                int (*putfunc)(int));

        int del_curterm(TERMINAL *);
        int putp(const char *);
        int restartterm(const char *, int, int *);
        TERMINAL *set_curterm(TERMINAL *);
        int setterm(const char *term);
        int setupterm(const char *, int, int *);
        int tgetent(char *, const char *);
        int tgetflag(const char *);
        int tgetnum(const char *);
        char *tgetstr(const char *, char **);
        char *tgoto(const char *, int, int);
        int tigetflag(const char *);
        int tigetnum(const char *);
        char *tigetstr(const char *);
        char *tparm(const char *,long, long, long, long, long, long,
                long, long, long);
        int tputs(const char *, int, int (*)(int));

  Description:
        mvcur() lets you move the physical cursor without updating any 
        window cursor positions. It returns OK or ERR.

        The rest of these functions are currently implemented as stubs, 
        returning the appropriate errors and doing nothing else.

  Portability                                X/Open    BSD    SYS V
        mvcur                                   Y       Y       Y



--------------------------------------------------------------------------


  Name:                                                         touch

  Synopsis:
        int touchwin(WINDOW *win);
        int touchline(WINDOW *win, int start, int count);
        int untouchwin(WINDOW *win);
        int wtouchln(WINDOW *win, int y, int n, int changed);
        bool is_linetouched(WINDOW *win, int line);
        bool is_wintouched(WINDOW *win);

  Description:
        touchwin() and touchline() throw away all information about 
        which parts of the window have been touched, pretending that the 
        entire window has been drawn on.  This is sometimes necessary 
        when using overlapping windows, since a change to one window 
        will affect the other window, but the records of which lines 
        have been changed in the other window will not reflect the 
        change.

        untouchwin() marks all lines in the window as unchanged since 
        the last call to wrefresh().

        wtouchln() makes n lines in the window, starting at line y, look 
        as if they have (changed == 1) or have not (changed == 0) been 
        changed since the last call to wrefresh().

        is_linetouched() returns TRUE if the specified line in the 
        specified window has been changed since the last call to 
        wrefresh().

        is_wintouched() returns TRUE if the specified window 
        has been changed since the last call to wrefresh().

  Return Value:
        All functions return OK on success and ERR on error except
        is_wintouched() and is_linetouched().

  Portability                                X/Open    BSD    SYS V
        touchwin                                Y       Y       Y
        touchline                               Y       -      3.0
        untouchwin                              Y       -      4.0
        wtouchln                                Y       Y       Y
        is_linetouched                          Y       -      4.0
        is_wintouched                           Y       -      4.0



--------------------------------------------------------------------------


  Name:                                                         util

  Synopsis:
        char *unctrl(chtype c);
        void filter(void);
        void use_env(bool x);
        int delay_output(int ms);

        int getcchar(const cchar_t *wcval, wchar_t *wch, attr_t *attrs,
                     short *color_pair, void *opts);
        int setcchar(cchar_t *wcval, const wchar_t *wch, const attr_t attrs,
                     short color_pair, const void *opts);
        wchar_t *wunctrl(cchar_t *wc);

        int PDC_mbtowc(wchar_t *pwc, const char *s, size_t n);
        size_t PDC_mbstowcs(wchar_t *dest, const char *src, size_t n);
        size_t PDC_wcstombs(char *dest, const wchar_t *src, size_t n);

  Description:
        unctrl() expands the text portion of the chtype c into a 
        printable string. Control characters are changed to the "^X" 
        notation; others are passed through. wunctrl() is the wide- 
        character version of the function.

        filter() and use_env() are no-ops in PDCurses.

        delay_output() inserts an ms millisecond pause in output.

        getcchar() works in two modes: When wch is not NULL, it reads 
        the cchar_t pointed to by wcval and stores the attributes in 
        attrs, the color pair in color_pair, and the text in the
        wide-character string wch. When wch is NULL, getcchar() merely 
        returns the number of wide characters in wcval. In either mode, 
        the opts argument is unused.

        setcchar constructs a cchar_t at wcval from the wide-character 
        text at wch, the attributes in attr and the color pair in 
        color_pair. The opts argument is unused.

        Currently, the length returned by getcchar() is always 1 or 0.
        Similarly, setcchar() will only take the first wide character
        from wch, and ignore any others that it "should" take (i.e.,
        combining characters). Nor will it correctly handle any 
        character outside the basic multilingual plane (UCS-2).

  Return Value:
        unctrl() and wunctrl() return NULL on failure. delay_output() 
        always returns OK.

        getcchar() returns the number of wide characters wcval points to 
        when wch is NULL; when it's not, getcchar() returns OK or ERR. 

        setcchar() returns OK or ERR.

  Portability                                X/Open    BSD    SYS V
        unctrl                                  Y       Y       Y
        filter                                  Y       -      3.0
        use_env                                 Y       -      4.0
        delay_output                            Y       Y       Y
        getcchar                                Y
        setcchar                                Y
        wunctrl                                 Y
        PDC_mbtowc                              -       -       -
        PDC_mbstowcs                            -       -       -
        PDC_wcstombs                            -       -       -



--------------------------------------------------------------------------


  Name:                                                         window

  Synopsis:
        WINDOW *newwin(int nlines, int ncols, int begy, int begx);
        WINDOW *derwin(WINDOW* orig, int nlines, int ncols,
                int begy, int begx);
        WINDOW *subwin(WINDOW* orig, int nlines, int ncols,
                int begy, int begx);
        WINDOW *dupwin(WINDOW *win);
        int delwin(WINDOW *win);
        int mvwin(WINDOW *win, int y, int x);
        int mvderwin(WINDOW *win, int pary, int parx);
        int syncok(WINDOW *win, bool bf);
        void wsyncup(WINDOW *win);
        void wcursyncup(WINDOW *win);
        void wsyncdown(WINDOW *win);

        WINDOW *resize_window(WINDOW *win, int nlines, int ncols);
        int wresize(WINDOW *win, int nlines, int ncols);
        WINDOW *PDC_makelines(WINDOW *win);
        WINDOW *PDC_makenew(int nlines, int ncols, int begy, int begx);
        void PDC_sync(WINDOW *win);

  Description:
        newwin() creates a new window with the given number of lines,
        nlines and columns, ncols. The upper left corner of the window
        is at line begy, column begx. If nlines is zero, it defaults to
        LINES - begy; ncols to COLS - begx. Create a new full-screen
        window by calling newwin(0, 0, 0, 0).

        delwin() deletes the named window, freeing all associated 
        memory. In the case of overlapping windows, subwindows should be 
        deleted before the main window.

        mvwin() moves the window so that the upper left-hand corner is
        at position (y,x). If the move would cause the window to be off
        the screen, it is an error and the window is not moved. Moving
        subwindows is allowed.

        subwin() creates a new subwindow within a window.  The
        dimensions of the subwindow are nlines lines and ncols columns.
        The subwindow is at position (begy, begx) on the screen.  This
        position is relative to the screen, and not to the window orig.
        Changes made to either window will affect both.  When using this
        routine, you will often need to call touchwin() before calling
        wrefresh().

        derwin() is the same as subwin(), except that begy and begx are
        relative to the origin of the window orig rather than the
        screen.  There is no difference between subwindows and derived
        windows.

        mvderwin() moves a derived window (or subwindow) inside its
        parent window.  The screen-relative parameters of the window are
        not changed.  This routine is used to display different parts of
        the parent window at the same physical position on the screen.

        dupwin() creates an exact duplicate of the window win.

        wsyncup() causes a touchwin() of all of the window's parents.

        If wsyncok() is called with a second argument of TRUE, this
        causes a wsyncup() to be called every time the window is
        changed.

        wcursyncup() causes the current cursor position of all of a
        window's ancestors to reflect the current cursor position of the
        current window.

        wsyncdown() causes a touchwin() of the current window if any of
        its parent's windows have been touched.

        resize_window() allows the user to resize an existing window. It 
        returns the pointer to the new window, or NULL on failure.

        wresize() is an ncurses-compatible wrapper for resize_window().
        Note that, unlike ncurses, it will NOT process any subwindows of
        the window. (However, you still can call it _on_ subwindows.) It 
        returns OK or ERR.

        PDC_makenew() allocates all data for a new WINDOW * except the
        actual lines themselves. If it's unable to allocate memory for
        the window structure, it will free all allocated memory and
        return a NULL pointer.

        PDC_makelines() allocates the memory for the lines.

        PDC_sync() handles wrefresh() and wsyncup() calls when a window
        is changed.

  Return Value:
        newwin(), subwin(), derwin() and dupwin() return a pointer
        to the new window, or NULL on failure. delwin(), mvwin(),
        mvderwin() and syncok() return OK or ERR. wsyncup(),
        wcursyncup() and wsyncdown() return nothing.

  Errors:
        It is an error to call resize_window() before calling initscr().
        Also, an error will be generated if we fail to create a newly
        sized replacement window for curscr, or stdscr. This could
        happen when increasing the window size. NOTE: If this happens,
        the previously successfully allocated windows are left alone;
        i.e., the resize is NOT cancelled for those windows.

  Portability                                X/Open    BSD    SYS V
        newwin                                  Y       Y       Y
        delwin                                  Y       Y       Y
        mvwin                                   Y       Y       Y
        subwin                                  Y       Y       Y
        derwin                                  Y       -       Y
        mvderwin                                Y       -       Y
        dupwin                                  Y       -      4.0
        wsyncup                                 Y       -      4.0
        syncok                                  Y       -      4.0
        wcursyncup                              Y       -      4.0
        wsyncdown                               Y       -      4.0
        resize_window                           -       -       -
        wresize                                 -       -       -
        PDC_makelines                           -       -       -
        PDC_makenew                             -       -       -
        PDC_sync                                -       -       -



--------------------------------------------------------------------------


  Name:                                                         clipboard

  Synopsis:
        int PDC_getclipboard(char **contents, long *length);
        int PDC_setclipboard(const char *contents, long length);
        int PDC_freeclipboard(char *contents);
        int PDC_clearclipboard(void);

  Description:
        PDC_getclipboard() gets the textual contents of the system's 
        clipboard. This function returns the contents of the clipboard 
        in the contents argument. It is the responsibilitiy of the 
        caller to free the memory returned, via PDC_freeclipboard().
        The length of the clipboard contents is returned in the length 
        argument.

        PDC_setclipboard copies the supplied text into the system's 
        clipboard, emptying the clipboard prior to the copy.

        PDC_clearclipboard() clears the internal clipboard.

  Return Values:
        indicator of success/failure of call.
        PDC_CLIP_SUCCESS        the call was successful
        PDC_CLIP_MEMORY_ERROR   unable to allocate sufficient memory for 
                                the clipboard contents
        PDC_CLIP_EMPTY          the clipboard contains no text
        PDC_CLIP_ACCESS_ERROR   no clipboard support

  Portability                                X/Open    BSD    SYS V
        PDC_getclipboard                        -       -       -
        PDC_setclipboard                        -       -       -
        PDC_freeclipboard                       -       -       -
        PDC_clearclipboard                      -       -       -



--------------------------------------------------------------------------


  Name:                                                         pdckbd

  Synopsis:
        unsigned long PDC_get_input_fd(void);

  Description:
        PDC_get_input_fd() returns the file descriptor that PDCurses 
        reads its input from. It can be used for select().

  Portability                                X/Open    BSD    SYS V
        PDC_get_input_fd                        -       -       -



--------------------------------------------------------------------------


  Name:                                                         pdcsetsc

  Synopsis:
        int PDC_set_blink(bool blinkon);
        void PDC_set_title(const char *title);

  Description:
        PDC_set_blink() toggles whether the A_BLINK attribute sets an
        actual blink mode (TRUE), or sets the background color to high
        intensity (FALSE). The default is platform-dependent (FALSE in
        most cases). It returns OK if it could set the state to match 
        the given parameter, ERR otherwise. Current platforms also 
        adjust the value of COLORS according to this function -- 16 for 
        FALSE, and 8 for TRUE.

        PDC_set_title() sets the title of the window in which the curses
        program is running. This function may not do anything on some
        platforms. (Currently it only works in Win32 and X11.)

  Portability                                X/Open    BSD    SYS V
        PDC_set_blink                           -       -       -
        PDC_set_title                           -       -       -



--------------------------------------------------------------------------


  Name:                                                          sb

  Synopsis:
        int sb_init(void)
        int sb_set_horz(int total, int viewport, int cur)
        int sb_set_vert(int total, int viewport, int cur)
        int sb_get_horz(int *total, int *viewport, int *cur)
        int sb_get_vert(int *total, int *viewport, int *cur)
        int sb_refresh(void);

  Description:
        These functions manipulate the scrollbar.

  Return Value:
        All functions return OK on success and ERR on error.

  Portability                                X/Open    BSD    SYS V
        sb_init                                 -       -       -
        sb_set_horz                             -       -       -
        sb_set_vert                             -       -       -
        sb_get_horz                             -       -       -
        sb_get_vert                             -       -       -
        sb_refresh                              -       -       -



--------------------------------------------------------------------------

X11 Considerations
==================

PDCurses for X11 uses the System V IPC shared memory facility, along 
with sockets, to share data between the curses program and the child 
process created to manage the X stuff.

When compiling your application, you need to include the <curses.h> or 
<xcurses.h> that comes with PDCurses. You also need to link your code 
with libXCurses. You may need to link with the following libraries under 
X11R5:
    Xaw Xmu Xt X11

or, under X11R6:
    Xaw Xmu Xt X11 SM ICE Xext

You can run "xcurses-config --libs" to show the link parameters for your 
system. If using dynamic linking, on some systems, "-lXCurses" suffices.

By calling Xinitscr() rather than initscr(), you can pass your program 
name and resource overrides to PDCurses. The program name is used as the 
title of the X window, and for defining X resources specific to your 
program.


Interaction with stdio
----------------------

Be aware that curses programs that expect to have a normal tty 
underneath them will be very disappointed! Output directed to stdout 
will go to the xterm that invoked the PDCurses application, or to the 
console if not invoked directly from an xterm. Similarly, stdin will 
expect its input from the same place as stdout.


X Resources
-----------

PDCurses for X11 recognizes the following resources:

    lines
    cols
    normalFont
    italicFont
    pointer
    pointerForeColor
    pointerBackColor
    cursorColor
    textCursor
    colorBlack
    colorRed
    colorGreen
    colorYellow
    colorBlue
    colorMagenta
    colorCyan
    colorWhite
    colorBoldBlack
    colorBoldRed
    colorBoldGreen
    colorBoldYellow
    colorBoldBlue
    colorBoldMagenta
    colorBoldCyan
    colorBoldWhite
    bitmap
    pixmap
    translations
    shmmin
    borderWidth
    borderColor
    clickPeriod
    doubleClickPeriod
    composeKey

lines:		   Specifies the number of lines the "screen" will have.
		   Directly equates to LINES.
		   There is no theoretical maximum.
		   The minimum value must be 2.
		   Default:	   24

cols:		   Specifies the number of columns the "screen" will have.
                   Directly equates to COLS.
                   There is no theoretical maximum.
                   The minimum value must be 2.
                   Default:	   80

normalFont:	   The name of a fixed width font.
		   Default:	   7x13

italicFont:	   The name of a fixed width font to be used for
		   characters with A_ITALIC attributes. Must have the 
		   same cell size as normalFont.
		   Default:	   7x13 (obviously not an italic font)

pointer:	   The name of a valid pointer cursor.
		   Default:	   xterm

pointerForeColor:  The foreground color of the pointer.
		   Default:	   black

pointerBackColor:  The background color of the pointer.
		   Default:	   white

textCursor:	   The alignment of the text cursor; horizontal or vertical.
		   Default:	   horizontal

colorBlack:	   The color of the COLOR_BLACK attribute.
		   Default:	   Black

colorRed:	   The color of the COLOR_RED attribute.
		   Default:	   red3

colorGreen:	   The color of the COLOR_GREEN attribute.
		   Default:	   green3

colorYellow:	   The color of the COLOR_YELLOW attribute.
		   Default:	   yellow3

colorBlue:	   The color of the COLOR_BLUE attribute.
		   Default:	   blue3

colorMagenta:	   The color of the COLOR_MAGENTA attribute.
		   Default:	   magenta3

colorCyan:	   The color of the COLOR_CYAN attribute.
		   Default:	   cyan3

colorWhite:	   The color of the COLOR_WHITE attribute.
		   Default:	   Grey

colorBoldBlack:    COLOR_BLACK combined with A_BOLD.
		   Default:	   grey40

colorBoldRed:	   COLOR_RED combined with A_BOLD.
		   Default:	   red1

colorBoldGreen:    COLOR_GREEN combined with A_BOLD.
		   Default:	   green1

colorBoldYellow:   COLOR_YELLOW combined with A_BOLD.
		   Default:	   yellow1

colorBoldBlue:	   COLOR_BLUE combined with A_BOLD.
		   Default:	   blue1

colorBoldMagenta:  COLOR_MAGENTA combined with A_BOLD.
		   Default:	   magenta1

colorBoldCyan:	   COLOR_CYAN combined with A_BOLD.
		   Default:	   cyan1

colorBoldWhite:    COLOR_WHITE combined with A_BOLD.
		   Default:	   White

bitmap:		   The name of a valid bitmap file of depth 1 (black and white)
		   used for the application's icon. The file is an X bitmap.
		   Default:        a 32x32 or 64x64 pixmap depending on the 
				   window manager

pixmap:		   The name of a valid pixmap file of any depth 
		   supported by the window manager (color) for the 
		   application's icon, The file is an X11 pixmap. This 
		   resource is only available if the libXpm package has 
		   been installed (most systems have this by default). 
		   This resource overrides the "bitmap" resource.
                   Default:        none, uses default bitmap above

translations:      Translations enable the user to customize the action
		   that occurs when a key, combination of keys, or a
		   button is pressed.  The translations are similar to
		   those used by xterm.
		   Defaults:
			<Key>:		XCursesKeyPress()
			<KeyUp>:	XCursesKeyPress()
			<BtnDown>:	XCursesButton()
			<BtnUp>:	XCursesButton()
			<BtnMotion>:	XCursesButton()

		   The most useful action for KeyPress translations is 
		   string(). The argument to the string() action can be 
		   either a string or a hex representation of a 
		   character; e.g., string(0x1b) will send the ASCII
		   escape character to the application; string("[11~") 
		   will send [ 1 1 ~ , as separate keystrokes.

shmmin:		   On most systems, there are two Unix kernel parameters
		   that determine the allowable size of a shared memory
		   segment. These parameters are usually something like 
		   SHMMIN and SHMMAX. To use shared memory, a program
		   must allocate a segment of shared memory that is
		   between these two values.  Usually these values are
		   like 1 for SHMMIN and some large number for SHMMAX. 
		   Sometimes the Unix kernel is configured to have a
		   value of SHMMIN that is bigger than the size of one
		   of the shared memory segments that libXCurses uses. 
		   On these systems an error message like:

		     Cannot allocate shared memory for SCREEN: Invalid argument

		   will result. To overcome this problem, this resource 
		   should be set to the kernel value for SHMMIN. This
		   ensures that a shared memory segment will always be
		   bigger than the kernel value for SHMMIN (and
		   hopefully less than SHMMAX!)

		   Default:	   0

borderColor:	   The color of the border around the screen.
		   Default:	   black

borderWidth:	   The width in pixels of the border around the screen.
		   Default:	   0

clickPeriod:	   The period (in milliseconds) between a button 
		   press and a button release that determines if a click
		   of a button has occurred.
		   Default:	   100

doubleClickPeriod: The period (in milliseconds) between two button
		   press events that determines if a double click
		   of a button has occurred.
		   Default:	   200

composeKey:	   The name of the X key that defines the "compose key",
		   which is used to enter characters in the Latin-1 
		   character set above 0xA0. (See "Compose Keys for 
		   Latin-1" below.) This is used only when PDCurses is 
		   built without XIM support. While in compose mode, the 
		   text cursor will appear as a hollow rectangle.
		   Default:	   Multi_key


Using Resources
---------------

All applications have a top-level class name of "XCurses". If Xinitscr() 
is used, it sets an application's top-level widget name. (Otherwise the 
name defaults to "PDCurses".)

Examples for app-defaults or .Xdefaults:

!
! resources for XCurses class of programs
!
XCurses*lines:  30
XCurses*cols:   80
XCurses*normalFont:     9x13
XCurses*bitmap: /tmp/xcurses.xbm
XCurses*pointer: top_left_arrow
!
! resources for testcurs - XCurses
!
testcurs.colorRed:      orange
testcurs.colorBlack:    midnightblue
testcurs.lines: 25
*testcurs.Translations: #override \n \
  <Key>F12:  string(0x1b) string("[11~") \n
!
! resources for THE - XCurses
!
! resources with the * wildcard can be overridden by a parameter passed
! to initscr()
!
the*normalFont: 9x15
the*lines:      40
the*cols:       86
the*pointer:    xterm
the*pointerForeColor: white
the*pointerBackColor: black
!
! resources with the . format can not be overridden by a parameter passed
! to Xinitscr()
!
the.bitmap:     /home/mark/the/the64.xbm
the.pixmap:     /home/mark/the/the64.xpm

Resources may also be passed as parameters to the Xinitscr() function. 
Parameters are strings in the form of switches; e.g., to set the color 
"red" to "indianred", and the number of lines to 30, the string passed 
to Xinitscr would be: "-colorRed indianred -lines 30"


Compose Keys for Latin-1
------------------------

When built without XIM support, PDCurses for X11 provides its own, 
limited compose key system for Latin-1 characters. The available 
combinations are listed here. For a given character, any of the 
combinations shown in the last column may be used. To generate a 
character, press the "compose" key followed by one of the pairs of 
keystrokes. Where no key is evident, the spacebar is used.  Thus, to 
generate the NO-BREAK SPACE, press the "compose" key followed by two 
hits of the spacebar.

With a typical modern X server, you can get many more compose key 
combinations by using XIM instead. Configure PDCurses with --enable-xim 
to use XIM support.

This document is encoded in UTF-8.

+----+-----+---+---------------------------------+---------------------------+
|Hex | Dec |Chr| Description ISO 10646-1:1993(E) | Compose key combinations  |
+----+-----+---+---------------------------------+---------------------------+
| A0 | 160 |   | NO-BREAK SPACE			 |			     |
| A1 | 161 | ¡ | INVERTED EXCLAMATION MARK	 | !   !!		     |
| A2 | 162 | ¢ | CENT SIGN			 | c|  |c  c/  c$  C$  C|    |
| A3 | 163 | £ | POUND SIGN			 | L-  L$  L=  l-  l$  l=  |-|
| A4 | 164 | ¤ | CURRENCY SIGN			 | xo  ox  XO  g$	     |
| A5 | 165 | ¥ | YEN SIGN			 | =y  y=  =Y  Y=  Y-  y$  y-|
| A6 | 166 | ¦ | BROKEN BAR			 | |   ||  vb  VB  |^	     |
| A7 | 167 | § | SECTION SIGN			 | SO  SS  s!  S!  so	     |
| A8 | 168 | ¨ | DIAERESIS			 | "   ""		     |
| A9 | 169 | © | COPYRIGHT SIGN			 | CO  co  OC		     |
| AA | 170 | ª | FEMININE ORDINAL INDICATOR	 | sa  SA  a_  A_	     |
| AB | 171 | « | LEFT DOUBLE ANGLE QUOTES	 | <<			     |
| AC | 172 | ¬ | NOT SIGN			 | -,  no  NO		     |
| AD | 173 | ­ | SOFT HYPHEN			 | -   --		     |
| AE | 174 | ® | REGISTERED SIGN		 | RO  ro  OR		     |
| AF | 175 | ¯ | MACRON				 | -^  _^  __		     |
| B0 | 176 | ° | DEGREE SIGN			 | o   0^  0*  de  DE  ^0    |
| B1 | 177 | ± | PLUS-MINUS SIGN		 | -+  +-		     |
| B2 | 178 | ² | SUPERSCRIPT TWO		 | 2   2^  s2  ^2	     |
| B3 | 179 | ³ | SUPERSCRIPT THREE		 | 3   3^  s3  ^3	     |
| B4 | 180 | ´ | ACUTE ACCENT			 | '   ''		     |
| B5 | 181 | µ | MICRO SIGN			 | u   /u  /U  *m  *M	     |
| B6 | 182 | ¶ | PILCROW SIGN			 | p!  P!  pg  PG	     |
| B7 | 183 | · | MIDDLE DOT			 | .   .^  ..		     |
| B8 | 184 | ¸ | CEDILLA			 | ,   ,,		     |
| B9 | 185 | ¹ | SUPERSCRIPT ONE		 | 1   1^  s1  ^1	     |
| BA | 186 | º | MASCULINE ORDINAL INDICATOR	 | o_  s0  S0		     |
| BB | 187 | » | RIGHT DOUBLE ANGLE QUOTES	 | >>			     |
| BC | 188 | ¼ | VULGAR FRACTION ONE QUARTER	 | 14			     |
| BD | 189 | ½ | VULGAR FRACTION ONE HALF	 | 12			     |
| BE | 190 | ¾ | VULGAR FRACTION THREE QUARTERS  | 34			     |
| BF | 191 | ¿ | INVERTED QUESTION MARK		 | ?   ??		     |
| C0 | 192 | À | CAPITAL A WITH GRAVE ACCENT	 | `A  A`		     |
| C1 | 193 | Á | CAPITAL A WITH ACUTE ACCENT	 | 'A  A'		     |
| C2 | 194 | Â | CAPITAL A WITH CIRCUMFLEX ACCENT| ^A  A^  A>		     |
| C3 | 195 | Ã | CAPITAL A WITH TILDE		 | ~A  A~  A-		     |
| C4 | 196 | Ä | CAPITAL A WITH DIAERESIS	 | "A  A"		     |
| C5 | 197 | Å | CAPITAL A WITH RING ABOVE	 | oA  Ao  A*  OA  *A	     |
| C6 | 198 | Æ | CAPITAL LIGATURE AE		 | AE			     |
| C7 | 199 | Ç | CAPITAL C WITH CEDILLA		 | ,C  C,		     |
| C8 | 200 | È | CAPITAL E WITH GRAVE ACCENT	 | `E  E`		     |
| C9 | 201 | É | CAPITAL E WITH ACUTE ACCENT	 | 'E  E'		     |
| CA | 202 | Ê | CAPITAL E WITH CIRCUMFLEX ACCENT| ^E  E^  E>		     |
| CB | 203 | Ë | CAPITAL E WITH DIAERESIS	 | "E  E"		     |
| CC | 204 | Ì | CAPITAL I WITH GRAVE ACCENT	 | `I  I`		     |
| CD | 205 | Í | CAPITAL I WITH ACUTE ACCENT	 | 'I  I'		     |
| CE | 206 | Î | CAPITAL I WITH CIRCUMFLEX ACCENT| ^I  I^  I>		     |
| CF | 207 | Ï | CAPITAL I WITH DIAERESIS	 | "I  I"		     |
| D0 | 208 | Ð | CAPITAL ETH			 | D-			     |
| D1 | 209 | Ñ | CAPITAL N WITH TILDE		 | ~N  N~  N-		     |
| D2 | 210 | Ò | CAPITAL O WITH GRAVE ACCENT	 | `O  O`		     |
| D3 | 211 | Ó | CAPITAL O WITH ACUTE ACCENT	 | 'O  O'		     |
| D4 | 212 | Ô | CAPITAL O WITH CIRCUMFLEX ACCENT| ^O  O^  O>		     |
| D5 | 213 | Õ | CAPITAL O WITH TILDE		 | ~O  O~  O-		     |
| D6 | 214 | Ö | CAPITAL O WITH DIAERESIS	 | "O  O"		     |
| D7 | 215 | × | MULTIPLICATION SIGN		 | x   xx  XX  mu  MU	     |
| D8 | 216 | Ø | CAPITAL O WITH STROKE		 | /O  O/		     |
| D9 | 217 | Ù | CAPITAL U WITH GRAVE ACCENT	 | `U  U`		     |
| DA | 218 | Ú | CAPITAL U WITH ACUTE ACCENT	 | 'U  U'		     |
| DB | 219 | Û | CAPITAL U WITH CIRCUMFLEX ACCENT| ^U  U^  U>		     |
| DC | 220 | Ü | CAPITAL U WITH DIAERESIS	 | "U  U"		     |
| DD | 221 | Ý | CAPITAL Y WITH ACUTE ACCENT	 | 'Y  Y'		     |
| DE | 222 | Þ | CAPITAL THORN			 | P   TH  |P		     |
| DF | 223 | ß | SMALL SHARP S			 | ss			     |
| E0 | 224 | à | SMALL A WITH GRAVE ACCENT	 | `a  a`		     |
| E1 | 225 | á | SMALL A WITH ACUTE ACCENT	 | 'a  a'		     |
| E2 | 226 | â | SMALL A WITH CIRCUMFLEX ACCENT  | ^a  a^  a>		     |
| E3 | 227 | ã | SMALL A WITH TILDE		 | ~a  a~  a-		     |
| E4 | 228 | ä | SMALL A WITH DIAERESIS		 | "a  a"		     |
| E5 | 229 | å | SMALL A WITH RING ABOVE	 | oa  ao  Oa  a*  *a	     |
| E6 | 230 | æ | SMALL LIGATURE AE		 | ae			     |
| E7 | 231 | ç | SMALL C WITH CEDILLA		 | ,c  c,		     |
| E8 | 232 | è | SMALL E WITH GRAVE ACCENT	 | `e  e`		     |
| E9 | 233 | é | SMALL E WITH ACUTE ACCENT	 | 'e  e'		     |
| EA | 234 | ê | SMALL E WITH CIRCUMFLEX ACCENT  | ^e  e^  e>		     |
| EB | 235 | ë | SMALL E WITH DIAERESIS		 | "e  e"		     |
| EC | 236 | ì | SMALL I WITH GRAVE ACCENT	 | `i  i`		     |
| ED | 237 | í | SMALL I WITH ACUTE ACCENT	 | 'i  i'		     |
| EE | 238 | î | SMALL I WITH CIRCUMFLEX ACCENT  | ^i  i^  i>		     |
| EF | 239 | ï | SMALL I WITH DIAERESIS		 | "i  i"		     |
| F0 | 240 | ð | SMALL ETH			 | d-			     |
| F1 | 241 | ñ | SMALL N WITH TILDE		 | ~n  n~  n-		     |
| F2 | 242 | ò | SMALL O WITH GRAVE ACCENT	 | `o  o`		     |
| F3 | 243 | ó | SMALL O WITH ACUTE ACCENT	 | 'o  o'		     |
| F4 | 244 | ô | SMALL O WITH CIRCUMFLEX ACCENT  | ^o  o^  o>		     |
| F5 | 245 | õ | SMALL O WITH TILDE		 | ~o  o~  o-		     |
| F6 | 246 | ö | SMALL O WITH DIAERESIS		 | "o  o"		     |
| F7 | 247 | ÷ | DIVISION SIGN			 | -:  :-		     |
| F8 | 248 | ø | SMALL O WITH OBLIQUE BAR	 | /o  o/		     |
| F9 | 249 | ù | SMALL U WITH GRAVE ACCENT	 | `u  u`		     |
| FA | 250 | ú | SMALL U WITH ACUTE ACCENT	 | 'u  u'		     |
| FB | 251 | û | SMALL U WITH CIRCUMFLEX ACCENT  | ^u  u^  u>		     |
| FC | 252 | ü | SMALL U WITH DIAERESIS		 | "u  u"		     |
| FD | 253 | ý | SMALL Y WITH ACUTE ACCENT	 | 'y  y'		     |
| FE | 254 | þ | SMALL THORN			 | p   th  |p		     |
| FF | 255 | ÿ | SMALL Y WITH DIAERESIS		 | "y  y"		     |
+----+-----+---+---------------------------------+---------------------------+


Deprecated
----------

XCursesProgramName is no longer used. To set the program name, you must 
use Xinitscr(), or PDC_set_title() to set just the window title.

The XCursesExit() function is now called automatically via atexit(). 
(Multiple calls to it are OK, so you don't need to remove it if you've 
already added it for previous versions of PDCurses.)

XCURSES is no longer defined automatically, but need not be defined, 
unless you want the X11-specific prototypes. (Normal curses programs 
won't need it.)


--------------------------------------------------------------------------

SDL Considerations
==================

There are no special requirements to use PDCurses for SDL -- all 
PDCurses-compatible code should work fine. (In fact, you can even build 
against the Win32 console pdcurses.dll, and then swap in the SDL 
pdcurses.dll.) Nothing extra is needed beyond the base SDL library. 
However, there are some optional special features, described here.

The principal limitation of this port is that input is currently 
restricted to ASCII (i.e., 0-127), plus the special keys like KEY_LEFT. 
(You could have Unicode input, but then the input wouldn't match the 
output, which is in Code Page 437.) Also, see the note about the 
potential for incomplete output under "PDC_update_rects()", below.


Fonts
-----

The font is a simple BMP, 32 characters wide by 8 characters tall, 
preferably with a palette. (BMPs without palettes still work, but in 
that case, no attributes will be available, nor will the cursor work.) 
The first entry in the palette (usually black) is treated as the 
background color; the last entry (usually white) is treated as the 
foreground. These are changed or made transparent as appropriate; any 
other colors in the palette are passed through unchanged. So -- although 
a one-bit depth is sufficient for a normal font -- you could redraw some 
characters as multi-colored tiles.

The font must be monospaced. The size of each character is derived by 
dividing the width of the BMP by 32 and the height by 8. There is no 
constraint on the dimensions.

As provided in the default font and expected by acs_map[], the font is 
in Code Page 437 form. But you can of course use any layout if you're 
not relying on correct values for the ACS_* macros.

The font can be set via the environment variable PDC_FONT. If it's not 
set, PDCurses looks for a file named "pdcfont.bmp" in the current 
directory at the time of initscr(). If neither is found, it uses the 
built-in default font encoded in deffont.h.


Backgrounds
-----------

PDCurses for SDL supports an optional background image BMP. This is used 
whenever start_color() has not been called (see the ptest demo for an 
example), or when use_default_colors() has been called after 
start_color(), and the background color of a pair has been set to -1 
(see newdemo, worm, and rain for examples). The usage parallels that of 
ncurses in an appropriate terminal (e.g., Gnome Terminal). The image is 
tiled to cover the PDCurses window, and can be any size or depth.

As with the font, you can point to a location for the background via the 
environment variable PDC_BACKGROUND; "pdcback.bmp" is the fallback. 
(There is no default background.)


Icons
-----

The icon (used with SDL_WM_SetIcon() -- not used for the executable 
file) can be set via the environment variable PDC_ICON, and falls back 
to "pdcicon.bmp", and then to the built-in icon from deficon.h. The 
built-in icon is the PDCurses logo, as seen in ../x11/little_icon.xbm. 
The SDL docs say that the icon must be 32x32, at least for use with MS 
Windows.

If pdc_screen is preinitialized (see below), PDCurses does not attempt 
to set the icon.


Screen size
-----------

The default screen size is 80x25 characters (whatever size they may be), 
but you can override this via the environment variables PDC_COLS and/or 
PDC_LINES. (Some other ports use COLS and LINES; this is not done here 
because those values are, or should be, those of the controlling 
terminal, and PDCurses for SDL is independent of the terminal.) If 
pdc_screen is preinitialized (see below), these are ignored.


Integration with SDL
--------------------

If you want to go further, you can mix PDCurses and SDL functions. (Of 
course this is extremely non-portable!) To aid you, there are several 
external variables and functions specific to the SDL port; you could 
include pdcsdl.h, or just add the declarations you need in your code:

 PDCEX SDL_Surface *pdc_screen, *pdc_font, *pdc_icon, *pdc_back;
 PDCEX int pdc_sheight, pdc_swidth, pdc_yoffset, pdc_xoffset;

 void PDC_update_rects(void);
 void PDC_retile(void);

pdc_screen is the main surface, created by SDL_SetVideoMode(), unless 
it's preset before initscr(). You can perform normal SDL operations on 
this surface, but PDCurses won't respect them when it updates. (For 
that, see PDC_retile().) As an alternative, you can preinitialize this 
surface before calling initscr(). In that case, you can use pdc_sheight, 
pdc_swidth, pdc_yoffset and/or pdc_xoffset (q.v.) to confine PDCurses to 
only a specific area of the surface, reserving the rest for other SDL 
operations. If you preinitialize pdc_screen, you'll have to close it 
yourself; PDCurses will ignore resize events, and won't try to set the 
icon. Also note that if you preinitialize pdc_screen, it need not be the 
display surface.

pdc_font, pdc_icon, and pdc_back are the SDL_surfaces for the font, 
icon, and background, respectively. You can set any or all of them 
before initscr(), and thus override any of the other ways to set them. 
But note that pdc_icon will be ignored if pdc_screen is preset.

pdc_sheight and pdc_swidth are the dimensions of the area of pdc_screen 
to be used by PDCurses. You can preset them before initscr(); if either 
is not set, it defaults to the full screen size minus the x or y offset, 
as appropriate.

pdc_xoffset and pdc_yoffset are the x and y offset for the area of 
pdc_screen to be used by PDCurses. See the sdltest demo for an example.

PDC_retile() makes a copy of pdc_screen, then tiles it with the 
background image, if any. The resulting surface is used as the 
background for transparent character cells. PDC_retile() is called from 
initscr() and resize_term(). However, you can also use it at other 
times, to take advantage of the way it copies pdc_screen: Draw some SDL 
stuff; call PDC_retile(); do some curses stuff -- it will use whatever 
was on pdc_screen as the background. Then you can erase the curses 
screen, do some more SDL stuff, and call PDC_retile() again to make a 
new background. (If you don't erase the curses screen, it will be 
incorporated into the background when you call PDC_retile().) But this 
only works if no background image is set.

PDC_update_rects() is how the screen actually gets updated. For 
performance reasons, when drawing, PDCurses for SDL maintains a table of 
rectangles that need updating, and only updates (by calling this 
function) during getch(), napms(), or when the table gets full. 
Normally, this is sufficient; but if you're pausing in some way other 
than by using napms(), and you're not doing keyboard checks, you may get 
an incomplete update. If that happens, you can call PDC_update_rects() 
manually.


Interaction with stdio
----------------------

As with X11, it's a bad idea to mix curses and stdio calls. (In fact, 
that's true for PDCurses on any platform; but especially these two, 
which don't run under terminals.) Depending on how SDL is built, stdout 
and stderr may be redirected to files.
