Curses
view release on metacpan or search on metacpan
$N =~ s/^.*:://;
croak
"No '$N' in Curses module. This could be because the Curses " .
"library for which it was built does not provide the associated " .
"functions. ";
}
sub printw($@) {
my ($format, @substitutions) = @_;
addstring(sprintf($format, @substitutions));
}
tie $LINES, Curses::Vars, 1;
tie $COLS, Curses::Vars, 2;
tie $stdscr, Curses::Vars, 3;
tie $curscr, Curses::Vars, 4;
tie $COLORS, Curses::Vars, 5;
tie $COLOR_PAIRS, Curses::Vars, 6;
@EXPORT = qw(
printw
LINES $LINES COLS $COLS stdscr $stdscr curscr $curscr COLORS $COLORS
COLOR_PAIRS $COLOR_PAIRS
getchar getstring ungetchar instring addstring insstring
addch echochar addchstr addchnstr addstr addnstr attroff attron attrset
standend standout attr_get attr_off attr_on attr_set chgat COLOR_PAIR
PAIR_NUMBER beep flash bkgd bkgdset getbkgd border box hline vline
erase clear clrtobot clrtoeol start_color init_pair init_color
has_colors can_change_color color_content pair_content delch deleteln
insdelln insertln getch ungetch has_key KEY_F getstr getnstr getyx
getparyx getbegyx getmaxyx inch inchstr inchnstr initscr endwin
isendwin newterm set_term delscreen cbreak nocbreak echo noecho
halfdelay intrflush keypad meta nodelay notimeout raw noraw qiflush
noqiflush timeout typeahead insch insstr insnstr instr innstr
def_prog_mode def_shell_mode reset_prog_mode reset_shell_mode resetty
savetty getsyx setsyx curs_set napms move clearok idlok idcok immedok
leaveok setscrreg scrollok nl nonl overlay overwrite copywin newpad
subpad prefresh pnoutrefresh pechochar refresh noutrefresh doupdate
redrawwin redrawln scr_dump scr_restore scr_init scr_set scroll scrl
slk_init slk_set slk_refresh slk_noutrefresh slk_label slk_clear
slk_restore slk_touch slk_attron slk_attrset slk_attr slk_attroff
slk_color baudrate erasechar has_ic has_il killchar longname termattrs
termname touchwin touchline untouchwin touchln is_linetouched
is_wintouched unctrl keyname filter use_env putwin getwin delay_output
flushinp newwin delwin mvwin subwin derwin mvderwin dupwin syncup
syncok cursyncup syncdown getmouse ungetmouse mousemask enclose
mouse_trafo mouseinterval BUTTON_RELEASE BUTTON_PRESS BUTTON_CLICK
BUTTON_DOUBLE_CLICK BUTTON_TRIPLE_CLICK BUTTON_RESERVED_EVENT
use_default_colors assume_default_colors define_key keybound keyok
resizeterm resize getmaxy getmaxx flusok getcap touchoverlap new_panel
bottom_panel top_panel show_panel update_panels hide_panel panel_window
replace_panel move_panel panel_hidden panel_above panel_below
set_panel_userptr panel_userptr del_panel set_menu_fore menu_fore
set_menu_back menu_back set_menu_grey menu_grey set_menu_pad menu_pad
pos_menu_cursor menu_driver set_menu_format menu_format set_menu_items
menu_items item_count set_menu_mark menu_mark new_menu free_menu
menu_opts set_menu_opts menu_opts_on menu_opts_off set_menu_pattern
menu_pattern post_menu unpost_menu set_menu_userptr menu_userptr
set_menu_win menu_win set_menu_sub menu_sub scale_menu set_current_item
current_item set_top_row top_row item_index item_name item_description
new_item free_item set_item_opts item_opts_on item_opts_off item_opts
item_userptr set_item_userptr set_item_value item_value item_visible
menu_request_name menu_request_by_name set_menu_spacing menu_spacing
pos_form_cursor data_ahead data_behind form_driver set_form_fields
form_fields field_count move_field new_form free_form set_new_page
new_page set_form_opts form_opts_on form_opts_off form_opts
set_current_field current_field set_form_page form_page field_index
post_form unpost_form set_form_userptr form_userptr set_form_win
form_win set_form_sub form_sub scale_form set_field_fore field_fore
set_field_back field_back set_field_pad field_pad set_field_buffer
field_buffer set_field_status field_status set_max_field field_info
dynamic_field_info set_field_just field_just new_field dup_field
link_field free_field set_field_opts field_opts_on field_opts_off
field_opts set_field_userptr field_userptr field_arg form_request_name
form_request_by_name
ERR OK 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_ITALIC 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_EVENT 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_MOUSE 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_RESIZE 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
BUTTON1_RELEASED BUTTON1_PRESSED BUTTON1_CLICKED BUTTON1_DOUBLE_CLICKED
BUTTON1_TRIPLE_CLICKED BUTTON1_RESERVED_EVENT BUTTON2_RELEASED
BUTTON2_PRESSED BUTTON2_CLICKED BUTTON2_DOUBLE_CLICKED
BUTTON2_TRIPLE_CLICKED BUTTON2_RESERVED_EVENT BUTTON3_RELEASED
BUTTON3_PRESSED BUTTON3_CLICKED BUTTON3_DOUBLE_CLICKED
BUTTON3_TRIPLE_CLICKED BUTTON3_RESERVED_EVENT BUTTON4_RELEASED
BUTTON4_PRESSED BUTTON4_CLICKED BUTTON4_DOUBLE_CLICKED
BUTTON4_TRIPLE_CLICKED BUTTON4_RESERVED_EVENT BUTTON5_RELEASED
BUTTON5_PRESSED BUTTON5_CLICKED BUTTON5_DOUBLE_CLICKED
BUTTON5_TRIPLE_CLICKED BUTTON5_RESERVED_EVENT BUTTON_CTRL BUTTON_SHIFT
BUTTON_ALT ALL_MOUSE_EVENTS REPORT_MOUSE_POSITION NCURSES_MOUSE_VERSION
E_OK E_SYSTEM_ERROR E_BAD_ARGUMENT E_POSTED E_CONNECTED E_BAD_STATE
E_NO_ROOM E_NOT_POSTED E_UNKNOWN_COMMAND E_NO_MATCH E_NOT_SELECTABLE
E_NOT_CONNECTED E_REQUEST_DENIED E_INVALID_FIELD E_CURRENT
REQ_LEFT_ITEM REQ_RIGHT_ITEM REQ_UP_ITEM REQ_DOWN_ITEM REQ_SCR_ULINE
REQ_SCR_DLINE REQ_SCR_DPAGE REQ_SCR_UPAGE REQ_FIRST_ITEM REQ_LAST_ITEM
REQ_NEXT_ITEM REQ_PREV_ITEM REQ_TOGGLE_ITEM REQ_CLEAR_PATTERN
REQ_BACK_PATTERN REQ_NEXT_MATCH REQ_PREV_MATCH MIN_MENU_COMMAND
MAX_MENU_COMMAND O_ONEVALUE O_SHOWDESC O_ROWMAJOR O_IGNORECASE
O_SHOWMATCH O_NONCYCLIC O_SELECTABLE REQ_NEXT_PAGE REQ_PREV_PAGE
REQ_FIRST_PAGE REQ_LAST_PAGE REQ_NEXT_FIELD REQ_PREV_FIELD
REQ_FIRST_FIELD REQ_LAST_FIELD REQ_SNEXT_FIELD REQ_SPREV_FIELD
REQ_SFIRST_FIELD REQ_SLAST_FIELD REQ_LEFT_FIELD REQ_RIGHT_FIELD
REQ_UP_FIELD REQ_DOWN_FIELD REQ_NEXT_CHAR REQ_PREV_CHAR REQ_NEXT_LINE
REQ_PREV_LINE REQ_NEXT_WORD REQ_PREV_WORD REQ_BEG_FIELD REQ_END_FIELD
wattron wattrset wstandend wstandout wattr_get wattr_off wattr_on
wattr_set wchgat mvchgat mvwchgat wbkgd wbkgdset wborder whline
mvhline mvwhline wvline mvvline mvwvline werase wclear
wclrtobot wclrtoeol wdelch mvdelch mvwdelch wdeleteln winsdelln
winsertln wgetch mvgetch mvwgetch wgetstr mvgetstr mvwgetstr
wgetnstr mvgetnstr mvwgetnstr winch mvinch mvwinch winchstr
mvinchstr mvwinchstr winchnstr mvinchnstr mvwinchnstr wtimeout
winsch mvinsch mvwinsch winsstr mvinsstr mvwinsstr winsnstr
mvinsnstr mvwinsnstr winstr mvinstr mvwinstr winnstr mvinnstr
mvwinnstr wmove wsetscrreg wrefresh wnoutrefresh wredrawln wscrl
wtouchln wsyncup wcursyncup wsyncdown wenclose wmouse_trafo wresize
);
push (@EXPORT, @_OLD);
for (@_OLD)
{
/^(?:mv)?(?:w)?(.*)/;
eval "sub $_ { $1(\@_); }";
}
eval <<EOS;
sub wprintw { addstr(shift, sprintf shift, @_) }
sub mvprintw { addstr(shift, shift, sprintf shift, @_) }
sub mvwprintw { addstr(shift, shift, shift, sprintf shift, @_) }
EOS
}
1;
__END__
=encoding Latin1
=head1 NAME
Curses - terminal screen handling and optimization
=head1 SYNOPSIS
use Curses;
initscr;
...
endwin;
=head1 DESCRIPTION
C<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.
=head2 Unified Functions
Many curses(3) functions have variants starting with the prefixes
I<w->, I<mv->, and/or I<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, C<addch()> has
three other variants: C<waddch()>, C<mvaddch()>, and C<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, C<Curses> is a Perl interface, so we
are free to "unify" these variants into one function. The section
L<"Available Functions"> below lists all curses(3) functions C<Curses>
makes available as Perl equivalents, along with a column listing if it
is I<unified>. If so, it takes a varying number of arguments as
follows:
=over 4
C<function( [win], [y, x], args );>
I<win> is an optional window argument, defaulting to C<stdscr> if not
specified.
I<y, x> is an optional coordinate pair used to move the cursor,
defaulting to no move if not specified.
I<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.
=back
This makes the variants obsolete, since their functionality has been
merged into a single function, so C<Curses> does not define them by
default. You can still get them if you want, by setting the
variable C<$Curses::OldCurses> to a non-zero value before using the
C<Curses> package. See L<"Perl 4.X C<cursperl> Compatibility">
for an example of this.
=head2 Wide-Character-Aware Functions
The following are the preferred functions for working with strings, though
they don't follow the normal unified function naming convention (based on the
names in the Curses library) described above. Despite the naming, each
corresponds to a Curses library function. For example, a C<getchar>
call performs a Curses library function in the C<getch> family.
In addition to these functions, The C<Curses> module contains corresponding
functions with the conventional naming (e.g. C<getch>); the duplication is for
historical reasons. The preferred functions were new in Curses 1.29 (April
2014). They use the wide character functions in the Curses library if
available (falling back to using the traditional non-wide-character versions).
They also have a more Perl-like interface, taking care of some gory details
under the hood about which a Perl programmer shouldn't have to worry.
The reason for two sets of string-handling functions is historical. The
original Curses Perl module predates Curses libraries that understand multiple
byte character encodings. Moreover, the module was designed to have a Perl
interface that closely resembles the C interface syntactically and directly
passes the internal byte representation of Perl strings to C code. This was
probably fine before Perl got Unicode function, but today, Perl stores strings
internally in either Latin-1 or Unicode UTF-8 and the original module was not
sensitive to which encoding was used.
While most of the problems could be worked around in Perl code using the
traditional interface, it's hard to get right and you need a
wide-character-aware curses library (e.g. ncursesw) anyway to make it work
properly. Because existing consumers of the Curses module may be relying on
the traditional behavior, Curses module designers couldn't simply modify the
existing functions to understand wide characters and convert from and to Perl
strings.
None of these functions exist if Perl is older than 5.6.
=head3 C<getchar>
This calls C<wget_wch()>. It returns a character -- more precisely, a
one-character (not necessarily one-byte!) string holding the character -- for
a normal key and a two-element list C<(undef, key-number)> for a function key.
It returns C<undef> on error.
If you don't expect function keys (i.e. with C<keypad(0))>, you can simply do
=over 4
my ($ch, $key) = getchar;
if (defined $key) {
<handle function key $key>
} else if (defined $ch) {
<handle normal key $ch>
} else {
die "getchar failed";
}
=back
If C<wget_wch()> is not available (i.e. The Curses library does not understand
wide characters), this calls C<wgetch()>, but returns the values described
above nonetheless. This can be a problem because with a multibyte character
encoding like UTF-8, you will receive two one-character strings for a
two-byte-character (e.g. "����" and "▽" for "∽"). If you append
these characters to a Perl string, that string may internally contain a valid
UTF-8 encoding of a character, but Perl will not interpret it that way. Perl
may even try to convert what it believes to be two characters to UTF-8, giving
you four bytes.
=head3 C<getstring>
This calls C<wgetn_wstr> and returns a string or C<undef>. It cannot return a
function key value; the Curses library will itself interpret KEY_LEFT and
KEY_BACKSPACE.
If C<wgett_wstr()> is unavailable, this calls C<wgetstr()>.
In both cases, the function allocates a buffer of fixed size to hold the
result of the Curses library call.
=over 4
my $s = getstring();
die "getstring failed" unless defined $s;
=back
=head3 C<addstring>/C<insstring>
This adds/inserts the Perl string passed as an argument to the Curses window
using C<waddnwstr()>/C<wins_nwstr()> or, if unavailable,
C<waddnstr()>/C<winsnstr()>. It returns a true value on success, false on
failure.
=over 4
addstring("H∽ll‡, W‡rld") || die "addstring failed";
=back
=head3 C<instring>
This returns a Perl string (or C<undef> on failure) holding the characters
from the current cursor position up to the end of the line. It uses
C<winnwstr()> if available, and otherwise C<innstr()>.
=over 4
my $s = instring();
die "instring failed" unless defined $s;
=back
=head3 C<ungetchar>
This pushes one character (passed as a one-character Perl string) back to the
input queue. It uses C<unget_wch()> or C<ungetch()>. It returns a true value
on success, false on failure. It cannot push back a function key; the Curses
library provides no way to push back function keys, only characters.
=over 4
ungetchar("X") or die "ungetchar failed";
=back
The C<Curses> module provides no interface to the complex-character routines
(C<wadd_wch()>, C<wadd_wchnstr()>, C<wecho_wchar()>, C<win_wch()>,
C<win_wchnstr()>, C<wins_wch()>) because there is no sensible way of
converting from Perl to a C C<cchar_t> or back.
=head2 Objects
Objects work. Example:
$win = new Curses;
$win->addstr(10, 10, 'foo');
$win->refresh;
...
Any function that has been marked as I<unified> (see
L<"Available Functions"> below and L<"Unified Functions"> above)
can be called as a method for a Curses object.
Do not use C<initscr()> if using objects, as the first call to get
a C<new Curses> will do it for you.
=head2 Security Concerns
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()
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 program must set the variable
C<$Curses::OldCurses> variable to a non-zero value before using the
( run in 0.536 second using v1.01-cache-2.11-cpan-39bf76dae61 )