NAME

SYNOPSIS

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.

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.

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.

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 %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. :-)

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
echochar Yes wechochar
addchstr Yes waddchstr mvaddchstr mvwaddchstr
addchnstr Yes waddchnstr mvaddchnstr mvwaddchnstr
addstr Yes waddstr mvaddstr mvwaddstr
addnstr Yes waddnstr mvaddnstr mvwaddnstr
attroff Yes wattroff
attron Yes wattron
attrset Yes wattrset
standend Yes wstandend
standout Yes wstandout
attr_get Yes wattr_get
attr_off Yes wattr_off
attr_on Yes wattr_on
attr_set Yes wattr_set
chgat Yes wchgat mvchgat mvwchgat
COLOR_PAIR No
PAIR_NUMBER No
beep No
flash No
bkgd Yes wbkgd
bkgdset Yes wbkgdset
getbkgd Yes
border Yes wborder
box Yes
hline Yes whline mvhline mvwhline
vline Yes wvline mvvline mvwvline
erase Yes werase
clear Yes wclear
clrtobot Yes wclrtobot
clrtoeol Yes wclrtoeol
start_color No
init_pair No
init_color No
has_colors No
can_change_color No
color_content No
pair_content No
delch Yes wdelch mvdelch mvwdelch
deleteln Yes wdeleteln
insdelln Yes winsdelln
insertln Yes winsertln
getch Yes wgetch mvgetch mvwgetch
ungetch No
has_key No
KEY_F No
getstr Yes wgetstr mvgetstr mvwgetstr
getnstr Yes wgetnstr mvgetnstr mvwgetnstr
getyx Yes
getparyx Yes
getbegyx Yes
getmaxyx Yes
inch Yes winch mvinch mvwinch
inchstr Yes winchstr mvinchstr mvwinchstr
inchnstr Yes winchnstr mvinchnstr mvwinchnstr
initscr No
endwin No
isendwin No
newterm No
set_term No
delscreen No
cbreak No
nocbreak No
echo No
noecho No
halfdelay No
intrflush Yes
keypad Yes
meta Yes
nodelay Yes
notimeout Yes
raw No
noraw No
qiflush No
noqiflush No
timeout Yes wtimeout
typeahead No
insch Yes winsch mvinsch mvwinsch
insstr Yes winsstr mvinsstr mvwinsstr
insnstr Yes winsnstr mvinsnstr mvwinsnstr
instr Yes winstr mvinstr mvwinstr
innstr Yes winnstr mvinnstr mvwinnstr
def_prog_mode No
def_shell_mode No
reset_prog_mode No
reset_shell_mode No
resetty No
savetty No
getsyx No
setsyx No
curs_set No
napms No
move Yes wmove
clearok Yes
idlok Yes
idcok Yes
immedok Yes
leaveok Yes
setscrreg Yes wsetscrreg
scrollok Yes
nl No
nonl No
overlay No
overwrite No
copywin No
newpad No
subpad No
prefresh No
pnoutrefresh No
pechochar No
refresh Yes wrefresh
noutrefresh Yes wnoutrefresh
doupdate No
redrawwin Yes
redrawln Yes wredrawln
scr_dump No
scr_restore No
scr_init No
scr_set No
scroll Yes
scrl Yes wscrl
slk_init No
slk_set No
slk_refresh No
slk_noutrefresh No
slk_label No
slk_clear No
slk_restore No
slk_touch No
slk_attron No
slk_attrset No
slk_attr No
slk_attroff No
slk_color No
baudrate No
erasechar No
has_ic No
has_il No
killchar No
longname No
termattrs No
termname No
touchwin Yes
touchline Yes
untouchwin Yes
touchln Yes wtouchln
is_linetouched Yes
is_wintouched Yes
unctrl No
keyname No
filter No
use_env No
putwin No
getwin No
delay_output No
flushinp No
newwin No
delwin Yes
mvwin Yes
subwin Yes
derwin Yes
mvderwin Yes
dupwin Yes
syncup Yes wsyncup
syncok Yes
cursyncup Yes wcursyncup
syncdown Yes wsyncdown
getmouse No
ungetmouse No
mousemask No
enclose Yes wenclose
mouse_trafo Yes wmouse_trafo
mouseinterval No
BUTTON_RELEASE No
BUTTON_PRESS No
BUTTON_CLICK No
BUTTON_DOUBLE_CLICK No
BUTTON_TRIPLE_CLICK No
BUTTON_RESERVED_EVENT No
use_default_colors No
assume_default_colors No
define_key No
keybound No
keyok No
resizeterm No
resize Yes wresize
getmaxy Yes
getmaxx Yes
flusok Yes
getcap No
touchoverlap No
new_panel No
bottom_panel No
top_panel No
show_panel No
update_panels No
hide_panel No
panel_window No
replace_panel No
move_panel No
panel_hidden No
panel_above No
panel_below No
set_panel_userptr No
panel_userptr No
del_panel No
set_menu_fore No
menu_fore No
set_menu_back No
menu_back No
set_menu_grey No
menu_grey No
set_menu_pad No
menu_pad No
pos_menu_cursor No
menu_driver No
set_menu_format No
menu_format No
set_menu_items No
menu_items No
item_count No
set_menu_mark No
menu_mark No
new_menu No
free_menu No
menu_opts No
set_menu_opts No
menu_opts_on No
menu_opts_off No
set_menu_pattern No
menu_pattern No
post_menu No
unpost_menu No
set_menu_userptr No
menu_userptr No
set_menu_win No
menu_win No
set_menu_sub No
menu_sub No
scale_menu No
set_current_item No
current_item No
set_top_row No
top_row No
item_index No
item_name No
item_description No
new_item No
free_item No
set_item_opts No
item_opts_on No
item_opts_off No
item_opts No
item_userptr No
set_item_userptr No
set_item_value No
item_value No
item_visible No
menu_request_name No
menu_request_by_name No
set_menu_spacing No
menu_spacing No
pos_form_cursor No
data_ahead No
data_behind No
form_driver No
set_form_fields No
form_fields No
field_count No
move_field No
new_form No
free_form No
set_new_page No
new_page No
set_form_opts No
form_opts_on No
form_opts_off No
form_opts No
set_current_field No
current_field No
set_form_page No
form_page No
field_index No
post_form No
unpost_form No
set_form_userptr No
form_userptr No
set_form_win No
form_win No
set_form_sub No
form_sub No
scale_form No
set_field_fore No
field_fore No
set_field_back No
field_back No
set_field_pad No
field_pad No
set_field_buffer No
field_buffer No
set_field_status No
field_status No
set_max_field No
field_info No
dynamic_field_info No
set_field_just No
field_just No
new_field No
dup_field No
link_field No
free_field No
set_field_opts No
field_opts_on No
field_opts_off No
field_opts No
set_field_userptr No
field_userptr No
field_arg No
form_request_name No
form_request_by_name No

[*] 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.