/ 
Curses-1.05
River stage two • 18 direct dependents • 35 total dependents
/ Curses

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 "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.

Objects

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.

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

  • 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
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 
getstr              Yes        wgetstr mvgetstr mvwgetstr
getnstr             Yes        wgetnstr mvgetnstr mvwgetnstr
getyx               Yes
getparyx            Yes
getbegyx            Yes
getmaxyx            Yes
getmaxy             Yes
getmaxx             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 
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_EVENTNo 
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 
longname            No 
termattrs           No 
termname            No 
touchwin            Yes
touchline           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
resize              Yes        wresize
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

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

Supported Variables

LINES           COLS            stdscr          curscr
COLORS          COLOR_PAIRS

Supported Constants

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_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          KEY_MOUSE
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 BUTTON_CTRL
BUTTON_SHIFT    BUTTON_ALT      ALL_MOUSE_EVENTS REPORT_MOUSE_POSITION
NCURSES_MOUSE_VERSION

curses(3) items not supported by Curses

Functions
---------
tstp scanw wscanw mvscanw mvwscanw _putchar fullname

[*] stdscr and curscr are also available via the Perl functions stdscr and curscr. See "Perl 4.X cursperl Compatibility" for more information.