Curses(3pm)

NAME

Curses - terminal screen handling and optimization

SYNOPSIS

use Curses;

initscr;
...
endwin;


Curses::supports_function($function);
Curses::supports_constant($constant);

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.

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.

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 available through "Curses", even

with the "BEGIN" line. They are listed under "curses(3) items not available through 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

o Curses function '%s' called with too %s arguments at ...

You have called a "Curses" function with a wrong number of

arguments.

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

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

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

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

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

o 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 AVAILABILITY

Available Functions

Available Function Unified? Available 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

attr_get Yes wattr_get

attr_off Yes wattr_off

attr_on Yes wattr_on

attr_set Yes wattr_set

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

KEY_F No

getstr Yes wgetstr mvgetstr mvwgetstr

getnstr Yes wgetnstr mvgetnstr mvwgetnstr

getyx Yes

getparyx Yes

getbegyx Yes

getmaxyx 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

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

termattrs No

termname No

touchwin 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

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

Available Variables

LINES COLS stdscr

curscr COLORS COLOR_PAIRS

Available 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_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_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 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 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 REQ_BEG_LINE REQ_END_LINE

REQ_LEFT_CHAR REQ_RIGHT_CHAR REQ_UP_CHAR

REQ_DOWN_CHAR REQ_NEW_LINE REQ_INS_CHAR

REQ_INS_LINE REQ_DEL_CHAR REQ_DEL_PREV

REQ_DEL_LINE REQ_DEL_WORD REQ_CLR_EOL

REQ_CLR_EOF REQ_CLR_FIELD REQ_OVL_MODE

REQ_INS_MODE REQ_SCR_FLINE REQ_SCR_BLINE

REQ_SCR_FPAGE REQ_SCR_BPAGE REQ_SCR_FHPAGE

REQ_SCR_BHPAGE REQ_SCR_FCHAR REQ_SCR_BCHAR

REQ_SCR_HFLINE REQ_SCR_HBLINE REQ_SCR_HFHALF

REQ_SCR_HBHALF REQ_VALIDATION REQ_NEXT_CHOICE

REQ_PREV_CHOICE MIN_FORM_COMMAND MAX_FORM_COMMAND

NO_JUSTIFICATION JUSTIFY_LEFT JUSTIFY_CENTER

JUSTIFY_RIGHT O_VISIBLE O_ACTIVE

O_PUBLIC O_EDIT O_WRAP

O_BLANK O_AUTOSKIP O_NULLOK

O_PASSOK O_STATIC O_NL_OVERLOAD

O_BS_OVERLOAD

curses(3) functions not available through "Curses"

tstp _putchar fullname scanw wscanw mvscanw mvwscanw ripoffline

setupterm setterm set_curterm del_curterm restartterm tparm tputs

putp vidputs vidattr mvcur tigetflag tigetnum tigetstr tgetent

tgetflag tgetnum tgetstr tgoto tputs

menu(3) functions not available through "Curses"

set_item_init item_init set_item_term item_term set_menu_init

menu_init set_menu_term menu_term

form(3) functions not available through "Curses"

new_fieldtype free_fieldtype set_fieldtype_arg

set_fieldtype_choice link_fieldtype set_form_init form_init

set_form_term form_term set_field_init field_init set_field_term

field_term set_field_type field_type

docs.sk

comprehensive documentation repository

In section

See also

Curses(3pm)

NAME

SYNOPSIS

DESCRIPTION

COMPATIBILITY

DIAGNOSTICS

BUGS

AUTHOR

SYNOPSIS OF PERL CURSES AVAILABILITY