Curses - terminal screen handling and optimization
use Curses; initscr; ... endwin;
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
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 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 "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 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 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.
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.
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.
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[*] --------- -------- ------------------------ 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 hline Yes whline idcok Yes 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 scroll Yes scrollok Yes 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 $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.
LINES COLS stdscr[*] curscr[*]
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_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_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
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 "Perl 4.X cursperl Compatibility" for more information.
To install Curses, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Curses
CPAN shell
perl -MCPAN -e shell install Curses
For more information on module installation, please visit the detailed CPAN module installation guide.