Curses - terminal screen handling and optimization
use Curses;
initscr;
...
endwin;
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.
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 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.
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.
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().
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).
You have called a Curses function with a wrong number of arguments.
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.
You have a Curses function in your code that your system's curses(3) library
doesn't define.
You have a Curses constant in your code that your system's curses(3) library
doesn't define.
You have a curses(3) function in your code that the Curses module doesn't support.
You have a curses(3) variable in your code that the Curses module doesn't support.
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.
You've been playing with the tie interface to the Curses
variables. Don't do that. :-)
Check out the perldiag man page to see if the error is in there.
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.
William Setzer <William_Setzer@ncsu.edu>
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
C<$Curses::OldCurses> must be set to a non-zero value before using the
C<Curses> package. See L<"Perl 4.X cursperl Compatibility"> for an
example of this.