NAME

Curses - terminal screen handling and optimization

SYNOPSIS

use Curses;

initscr;
...
endwin;

DESCRIPTION

Curses is the interface between Perl and your system's curses(3) library. For descriptions on the usage of a given function, variable, or constant, consult your system's documentation, as such information invariably varies (:-) between different curses(3) libraries and operating systems. This document describes the interface itself, and assumes that you already know how your system's curses(3) library works.

Unified Functions

Many curses(3) functions have variants starting with the prefixes w-, mv-, and/or wmv-. These variants differ only in the explicit addition of a window, or by the addition of two coordinates that are used to move the cursor first. For example, addch() has three other variants: waddch(), mvaddch(), and mvwaddch(). The variants aren't very interesting; in fact, we could roll all of the variants into original function by allowing a variable number of arguments and analyzing the argument list for which variant the user wanted to call.

Unfortunately, curses(3) predates varargs(3), so in C we were stuck with all the variants. However, Curses is a Perl interface, so we are free to "unify" these variants into one function. The section "Supported Functions" below lists all curses(3) function supported by Curses, along with a column listing if it is unified. If so, it takes a varying number of arguments as follows:

function( [win], [y, x], args );

win is an optional window argument, defaulting to stdscr if not specified.

y, x is an optional coordinate pair used to move the cursor, defaulting to no move if not specified.

args are the required arguments of the function. These are the arguments you would specify if you were just calling the base function and not any of the variants.

This makes the variants obsolete, since their functionality has been merged into a single function, so Curses does not define them by default. You can still get them if you want, by setting the variable $Curses::OldCurses to a non-zero value before using the Curses package. See "Perl 4.X cursperl Compatibility" for an example of this.

Objects

Objects are supported. Example:

$win = new Curses;
$win->addstr(10, 10, 'foo');
$win->refresh;
...

Any function that has been marked as unified (see "Supported Functions" below and "Unified Functions" above) can be called as a method for a Curses object.

Do not use initscr() if using objects, as the first call to get a new Curses will do it for you.

COMPATIBILITY

Perl 4.X cursperl Compatibility

Curses has been written to take advantage of the new features of Perl. I felt it better to provide an improved curses programming environment rather than to be 100% compatible. However, many old curseperl applications will probably still work by starting the script with:

BEGIN { $Curses::OldCurses = 1; }
use Curses;

Any old application that still does not work should print an understandable error message explaining the problem.

Some functions and variables are not supported by Curses, even with the BEGIN line. They are listed under "curses(3) items not supported by Curses".

The variables $stdscr and $curscr are also available as functions stdscr and curscr. This is because of a Perl bug. See the BUGS section for details.

Incompatibilities with previous versions of Curses

In previous versions of this software, some Perl functions took a different set of parameters than their C counterparts. This is no longer true. You should now use getstr($str) and getyx($y, $x) instead of $str = getstr() and ($y, $x) = getyx().

Incompatibilities with other Perl programs

    menu.pl, v3.0 and v3.1
	There were various interaction problems between these two
	releases and Curses.  Please upgrade to the latest version
	(v3.3 as of 3/16/96).

DIAGNOSTICS

• Curses function '%s' called with too %s arguments at ...

  You have called a Curses function with a wrong number of arguments.

• argument %d to Curses function '%s' is not a Curses window at ... =item * argument is not a Curses window at ...

  The window argument you gave to the function wasn't really a window.

  This probably means that you didn't give the right arguments to a unified function. See the DESCRIPTION section on "Unified Functions" for more information.

• Curses function '%s' is not defined by your vendor at ...

  You have a Curses function in your code that your system's curses(3) library doesn't define.

• Curses constant '%s' is not defined by your vendor at ...

  You have a Curses constant in your code that your system's curses(3) library doesn't define.

• Curses does not support the curses function '%s', used at ...

  You have a curses(3) function in your code that the Curses module doesn't support.

• Curses does not support the curses variable '%s', used at ...

  You have a curses(3) variable in your code that the Curses module doesn't support.

• Curses does not support the curses constant '%s', used at ...

  You have a bareword in your code that is trying to be interpreted as a Curses constant, but Curses doesn't know anything about it.

