Curses - terminal screen handling and optimization
use Curses; initscr; ... endwin; Curses::supports_function($function); Curses::supports_contsant($constant);
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.
Curses
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.
addch()
waddch()
mvaddch()
mvwaddch()
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.
stdscr
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.
$Curses::OldCurses
cursperl
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.
initscr()
new Curses
It has always been the case with the curses functions, but please note that the following functions:
getstr() (and optional wgetstr(), mvgetstr(), and mvwgetstr()) inchstr() (and optional winchstr(), mvinchstr(), and mvwinchstr()) instr() (and optional winstr(), mvinstr(), and mvwinstr())
are subject to buffer overflow attack. This is because you pass in the buffer to be filled in, which has to be of finite length, but there is no way to stop a bad guy from typing.
In order to avoid this problem, use the alternate functions:
getnstr() inchnstr() innstr()
which take an extra "size of buffer" argument.
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:
curseperl
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".
BEGIN
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.
$stdscr
$curscr
curscr
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().
getstr($str)
getyx($y, $x)
$str = getstr()
($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).
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 %s at ... =item * argument is not a Curses %s at ...
The argument you gave to the function wasn't what it wanted.
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 variable '%s' is not defined by your vendor at ...
You have a Curses variable 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::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. :-)
tie
Anything else
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.
$stdscr = $stdscr
Probably many more.
William Setzer <William_Setzer@ncsu.edu>
Supported Unified? Supported via $OldCurses[*] --------- -------- ------------------------ PAUSE
[*] 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.
PAUSE
tstp _putchar fullname scanw wscanw mvscanw mvwscanw ripoffline setupterm setterm set_curterm del_curterm restartterm tparm tputs putp vidputs vidattr mvcur tigetflag tigetnum tigetstr tgetent tgetflag tgetnum tgetstr tgoto tputs
set_item_init item_init set_item_term item_term set_menu_init menu_init set_menu_term menu_term
new_fieldtype free_fieldtype set_fieldtype_arg set_fieldtype_choice link_fieldtype set_form_init form_init set_form_term form_term set_field_init field_init set_field_term field_term set_field_type field_type
To install Curses::Window, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Curses::Window
CPAN shell
perl -MCPAN -e shell install Curses::Window
For more information on module installation, please visit the detailed CPAN module installation guide.