NAME
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 "Available Functions" below lists all curses(3) functions "Curses" makes available as Perl equivalents, 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.
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 "getchar" call performs a Curses library function in the "getch" family.
In addition to these functions, The "Curses" module contains corresponding functions with the conventional naming (e.g. "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.
"getchar"
This calls 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 "(undef, key-number)" for a function key. It returns "undef" on error.
If you don't expect function keys (i.e. with "keypad(0))", you can simply do
my $ch = getchar;die "getchar failed" unless defined $ch;
If you do expect function keys (i.e. with keypad(1)), you can still assign the result to a scalar variable as above. Because of of the way the comma operator works, that variable will receive either "undef" or the string or the number, and you can decode it yourself.
my $ch = getchar;die "getchar failed" unless defined $ch;if (<$ch looks like a number >= 0x100>) {<handle function key>} else {<handle normal key>}
or do
my ($ch, $key) = getchar;if (defined $key) {<handle function key $key>} else if (defined $ch) {<handle normal key $ch>} else {die "getchar failed";}
If wget_wch() is not available (i.e. The Curses library does not understand wide characters), this calls 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.
"getstring"
This calls "wgetn_wstr" and returns a string or "undef". It cannot return a function key value; the Curses library will itself interpret KEY_LEFT and KEY_BACKSPACE.
If wgett_wstr() is unavailable, this calls wgetstr().
In both cases, the function allocates a buffer of fixed size to hold the result of the Curses library call.
my $s = getstring();die "getstring failed" unless defined $s;
"addstring"/"insstring"
This adds/inserts the Perl string passed as an argument to the Curses window using waddnwstr()/wins_nwstr() or, if unavailable, waddnstr()/winsnstr(). It returns a true value on success, false on failure.
addstring("Hâ½llâ¡, Wâ¡rld") || die "addstring failed";
"instring"
This returns a Perl string (or "undef" on failure) holding the characters from the current cursor position up to the end of the line. It uses winnwstr() if available, and otherwise innstr().
my $s = instring();die "instring failed" unless defined $s;
"ungetchar"
This pushes one character (passed as a one-character Perl string) back to the input queue. It uses unget_wch() or 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.
ungetchar("X") or die "ungetchar failed";
The "Curses" module provides no interface to the complex-character routines (wadd_wch(), wadd_wchnstr(), wecho_wchar(), win_wch(), win_wchnstr(), wins_wch()) because there is no sensible way of converting from Perl to a C "cchar_t" or back.
Objects
Objects work. Example:
$win = new Curses;$win->addstr(10, 10, 'foo');$win->refresh;...
Any function that has been marked as unified (see "Available 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.
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()innstr()
which take an extra "size of buffer" argument or the wide-character-aware getstring() and instring() versions.
COMPATIBILITY
Perl 4.X "cursperl" Compatibility
"Curses" was written to take advantage of features of Perl 5 and later. The author thought it was better to provide an improved curses programming environment 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 available through "Curses", even with the "BEGIN" line. They are listed under "Curses items not available through Perl Curses".
The variables $stdscr and $curscr are also available as functions "stdscr" and "curscr". This is because of a Perl bug. See the LIMITATIONS 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 not true in the current version. You should now use getstr($str) and "getyx($y, $x)" instead of "$str = getstr()" and "($y, $x) = getyx()".
DIAGNOSTICS
- •
-
Curses function '%s' called with too
%sarguments at ...You have called a
"Curses"function with a wrong number of arguments.
- •
-
argument
%dto Curses function '%s' is not a Curses%sat ...
- •
-
argument is not a Curses
%sat ...The argument you gave to the function wasn't of a valid type for the place you used it.
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 in your Curses library at ...
Your code has a call to a Perl
"Curses"function that your system's Curses library doesn't provide.
- •
-
Curses variable '%s' is not defined in your Curses library at ...
Your code has a Perl
"Curses"variable that your system's Curses library doesn't provide.
- •
-
Curses constant '%s' is not defined in your Curses library at ...
Your code references the specified
"Curses"constant, and your system's Curses library doesn't provide it.
- •
-
Curses::Vars::FETCH called with bad index at ...
- •
-
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.
LIMITATIONS
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.
AUTHOR
William Setzer <[email protected]>
SYNOPSIS OF PERL CURSES AVAILABILITY
Available Functions
Available Function Unified? Available via $OldCurses[*]------------------ -------- ------------------------addch Yes waddch mvaddch mvwaddchechochar Yes wechocharaddchstr Yes waddchstr mvaddchstr mvwaddchstraddchnstr Yes waddchnstr mvaddchnstr mvwaddchnstraddstr Yes waddstr mvaddstr mvwaddstraddnstr Yes waddnstr mvaddnstr mvwaddnstrattroff Yes wattroffattron Yes wattronattrset Yes wattrsetstandend Yes wstandendstandout Yes wstandoutattr_get Yes wattr_getattr_off Yes wattr_offattr_on Yes wattr_onattr_set Yes wattr_setchgat Yes wchgat mvchgat mvwchgatCOLOR_PAIR NoPAIR_NUMBER Nobeep Noflash Nobkgd Yes wbkgdbkgdset Yes wbkgdsetgetbkgd Yesborder Yes wborderbox Yeshline Yes whline mvhline mvwhlinevline Yes wvline mvvline mvwvlineerase Yes weraseclear Yes wclearclrtobot Yes wclrtobotclrtoeol Yes wclrtoeolstart_color Noinit_pair Noinit_color Nohas_colors Nocan_change_color Nocolor_content Nopair_content Nodelch Yes wdelch mvdelch mvwdelchdeleteln Yes wdeletelninsdelln Yes winsdellninsertln Yes winsertlngetch Yes wgetch mvgetch mvwgetchungetch Nohas_key NoKEY_F Nogetstr Yes wgetstr mvgetstr mvwgetstrgetnstr Yes wgetnstr mvgetnstr mvwgetnstrgetyx Yesgetparyx Yesgetbegyx Yesgetmaxyx Yesinch Yes winch mvinch mvwinchinchstr Yes winchstr mvinchstr mvwinchstrinchnstr Yes winchnstr mvinchnstr mvwinchnstrinitscr Noendwin Noisendwin Nonewterm Noset_term Nodelscreen Nocbreak Nonocbreak Noecho Nonoecho Nohalfdelay Nointrflush Yeskeypad Yesmeta Yesnodelay Yesnotimeout Yesraw Nonoraw Noqiflush Nonoqiflush Notimeout Yes wtimeouttypeahead Noinsch Yes winsch mvinsch mvwinschinsstr Yes winsstr mvinsstr mvwinsstrinsnstr Yes winsnstr mvinsnstr mvwinsnstrinstr Yes winstr mvinstr mvwinstrinnstr Yes winnstr mvinnstr mvwinnstrdef_prog_mode Nodef_shell_mode Noreset_prog_mode Noreset_shell_mode Noresetty Nosavetty Nogetsyx Nosetsyx Nocurs_set Nonapms Nomove Yes wmoveclearok Yesidlok Yesidcok Yesimmedok Yesleaveok Yessetscrreg Yes wsetscrregscrollok Yesnl Nononl Nooverlay Nooverwrite Nocopywin Nonewpad Nosubpad Noprefresh Nopnoutrefresh Nopechochar Norefresh Yes wrefreshnoutrefresh Yes wnoutrefreshdoupdate Noredrawwin Yesredrawln Yes wredrawlnscr_dump Noscr_restore Noscr_init Noscr_set Noscroll Yesscrl Yes wscrlslk_init Noslk_set Noslk_refresh Noslk_noutrefresh Noslk_label Noslk_clear Noslk_restore Noslk_touch Noslk_attron Noslk_attrset Noslk_attr Noslk_attroff Noslk_color Nobaudrate Noerasechar Nohas_ic Nohas_il Nokillchar Nolongname Notermattrs Notermname Notouchwin Yestouchline Yesuntouchwin Yestouchln Yes wtouchlnis_linetouched Yesis_wintouched Yesunctrl Nokeyname Nofilter Nouse_env Noputwin Nogetwin Nodelay_output Noflushinp Nonewwin Nodelwin Yesmvwin Yessubwin Yesderwin Yesmvderwin Yesdupwin Yessyncup Yes wsyncupsyncok Yescursyncup Yes wcursyncupsyncdown Yes wsyncdowngetmouse Noungetmouse Nomousemask Noenclose Yes wenclosemouse_trafo Yes wmouse_trafomouseinterval NoBUTTON_RELEASE NoBUTTON_PRESS NoBUTTON_CLICK NoBUTTON_DOUBLE_CLICK NoBUTTON_TRIPLE_CLICK NoBUTTON_RESERVED_EVENT Nouse_default_colors Noassume_default_colors Nodefine_key Nokeybound Nokeyok Noresizeterm Noresize Yes wresizegetmaxy Yesgetmaxx Yesflusok Yesgetcap Notouchoverlap Nonew_panel Nobottom_panel Notop_panel Noshow_panel Noupdate_panels Nohide_panel Nopanel_window Noreplace_panel Nomove_panel Nopanel_hidden Nopanel_above Nopanel_below Noset_panel_userptr Nopanel_userptr Nodel_panel Noset_menu_fore Nomenu_fore Noset_menu_back Nomenu_back Noset_menu_grey Nomenu_grey Noset_menu_pad Nomenu_pad Nopos_menu_cursor Nomenu_driver Noset_menu_format Nomenu_format Noset_menu_items Nomenu_items Noitem_count Noset_menu_mark Nomenu_mark Nonew_menu Nofree_menu Nomenu_opts Noset_menu_opts Nomenu_opts_on Nomenu_opts_off Noset_menu_pattern Nomenu_pattern Nopost_menu Nounpost_menu Noset_menu_userptr Nomenu_userptr Noset_menu_win Nomenu_win Noset_menu_sub Nomenu_sub Noscale_menu Noset_current_item Nocurrent_item Noset_top_row Notop_row Noitem_index Noitem_name Noitem_description Nonew_item Nofree_item Noset_item_opts Noitem_opts_on Noitem_opts_off Noitem_opts Noitem_userptr Noset_item_userptr Noset_item_value Noitem_value Noitem_visible Nomenu_request_name Nomenu_request_by_name Noset_menu_spacing Nomenu_spacing Nopos_form_cursor Nodata_ahead Nodata_behind Noform_driver Noset_form_fields Noform_fields Nofield_count Nomove_field Nonew_form Nofree_form Noset_new_page Nonew_page Noset_form_opts Noform_opts_on Noform_opts_off Noform_opts Noset_current_field Nocurrent_field Noset_form_page Noform_page Nofield_index Nopost_form Nounpost_form Noset_form_userptr Noform_userptr Noset_form_win Noform_win Noset_form_sub Noform_sub Noscale_form Noset_field_fore Nofield_fore Noset_field_back Nofield_back Noset_field_pad Nofield_pad Noset_field_buffer Nofield_buffer Noset_field_status Nofield_status Noset_max_field Nofield_info Nodynamic_field_info Noset_field_just Nofield_just Nonew_field Nodup_field Nolink_field Nofree_field Noset_field_opts Nofield_opts_on Nofield_opts_off Nofield_opts Noset_field_userptr Nofield_userptr Nofield_arg Noform_request_name Noform_request_by_name No
[*] To use any functions in this column, the program must set the variable $Curses::OldCurses variable to a non-zero value before using the "Curses" package. See "Perl 4.X cursperl Compatibility" for an example of this.
Available Wide-Character-Aware Functions
Function Uses wide-character call Reverts to legacy call-------- ------------------------ ----------------------getchar wget_wch wgetchgetstring wgetn_wstr wgetnstrungetchar unget_wch ungetchinstring winnwtr winnstraddstring waddnwstr waddnstrinsstring wins_nwstr winsnstr
Available Variables
LINES COLS stdscrcurscr COLORS COLOR_PAIRS
Available Constants
ERR OK ACS_BLOCKACS_BOARD ACS_BTEE ACS_BULLETACS_CKBOARD ACS_DARROW ACS_DEGREEACS_DIAMOND ACS_HLINE ACS_LANTERNACS_LARROW ACS_LLCORNER ACS_LRCORNERACS_LTEE ACS_PLMINUS ACS_PLUSACS_RARROW ACS_RTEE ACS_S1ACS_S9 ACS_TTEE ACS_UARROWACS_ULCORNER ACS_URCORNER ACS_VLINEA_ALTCHARSET A_ATTRIBUTES A_BLINKA_BOLD A_CHARTEXT A_COLORA_DIM A_INVIS A_NORMALA_PROTECT A_REVERSE A_STANDOUTA_UNDERLINE A_ITALICCOLOR_BLACK COLOR_BLUECOLOR_CYAN COLOR_GREEN COLOR_MAGENTACOLOR_RED COLOR_WHITE COLOR_YELLOWKEY_A1 KEY_A3 KEY_B2KEY_BACKSPACE KEY_BEG KEY_BREAKKEY_BTAB KEY_C1 KEY_C3KEY_CANCEL KEY_CATAB KEY_CLEARKEY_CLOSE KEY_COMMAND KEY_COPYKEY_CREATE KEY_CTAB KEY_DCKEY_DL KEY_DOWN KEY_EICKEY_END KEY_ENTER KEY_EOLKEY_EOS KEY_EVENT KEY_EXITKEY_F0KEY_FIND KEY_HELP KEY_HOMEKEY_IC KEY_IL KEY_LEFTKEY_LL KEY_MARK KEY_MAXKEY_MESSAGE KEY_MIN KEY_MOVEKEY_NEXT KEY_NPAGE KEY_OPENKEY_OPTIONS KEY_PPAGE KEY_PREVIOUSKEY_PRINT KEY_REDO KEY_REFERENCEKEY_REFRESH KEY_REPLACE KEY_RESETKEY_RESIZE KEY_RESTART KEY_RESUMEKEY_RIGHTKEY_SAVE KEY_SBEG KEY_SCANCELKEY_SCOMMAND KEY_SCOPY KEY_SCREATEKEY_SDC KEY_SDL KEY_SELECTKEY_SEND KEY_SEOL KEY_SEXITKEY_SF KEY_SFIND KEY_SHELPKEY_SHOME KEY_SIC KEY_SLEFTKEY_SMESSAGE KEY_SMOVE KEY_SNEXTKEY_SOPTIONS KEY_SPREVIOUS KEY_SPRINTKEY_SR KEY_SREDO KEY_SREPLACEKEY_SRESET KEY_SRIGHT KEY_SRSUMEKEY_SSAVE KEY_SSUSPEND KEY_STABKEY_SUNDO KEY_SUSPEND KEY_UNDOKEY_UP KEY_MOUSE BUTTON1_RELEASEDBUTTON1_PRESSED BUTTON1_CLICKED BUTTON1_DOUBLE_CLICKEDBUTTON1_TRIPLE_CLICKED BUTTON1_RESERVED_EVENT BUTTON2_RELEASEDBUTTON2_PRESSED BUTTON2_CLICKED BUTTON2_DOUBLE_CLICKEDBUTTON2_TRIPLE_CLICKED BUTTON2_RESERVED_EVENT BUTTON3_RELEASEDBUTTON3_PRESSED BUTTON3_CLICKED BUTTON3_DOUBLE_CLICKEDBUTTON3_TRIPLE_CLICKED BUTTON3_RESERVED_EVENT BUTTON4_RELEASEDBUTTON4_PRESSED BUTTON4_CLICKED BUTTON4_DOUBLE_CLICKEDBUTTON4_TRIPLE_CLICKED BUTTON4_RESERVED_EVENT BUTTON_CTRLBUTTON_SHIFT BUTTON_ALT ALL_MOUSE_EVENTSREPORT_MOUSE_POSITION NCURSES_MOUSE_VERSION E_OKE_SYSTEM_ERROR E_BAD_ARGUMENT E_POSTEDE_CONNECTED E_BAD_STATE E_NO_ROOME_NOT_POSTED E_UNKNOWN_COMMAND E_NO_MATCHE_NOT_SELECTABLE E_NOT_CONNECTED E_REQUEST_DENIEDE_INVALID_FIELD E_CURRENT REQ_LEFT_ITEMREQ_RIGHT_ITEM REQ_UP_ITEM REQ_DOWN_ITEMREQ_SCR_ULINE REQ_SCR_DLINE REQ_SCR_DPAGEREQ_SCR_UPAGE REQ_FIRST_ITEM REQ_LAST_ITEMREQ_NEXT_ITEM REQ_PREV_ITEM REQ_TOGGLE_ITEMREQ_CLEAR_PATTERN REQ_BACK_PATTERN REQ_NEXT_MATCHREQ_PREV_MATCH MIN_MENU_COMMAND MAX_MENU_COMMANDO_ONEVALUE O_SHOWDESC O_ROWMAJORO_IGNORECASE O_SHOWMATCH O_NONCYCLICO_SELECTABLE REQ_NEXT_PAGE REQ_PREV_PAGEREQ_FIRST_PAGE REQ_LAST_PAGE REQ_NEXT_FIELDREQ_PREV_FIELD REQ_FIRST_FIELD REQ_LAST_FIELDREQ_SNEXT_FIELD REQ_SPREV_FIELD REQ_SFIRST_FIELDREQ_SLAST_FIELD REQ_LEFT_FIELD REQ_RIGHT_FIELDREQ_UP_FIELD REQ_DOWN_FIELD REQ_NEXT_CHARREQ_PREV_CHAR REQ_NEXT_LINE REQ_PREV_LINEREQ_NEXT_WORD REQ_PREV_WORD REQ_BEG_FIELDREQ_END_FIELD REQ_BEG_LINE REQ_END_LINEREQ_LEFT_CHAR REQ_RIGHT_CHAR REQ_UP_CHARREQ_DOWN_CHAR REQ_NEW_LINE REQ_INS_CHARREQ_INS_LINE REQ_DEL_CHAR REQ_DEL_PREVREQ_DEL_LINE REQ_DEL_WORD REQ_CLR_EOLREQ_CLR_EOF REQ_CLR_FIELD REQ_OVL_MODEREQ_INS_MODE REQ_SCR_FLINE REQ_SCR_BLINEREQ_SCR_FPAGE REQ_SCR_BPAGE REQ_SCR_FHPAGEREQ_SCR_BHPAGE REQ_SCR_FCHAR REQ_SCR_BCHARREQ_SCR_HFLINE REQ_SCR_HBLINE REQ_SCR_HFHALFREQ_SCR_HBHALF REQ_VALIDATION REQ_NEXT_CHOICEREQ_PREV_CHOICE MIN_FORM_COMMAND MAX_FORM_COMMANDNO_JUSTIFICATION JUSTIFY_LEFT JUSTIFY_CENTERJUSTIFY_RIGHT O_VISIBLE O_ACTIVEO_PUBLIC O_EDIT O_WRAPO_BLANK O_AUTOSKIP O_NULLOKO_PASSOK O_STATIC O_NL_OVERLOADO_BS_OVERLOAD
Curses functions not available through Perl "Curses"
tstp _putchar fullname scanw wscanw mvscanw mvwscanw ripofflinesetupterm setterm set_curterm del_curterm restartterm tparm tputsputp vidputs vidattr mvcur tigetflag tigetnum tigetstr tgetenttgetflag tgetnum tgetstr tgoto tputs
Curses menu functions not available through Perl "Curses"
set_item_init item_init set_item_term item_term set_menu_initmenu_init set_menu_term menu_term
Curses form functions not available through Perl "Curses"
new_fieldtype free_fieldtype set_fieldtype_argset_fieldtype_choice link_fieldtype set_form_init form_initset_form_term form_term set_field_init field_init set_field_termfield_term set_field_type field_type