• Curses::Vars::FETCH called with bad index at ... =item * Curses::Vars::STORE called with bad index at ...

  You've been playing with the tie interface to the Curses variables. Don't do that. :-)

• Anything else

  Check out the perldiag man page to see if the error is in there.

BUGS

If you use the variables $stdscr and $curscr instead of their functional counterparts (stdscr and curscr), you might run into a bug in Perl where the "magic" isn't called early enough. This is manifested by the Curses package telling you $stdscr isn't a window. One workaround is to put a line like $stdscr = $stdscr near the front of your program.

Probably many more.

AUTHOR

William Setzer <William_Setzer@ncsu.edu>

SYNOPSIS OF PERL CURSES SUPPORT

Supported Functions

Supported     Unified?		Supported via $OldCurses[*]
---------     --------		------------------------
addch		Yes		waddch mvaddch mvwaddch
addchnstr	Yes		waddchnstr mvaddchnstr mvwaddchnstr
addchstr	Yes		waddchstr mvaddchstr mvwaddchstr
addnstr		Yes		waddnstr mvaddnstr mvwaddnstr
addstr		Yes		waddstr mvaddstr mvwaddstr
attroff		Yes		wattroff
attron		Yes		wattron
attrset		Yes		wattrset
baudrate	No
beep		No
bkgd		Yes		wbkgd
bkgdset		Yes		wbkgdset
border		Yes		wborder
box		Yes
can_change_color No
cbreak		No
clear		Yes		wclear
clearok		Yes
clrtobot	Yes		wclrtobot
clrtoeol	Yes		wclrtoeol
color_content	No
COLOR_PAIR	No
copywin		No
delch		Yes		wdelch mvdelch mvwdelch
deleteln	Yes		wdeleteln
delwin		Yes
derwin		Yes
doupdate	No
echo		No
echochar	Yes		wechochar
endwin		No
erase		Yes		werase
erasechar	No
flash		No
flushinp	No
flusok		Yes
getattrs	Yes
getbegyx	Yes
getbkgd		Yes
getcap		No
getch		Yes		wgetch mvgetch mvwgetch
getmaxyx	Yes
getnstr		Yes		wgetnstr mvgetnstr mvwgetnstr
getparyx	Yes
getstr		Yes		wgetstr mvgetstr mvwgetstr
gettmode	No
getyx		Yes
halfdelay	No
has_colors	No
has_ic		No
has_il		No
hline		Yes		whline
idcok		Yes
idlok		Yes
immedok		Yes
inch		Yes		winch mvinch mvwinch
inchnstr	Yes		winchnstr mvinchnstr mvwinchnstr
inchstr		Yes		winchstr mvinchstr mvwinchstr
init_color	No
init_pair	No
initscr		No
innstr		Yes		winnstr mvinnstr mvwinnstr
insch		Yes		winsch mvinsch mvwinsch
insdelln	Yes		winsdelln
insertln	Yes		winsertln
insnstr		Yes		winsnstr mvinsnstr mvwinsnstr
insstr		Yes		winsstr mvinsstr mvwinsstr
instr		Yes		winstr mvinstr mvwinstr
intrflush	Yes
is_linetouched	Yes
is_wintouched	Yes
isendwin	No
keyname		No
keypad		Yes
killchar	No
leaveok		Yes
longname	No
meta		Yes
move		Yes		wmove
mvcur		No
mvwin		Yes
newpad		No
newwin		No
nl		No
nocbreak	No
nodelay		Yes
noecho		No
nonl		No
noqiflush	No
noraw		No
notimeout	Yes
noutrefresh	Yes		wnoutrefresh
overlay		No
overwrite	No
pair_content	No
PAIR_NUMBER	No
pechochar	No
pnoutrefresh	No
prefresh	No
qiflush		No
raw		No
refresh		Yes		wrefresh
resetty		No
savetty		No
scrl		Yes		wscrl
scroll		Yes
scrollok	Yes
setscrreg	Yes		wsetscrreg
setterm		No
slk_clear	No
slk_init	No
slk_label	No
slk_noutrefresh	No
slk_refresh	No
slk_restore	No
slk_set		No
slk_touch	No
standend	Yes		wstandend
standout	Yes		wstandout
start_color	No
subpad		No
subwin		Yes
syncok		Yes
timeout		Yes		wtimeout
touchline	Yes
touchln		Yes		wtouchln
touchoverlap	No
touchwin	Yes
typeahead	No
unctrl		No
ungetch		No
vline		Yes		wvline

