Curses
Section: User Contributed Perl Documentation
(3)
Updated: perl 5.004, patch 55
Index
Return to Main Contents
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
the section on 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 the section on 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
the section on Supported Functions below and the section on 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
the section on 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 the BUGS manpage 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 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 the 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. :-)
- * 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
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
C<$Curses::OldCurses> must be set to a non-zero value before using the
C<Curses> package. See L<"Perl 4.X cursperl Compatibility"> for an
example of this.
Supported Variables LINESCOLSstdscr[*]curscr[*] =head2 Supported Constants OKERR ACS_BLOCKACS_BOARDACS_BTEEACS_BULLET ACS_CKBOARDACS_DARROWACS_DEGREEACS_DIAMOND ACS_HLINEACS_LANTERNACS_LARROWACS_LLCORNER ACS_LRCORNERACS_LTEEACS_PLMINUSACS_PLUS ACS_RARROWACS_RTEEACS_S1ACS_S9 ACS_TTEEACS_UARROWACS_ULCORNERACS_URCORNER ACS_VLINE A_ALTCHARSETA_ATTRIBUTESA_BLINKA_BOLD A_CHARTEXTA_COLORA_DIMA_INVIS A_NORMALA_PROTECTA_REVERSEA_STANDOUT A_UNDERLINE COLOR_BLACKCOLOR_BLUECOLOR_CYANCOLOR_GREEN COLOR_MAGENTACOLOR_REDCOLOR_WHITECOLOR_YELLOW KEY_A1KEY_A3KEY_B2KEY_BACKSPACE KEY_BEGKEY_BREAKKEY_BTABKEY_C1 KEY_C3KEY_CANCELKEY_CATABKEY_CLEAR KEY_CLOSEKEY_COMMANDKEY_COPYKEY_CREATE KEY_CTABKEY_DCKEY_DLKEY_DOWN KEY_EICKEY_ENDKEY_ENTERKEY_EOL KEY_EOSKEY_EXITKEY_F0KEY_FIND KEY_HELPKEY_HOMEKEY_ICKEY_IL KEY_LEFTKEY_LLKEY_MARKKEY_MAX KEY_MESSAGEKEY_MINKEY_MOVEKEY_NEXT KEY_NPAGEKEY_OPENKEY_OPTIONSKEY_PPAGE KEY_PREVIOUSKEY_PRINTKEY_REDOKEY_REFERENCE KEY_REFRESHKEY_REPLACEKEY_RESETKEY_RESTART KEY_RESUMEKEY_RIGHTKEY_SAVEKEY_SBEG KEY_SCANCELKEY_SCOMMANDKEY_SCOPYKEY_SCREATE KEY_SDCKEY_SDLKEY_SELECTKEY_SEND KEY_SEOLKEY_SEXITKEY_SFKEY_SFIND KEY_SHELPKEY_SHOMEKEY_SICKEY_SLEFT KEY_SMESSAGEKEY_SMOVEKEY_SNEXTKEY_SOPTIONS KEY_SPREVIOUSKEY_SPRINTKEY_SRKEY_SREDO KEY_SREPLACEKEY_SRESETKEY_SRIGHTKEY_SRSUME KEY_SSAVEKEY_SSUSPENDKEY_STABKEY_SUNDO KEY_SUSPENDKEY_UNDOKEY_UP =head2 curses(3) items not supported by Curses 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 the section on Perl 4.X cursperl Compatibility for more information.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- Unified Functions
-
- Objects
-
- COMPATIBILITY
-
- Perl 4.X cursperl Compatibility
-
- Incompatibilities with previous versions of Curses
-
- Incompatibilities with other Perl programs
-
- DIAGNOSTICS
-
- BUGS
-
- AUTHOR
-
- SYNOPSIS OF PERL CURSES SUPPORT
-
- Supported Functions
-
- Supported Variables LINES COLS stdscr[*] curscr[*] =head2 Supported Constants OKERR ACS_BLOCKACS_BOARDACS_BTEEACS_BULLET ACS_CKBOARDACS_DARROWACS_DEGREEACS_DIAMOND ACS_HLINEACS_LANTERNACS_LARROWACS_LLCORNER ACS_LRCORNERACS_LTEEACS_PLMINUSACS_PLUS ACS_RARROWACS_RTEEACS_S1ACS_S9 ACS_TTEEACS_UARROWACS_ULCORNERACS_URCORNER ACS_VLINE A_ALTCHARSETA_ATTRIBUTESA_BLINKA_BOLD A_CHARTEXTA_COLORA_DIMA_INVIS A_NORMALA_PROTECTA_REVERSEA_STANDOUT A_UNDERLINE COLOR_BLACKCOLOR_BLUECOLOR_CYANCOLOR_GREEN COLOR_MAGENTACOLOR_REDCOLOR_WHITECOLOR_YELLOW KEY_A1KEY_A3KEY_B2KEY_BACKSPACE KEY_BEGKEY_BREAKKEY_BTABKEY_C1 KEY_C3KEY_CANCELKEY_CATABKEY_CLEAR KEY_CLOSEKEY_COMMANDKEY_COPYKEY_CREATE KEY_CTABKEY_DCKEY_DLKEY_DOWN KEY_EICKEY_ENDKEY_ENTERKEY_EOL KEY_EOSKEY_EXITKEY_F0KEY_FIND KEY_HELPKEY_HOMEKEY_ICKEY_IL KEY_LEFTKEY_LLKEY_MARKKEY_MAX KEY_MESSAGEKEY_MINKEY_MOVEKEY_NEXT KEY_NPAGEKEY_OPENKEY_OPTIONSKEY_PPAGE KEY_PREVIOUSKEY_PRINTKEY_REDOKEY_REFERENCE KEY_REFRESHKEY_REPLACEKEY_RESETKEY_RESTART KEY_RESUMEKEY_RIGHTKEY_SAVEKEY_SBEG KEY_SCANCELKEY_SCOMMANDKEY_SCOPYKEY_SCREATE KEY_SDCKEY_SDLKEY_SELECTKEY_SEND KEY_SEOLKEY_SEXITKEY_SFKEY_SFIND KEY_SHELPKEY_SHOMEKEY_SICKEY_SLEFT KEY_SMESSAGEKEY_SMOVEKEY_SNEXTKEY_SOPTIONS KEY_SPREVIOUSKEY_SPRINTKEY_SRKEY_SREDO KEY_SREPLACEKEY_SRESETKEY_SRIGHTKEY_SRSUME KEY_SSAVEKEY_SSUSPENDKEY_STABKEY_SUNDO KEY_SUSPENDKEY_UNDOKEY_UP =head2 curses(3) items not supported by Curses 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 the section on Perl 4.X cursperl Compatibility for more information.
-
This document was created by
man2html,
using the manual pages.
Time: 23:58:15 GMT, February 15, 2023