path: root/payloads/libpayload/curses/PDCurses/doc/intro.txt

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

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