[*] To use any functions in this column, the variable $Curses::OldCurses must be set to a non-zero value before using the Curses package. See "Perl 4.X cursperl Compatibility" for an example of this.

Supported Variables

LINES		COLS		stdscr[*]	curscr[*]

Supported Constants

OK		ERR

ACS_BLOCK	ACS_BOARD	ACS_BTEE	ACS_BULLET
ACS_CKBOARD	ACS_DARROW	ACS_DEGREE	ACS_DIAMOND
ACS_HLINE	ACS_LANTERN	ACS_LARROW	ACS_LLCORNER
ACS_LRCORNER	ACS_LTEE	ACS_PLMINUS	ACS_PLUS
ACS_RARROW	ACS_RTEE	ACS_S1		ACS_S9
ACS_TTEE	ACS_UARROW	ACS_ULCORNER	ACS_URCORNER
ACS_VLINE

A_ALTCHARSET	A_ATTRIBUTES	A_BLINK		A_BOLD
A_CHARTEXT	A_COLOR		A_DIM		A_INVIS
A_NORMAL	A_PROTECT	A_REVERSE	A_STANDOUT
A_UNDERLINE

COLOR_BLACK	COLOR_BLUE	COLOR_CYAN	COLOR_GREEN
COLOR_MAGENTA	COLOR_RED	COLOR_WHITE	COLOR_YELLOW

KEY_A1		KEY_A3		KEY_B2		KEY_BACKSPACE
KEY_BEG		KEY_BREAK	KEY_BTAB	KEY_C1
KEY_C3		KEY_CANCEL	KEY_CATAB	KEY_CLEAR
KEY_CLOSE	KEY_COMMAND	KEY_COPY	KEY_CREATE
KEY_CTAB	KEY_DC		KEY_DL		KEY_DOWN
KEY_EIC		KEY_END		KEY_ENTER	KEY_EOL
KEY_EOS		KEY_EXIT	KEY_F0		KEY_FIND
KEY_HELP	KEY_HOME	KEY_IC		KEY_IL
KEY_LEFT	KEY_LL		KEY_MARK	KEY_MAX
KEY_MESSAGE	KEY_MIN		KEY_MOVE	KEY_NEXT
KEY_NPAGE	KEY_OPEN	KEY_OPTIONS	KEY_PPAGE
KEY_PREVIOUS	KEY_PRINT	KEY_REDO	KEY_REFERENCE
KEY_REFRESH	KEY_REPLACE	KEY_RESET	KEY_RESTART
KEY_RESUME	KEY_RIGHT	KEY_SAVE	KEY_SBEG
KEY_SCANCEL	KEY_SCOMMAND	KEY_SCOPY	KEY_SCREATE
KEY_SDC		KEY_SDL		KEY_SELECT	KEY_SEND
KEY_SEOL	KEY_SEXIT	KEY_SF		KEY_SFIND
KEY_SHELP	KEY_SHOME	KEY_SIC		KEY_SLEFT
KEY_SMESSAGE	KEY_SMOVE	KEY_SNEXT	KEY_SOPTIONS
KEY_SPREVIOUS	KEY_SPRINT	KEY_SR		KEY_SREDO
KEY_SREPLACE	KEY_SRESET	KEY_SRIGHT	KEY_SRSUME
KEY_SSAVE	KEY_SSUSPEND	KEY_STAB	KEY_SUNDO
KEY_SUSPEND	KEY_UNDO	KEY_UP

curses(3) items not supported by Curses

	Functions
	---------
	tstp printw wprintw mvprintw mvwprintw scanw wscanw mvscanw mvwscanw
	_putchar fullname
	
	Variables
	---------
	ttytype Def_term My_term
 

[*] stdscr and curscr are also available via the Perl functions stdscr and curscr. See "Perl 4.X cursperl Compatibility" for more information.

cpanm Curses

perl -MCPAN -e shell
install Curses