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 the section on 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.
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 the section on 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 the
section on Supported Functions below and the section on
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 the
section on 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 the BUGS manpage 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()
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
o Curses function '%s' called with too %s arguments at ...
You have called a Curses function with a wrong number
of arguments.
o 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 the section on Unified Functions for more
information.
o 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.
o 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.
o 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.
o 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.
o 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.
o Curses::Vars::FETCH called with bad index at ... =item *
Curses::Vars::STORE called with bad index at ...
o 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
--------- -------- ------------------------
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
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
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.
Supported Variables
LINES COLS stdscr[*] curscr[*] =head2
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_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 =head2 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 the section on Perl 4.X
cursperl Compatibility for more information.