1Curses(3) User Contributed Perl Documentation Curses(3)
2
6 Curses - terminal screen handling and optimization
7
9 use Curses;
10 initscr;
12 ...
13 endwin;
14 Curses::supports_function($function);
16 Curses::supports_contsant($constant);
17
19 "Curses" is the interface between Perl and your system's curses(3)
20 library. For descriptions on the usage of a given function, variable,
21 or constant, consult your system's documentation, as such information
22 invariably varies (:-) between different curses(3) libraries and oper‐
23 ating systems. This document describes the interface itself, and
24 assumes that you already know how your system's curses(3) library
25 works.
26 Unified Functions
28 Many curses(3) functions have variants starting with the prefixes w-,
30 mv-, and/or wmv-. These variants differ only in the explicit addition
31 of a window, or by the addition of two coordinates that are used to
32 move the cursor first. For example, "addch()" has three other vari‐
33 ants: "waddch()", "mvaddch()", and "mvwaddch()". The variants aren't
34 very interesting; in fact, we could roll all of the variants into orig‐
35 inal function by allowing a variable number of arguments and analyzing
36 the argument list for which variant the user wanted to call.
37 Unfortunately, curses(3) predates varargs(3), so in C we were stuck
39 with all the variants. However, "Curses" is a Perl interface, so we
40 are free to "unify" these variants into one function. The section
41 "Supported Functions" below lists all curses(3) function supported by
42 "Curses", along with a column listing if it is unified. If so, it
43 takes a varying number of arguments as follows:
44 "function( [win], [y, x], args );"
46 win is an optional window argument, defaulting to "stdscr" if not
48 specified.
49 y, x is an optional coordinate pair used to move the cursor,
51 defaulting to no move if not specified.
52 args are the required arguments of the function. These are the
54 arguments you would specify if you were just calling the base func‐
55 tion and not any of the variants.
56 This makes the variants obsolete, since their functionality has been
58 merged into a single function, so "Curses" does not define them by
59 default. You can still get them if you want, by setting the variable
60 $Curses::OldCurses to a non-zero value before using the "Curses" pack‐
61 age. See "Perl 4.X "cursperl" Compatibility" for an example of this.
62 Objects
64 Objects are supported. Example:
66 $win = new Curses;
68 $win->addstr(10, 10, 'foo');
69 $win->refresh;
70 ...
71 Any function that has been marked as unified (see "Supported Functions"
73 below and "Unified Functions" above) can be called as a method for a
74 Curses object.
75 Do not use "initscr()" if using objects, as the first call to get a
77 "new Curses" will do it for you.
78 Security Concerns
80 It has always been the case with the curses functions, but please note
82 that the following functions:
83 getstr() (and optional wgetstr(), mvgetstr(), and mvwgetstr())
85 inchstr() (and optional winchstr(), mvinchstr(), and mvwinchstr())
86 instr() (and optional winstr(), mvinstr(), and mvwinstr())
87 are subject to buffer overflow attack. This is because you pass in the
89 buffer to be filled in, which has to be of finite length, but there is
90 no way to stop a bad guy from typing.
91 In order to avoid this problem, use the alternate functions:
93 getnstr()
95 inchnstr()
96 innstr()
97 which take an extra "size of buffer" argument.
99
101 Perl 4.X "cursperl" Compatibility
102 "Curses" has been written to take advantage of the new features of
104 Perl. I felt it better to provide an improved curses programming envi‐
105 ronment rather than to be 100% compatible. However, many old
106 "curseperl" applications will probably still work by starting the
107 script with:
108 BEGIN { $Curses::OldCurses = 1; }
110 use Curses;
111 Any old application that still does not work should print an under‐
113 standable error message explaining the problem.
114 Some functions and variables are not supported by "Curses", even with
116 the "BEGIN" line. They are listed under "curses(3) items not supported
117 by Curses".
118 The variables $stdscr and $curscr are also available as functions "std‐
120 scr" and "curscr". This is because of a Perl bug. See the BUGS sec‐
121 tion for details.
122 Incompatibilities with previous versions of "Curses"
124 In previous versions of this software, some Perl functions took a dif‐
126 ferent set of parameters than their C counterparts. This is no longer
127 true. You should now use "getstr($str)" and "getyx($y, $x)" instead of
128 "$str = getstr()" and "($y, $x) = getyx()".
129 Incompatibilities with other Perl programs
131 menu.pl, v3.0 and v3.1
133 There were various interaction problems between these two
134 releases and Curses. Please upgrade to the latest version
135 (v3.3 as of 3/16/96).
136
138 * Curses function '%s' called with too %s arguments at ...
139 You have called a "Curses" function with a wrong number of argu‐
140 ments.
141 * argument %d to Curses function '%s' is not a Curses %s at ... =item *
143 argument is not a Curses %s at ...
144 The argument you gave to the function wasn't what it wanted.
145 This probably means that you didn't give the right arguments to a
147 unified function. See the DESCRIPTION section on "Unified Func‐
148 tions" for more information.
149 * Curses function '%s' is not defined by your vendor at ...
151 You have a "Curses" function in your code that your system's
152 curses(3) library doesn't define.
153 * Curses variable '%s' is not defined by your vendor at ...
155 You have a "Curses" variable in your code that your system's
156 curses(3) library doesn't define.
157 * Curses constant '%s' is not defined by your vendor at ...
159 You have a "Curses" constant in your code that your system's
160 curses(3) library doesn't define.
161 * Curses::Vars::FETCH called with bad index at ... =item *
163 Curses::Vars::STORE called with bad index at ...
164 You've been playing with the "tie" interface to the "Curses" vari‐
165 ables. Don't do that. :-)
166 * Anything else
168 Check out the perldiag man page to see if the error is in there.
169
171 If you use the variables $stdscr and $curscr instead of their func‐
172 tional counterparts ("stdscr" and "curscr"), you might run into a bug
173 in Perl where the "magic" isn't called early enough. This is mani‐
174 fested by the "Curses" package telling you $stdscr isn't a window. One
175 workaround is to put a line like "$stdscr = $stdscr" near the front of
176 your program.
177 Probably many more.
179
181 William Setzer <William_Setzer@ncsu.edu>
182
184 Supported Functions
185 Supported Unified? Supported via $OldCurses[*]
187 --------- -------- ------------------------
188 addch Yes waddch mvaddch mvwaddch
189 echochar Yes wechochar
190 addchstr Yes waddchstr mvaddchstr mvwaddchstr
191 addchnstr Yes waddchnstr mvaddchnstr mvwaddchnstr
192 addstr Yes waddstr mvaddstr mvwaddstr
193 addnstr Yes waddnstr mvaddnstr mvwaddnstr
194 attroff Yes wattroff
195 attron Yes wattron
196 attrset Yes wattrset
197 standend Yes wstandend
198 standout Yes wstandout
199 attr_get Yes wattr_get
200 attr_off Yes wattr_off
201 attr_on Yes wattr_on
202 attr_set Yes wattr_set
203 chgat Yes wchgat mvchgat mvwchgat
204 COLOR_PAIR No
205 PAIR_NUMBER No
206 beep No
207 flash No
208 bkgd Yes wbkgd
209 bkgdset Yes wbkgdset
210 getbkgd Yes
211 border Yes wborder
212 box Yes
213 hline Yes whline mvhline mvwhline
214 vline Yes wvline mvvline mvwvline
215 erase Yes werase
216 clear Yes wclear
217 clrtobot Yes wclrtobot
218 clrtoeol Yes wclrtoeol
219 start_color No
220 init_pair No
221 init_color No
222 has_colors No
223 can_change_color No
224 color_content No
225 pair_content No
226 delch Yes wdelch mvdelch mvwdelch
227 deleteln Yes wdeleteln
228 insdelln Yes winsdelln
229 insertln Yes winsertln
230 getch Yes wgetch mvgetch mvwgetch
231 ungetch No
232 has_key No
233 KEY_F No
234 getstr Yes wgetstr mvgetstr mvwgetstr
235 getnstr Yes wgetnstr mvgetnstr mvwgetnstr
236 getyx Yes
237 getparyx Yes
238 getbegyx Yes
239 getmaxyx Yes
240 inch Yes winch mvinch mvwinch
241 inchstr Yes winchstr mvinchstr mvwinchstr
242 inchnstr Yes winchnstr mvinchnstr mvwinchnstr
243 initscr No
244 endwin No
245 isendwin No
246 newterm No
247 set_term No
248 delscreen No
249 cbreak No
250 nocbreak No
251 echo No
252 noecho No
253 halfdelay No
254 intrflush Yes
255 keypad Yes
256 meta Yes
257 nodelay Yes
258 notimeout Yes
259 raw No
260 noraw No
261 qiflush No
262 noqiflush No
263 timeout Yes wtimeout
264 typeahead No
265 insch Yes winsch mvinsch mvwinsch
266 insstr Yes winsstr mvinsstr mvwinsstr
267 insnstr Yes winsnstr mvinsnstr mvwinsnstr
268 instr Yes winstr mvinstr mvwinstr
269 innstr Yes winnstr mvinnstr mvwinnstr
270 def_prog_mode No
271 def_shell_mode No
272 reset_prog_mode No
273 reset_shell_mode No
274 resetty No
275 savetty No
276 getsyx No
277 setsyx No
278 curs_set No
279 napms No
280 move Yes wmove
281 clearok Yes
282 idlok Yes
283 idcok Yes
284 immedok Yes
285 leaveok Yes
286 setscrreg Yes wsetscrreg
287 scrollok Yes
288 nl No
289 nonl No
290 overlay No
291 overwrite No
292 copywin No
293 newpad No
294 subpad No
295 prefresh No
296 pnoutrefresh No
297 pechochar No
298 refresh Yes wrefresh
299 noutrefresh Yes wnoutrefresh
300 doupdate No
301 redrawwin Yes
302 redrawln Yes wredrawln
303 scr_dump No
304 scr_restore No
305 scr_init No
306 scr_set No
307 scroll Yes
308 scrl Yes wscrl
309 slk_init No
310 slk_set No
311 slk_refresh No
312 slk_noutrefresh No
313 slk_label No
314 slk_clear No
315 slk_restore No
316 slk_touch No
317 slk_attron No
318 slk_attrset No
319 slk_attr No
320 slk_attroff No
321 slk_color No
322 baudrate No
323 erasechar No
324 has_ic No
325 has_il No
326 killchar No
327 longname No
328 termattrs No
329 termname No
330 touchwin Yes
331 touchline Yes
332 untouchwin Yes
333 touchln Yes wtouchln
334 is_linetouched Yes
335 is_wintouched Yes
336 unctrl No
337 keyname No
338 filter No
339 use_env No
340 putwin No
341 getwin No
342 delay_output No
343 flushinp No
344 newwin No
345 delwin Yes
346 mvwin Yes
347 subwin Yes
348 derwin Yes
349 mvderwin Yes
350 dupwin Yes
351 syncup Yes wsyncup
352 syncok Yes
353 cursyncup Yes wcursyncup
354 syncdown Yes wsyncdown
355 getmouse No
356 ungetmouse No
357 mousemask No
358 enclose Yes wenclose
359 mouse_trafo Yes wmouse_trafo
360 mouseinterval No
361 BUTTON_RELEASE No
362 BUTTON_PRESS No
363 BUTTON_CLICK No
364 BUTTON_DOUBLE_CLICK No
365 BUTTON_TRIPLE_CLICK No
366 BUTTON_RESERVED_EVENT No
367 use_default_colors No
368 assume_default_colors No
369 define_key No
370 keybound No
371 keyok No
372 resizeterm No
373 resize Yes wresize
374 getmaxy Yes
375 getmaxx Yes
376 flusok Yes
377 getcap No
378 touchoverlap No
379 new_panel No
380 bottom_panel No
381 top_panel No
382 show_panel No
383 update_panels No
384 hide_panel No
385 panel_window No
386 replace_panel No
387 move_panel No
388 panel_hidden No
389 panel_above No
390 panel_below No
391 set_panel_userptr No
392 panel_userptr No
393 del_panel No
394 set_menu_fore No
395 menu_fore No
396 set_menu_back No
397 menu_back No
398 set_menu_grey No
399 menu_grey No
400 set_menu_pad No
401 menu_pad No
402 pos_menu_cursor No
403 menu_driver No
404 set_menu_format No
405 menu_format No
406 set_menu_items No
407 menu_items No
408 item_count No
409 set_menu_mark No
410 menu_mark No
411 new_menu No
412 free_menu No
413 menu_opts No
414 set_menu_opts No
415 menu_opts_on No
416 menu_opts_off No
417 set_menu_pattern No
418 menu_pattern No
419 post_menu No
420 unpost_menu No
421 set_menu_userptr No
422 menu_userptr No
423 set_menu_win No
424 menu_win No
425 set_menu_sub No
426 menu_sub No
427 scale_menu No
428 set_current_item No
429 current_item No
430 set_top_row No
431 top_row No
432 item_index No
433 item_name No
434 item_description No
435 new_item No
436 free_item No
437 set_item_opts No
438 item_opts_on No
439 item_opts_off No
440 item_opts No
441 item_userptr No
442 set_item_userptr No
443 set_item_value No
444 item_value No
445 item_visible No
446 menu_request_name No
447 menu_request_by_name No
448 set_menu_spacing No
449 menu_spacing No
450 pos_form_cursor No
451 data_ahead No
452 data_behind No
453 form_driver No
454 set_form_fields No
455 form_fields No
456 field_count No
457 move_field No
458 new_form No
459 free_form No
460 set_new_page No
461 new_page No
462 set_form_opts No
463 form_opts_on No
464 form_opts_off No
465 form_opts No
466 set_current_field No
467 current_field No
468 set_form_page No
469 form_page No
470 field_index No
471 post_form No
472 unpost_form No
473 set_form_userptr No
474 form_userptr No
475 set_form_win No
476 form_win No
477 set_form_sub No
478 form_sub No
479 scale_form No
480 set_field_fore No
481 field_fore No
482 set_field_back No
483 field_back No
484 set_field_pad No
485 field_pad No
486 set_field_buffer No
487 field_buffer No
488 set_field_status No
489 field_status No
490 set_max_field No
491 field_info No
492 dynamic_field_info No
493 set_field_just No
494 field_just No
495 new_field No
496 dup_field No
497 link_field No
498 free_field No
499 set_field_opts No
500 field_opts_on No
501 field_opts_off No
502 field_opts No
503 set_field_userptr No
504 field_userptr No
505 field_arg No
506 form_request_name No
507 form_request_by_name No
508 [*] To use any functions in this column, the variable $Curses::Old‐
510 Curses must be set to a non-zero value before using the "Curses" pack‐
511 age. See "Perl 4.X cursperl Compatibility" for an example of this.
512 Supported Variables
514 LINES COLS stdscr
516 curscr COLORS COLOR_PAIRS
517 Supported Constants
519 ERR OK ACS_BLOCK
521 ACS_BOARD ACS_BTEE ACS_BULLET
522 ACS_CKBOARD ACS_DARROW ACS_DEGREE
523 ACS_DIAMOND ACS_HLINE ACS_LANTERN
524 ACS_LARROW ACS_LLCORNER ACS_LRCORNER
525 ACS_LTEE ACS_PLMINUS ACS_PLUS
526 ACS_RARROW ACS_RTEE ACS_S1
527 ACS_S9 ACS_TTEE ACS_UARROW
528 ACS_ULCORNER ACS_URCORNER ACS_VLINE
529 A_ALTCHARSET A_ATTRIBUTES A_BLINK
530 A_BOLD A_CHARTEXT A_COLOR
531 A_DIM A_INVIS A_NORMAL
532 A_PROTECT A_REVERSE A_STANDOUT
533 A_UNDERLINE COLOR_BLACK COLOR_BLUE
534 COLOR_CYAN COLOR_GREEN COLOR_MAGENTA
535 COLOR_RED COLOR_WHITE COLOR_YELLOW
536 KEY_A1 KEY_A3 KEY_B2
537 KEY_BACKSPACE KEY_BEG KEY_BREAK
538 KEY_BTAB KEY_C1 KEY_C3
539 KEY_CANCEL KEY_CATAB KEY_CLEAR
540 KEY_CLOSE KEY_COMMAND KEY_COPY
541 KEY_CREATE KEY_CTAB KEY_DC
542 KEY_DL KEY_DOWN KEY_EIC
543 KEY_END KEY_ENTER KEY_EOL
544 KEY_EOS KEY_EXIT KEY_F0
545 KEY_FIND KEY_HELP KEY_HOME
546 KEY_IC KEY_IL KEY_LEFT
547 KEY_LL KEY_MARK KEY_MAX
548 KEY_MESSAGE KEY_MIN KEY_MOVE
549 KEY_NEXT KEY_NPAGE KEY_OPEN
550 KEY_OPTIONS KEY_PPAGE KEY_PREVIOUS
551 KEY_PRINT KEY_REDO KEY_REFERENCE
552 KEY_REFRESH KEY_REPLACE KEY_RESET
553 KEY_RESTART KEY_RESUME KEY_RIGHT
554 KEY_SAVE KEY_SBEG KEY_SCANCEL
555 KEY_SCOMMAND KEY_SCOPY KEY_SCREATE
556 KEY_SDC KEY_SDL KEY_SELECT
557 KEY_SEND KEY_SEOL KEY_SEXIT
558 KEY_SF KEY_SFIND KEY_SHELP
559 KEY_SHOME KEY_SIC KEY_SLEFT
560 KEY_SMESSAGE KEY_SMOVE KEY_SNEXT
561 KEY_SOPTIONS KEY_SPREVIOUS KEY_SPRINT
562 KEY_SR KEY_SREDO KEY_SREPLACE
563 KEY_SRESET KEY_SRIGHT KEY_SRSUME
564 KEY_SSAVE KEY_SSUSPEND KEY_STAB
565 KEY_SUNDO KEY_SUSPEND KEY_UNDO
566 KEY_UP KEY_MOUSE BUTTON1_RELEASED
567 BUTTON1_PRESSED BUTTON1_CLICKED BUTTON1_DOUBLE_CLICKED
568 BUTTON1_TRIPLE_CLICKED BUTTON1_RESERVED_EVENT BUTTON2_RELEASED
569 BUTTON2_PRESSED BUTTON2_CLICKED BUTTON2_DOUBLE_CLICKED
570 BUTTON2_TRIPLE_CLICKED BUTTON2_RESERVED_EVENT BUTTON3_RELEASED
571 BUTTON3_PRESSED BUTTON3_CLICKED BUTTON3_DOUBLE_CLICKED
572 BUTTON3_TRIPLE_CLICKED BUTTON3_RESERVED_EVENT BUTTON4_RELEASED
573 BUTTON4_PRESSED BUTTON4_CLICKED BUTTON4_DOUBLE_CLICKED
574 BUTTON4_TRIPLE_CLICKED BUTTON4_RESERVED_EVENT BUTTON_CTRL
575 BUTTON_SHIFT BUTTON_ALT ALL_MOUSE_EVENTS
576 REPORT_MOUSE_POSITION NCURSES_MOUSE_VERSION E_OK
577 E_SYSTEM_ERROR E_BAD_ARGUMENT E_POSTED
578 E_CONNECTED E_BAD_STATE E_NO_ROOM
579 E_NOT_POSTED E_UNKNOWN_COMMAND E_NO_MATCH
580 E_NOT_SELECTABLE E_NOT_CONNECTED E_REQUEST_DENIED
581 E_INVALID_FIELD E_CURRENT REQ_LEFT_ITEM
582 REQ_RIGHT_ITEM REQ_UP_ITEM REQ_DOWN_ITEM
583 REQ_SCR_ULINE REQ_SCR_DLINE REQ_SCR_DPAGE
584 REQ_SCR_UPAGE REQ_FIRST_ITEM REQ_LAST_ITEM
585 REQ_NEXT_ITEM REQ_PREV_ITEM REQ_TOGGLE_ITEM
586 REQ_CLEAR_PATTERN REQ_BACK_PATTERN REQ_NEXT_MATCH
587 REQ_PREV_MATCH MIN_MENU_COMMAND MAX_MENU_COMMAND
588 O_ONEVALUE O_SHOWDESC O_ROWMAJOR
589 O_IGNORECASE O_SHOWMATCH O_NONCYCLIC
590 O_SELECTABLE REQ_NEXT_PAGE REQ_PREV_PAGE
591 REQ_FIRST_PAGE REQ_LAST_PAGE REQ_NEXT_FIELD
592 REQ_PREV_FIELD REQ_FIRST_FIELD REQ_LAST_FIELD
593 REQ_SNEXT_FIELD REQ_SPREV_FIELD REQ_SFIRST_FIELD
594 REQ_SLAST_FIELD REQ_LEFT_FIELD REQ_RIGHT_FIELD
595 REQ_UP_FIELD REQ_DOWN_FIELD REQ_NEXT_CHAR
596 REQ_PREV_CHAR REQ_NEXT_LINE REQ_PREV_LINE
597 REQ_NEXT_WORD REQ_PREV_WORD REQ_BEG_FIELD
598 REQ_END_FIELD REQ_BEG_LINE REQ_END_LINE
599 REQ_LEFT_CHAR REQ_RIGHT_CHAR REQ_UP_CHAR
600 REQ_DOWN_CHAR REQ_NEW_LINE REQ_INS_CHAR
601 REQ_INS_LINE REQ_DEL_CHAR REQ_DEL_PREV
602 REQ_DEL_LINE REQ_DEL_WORD REQ_CLR_EOL
603 REQ_CLR_EOF REQ_CLR_FIELD REQ_OVL_MODE
604 REQ_INS_MODE REQ_SCR_FLINE REQ_SCR_BLINE
605 REQ_SCR_FPAGE REQ_SCR_BPAGE REQ_SCR_FHPAGE
606 REQ_SCR_BHPAGE REQ_SCR_FCHAR REQ_SCR_BCHAR
607 REQ_SCR_HFLINE REQ_SCR_HBLINE REQ_SCR_HFHALF
608 REQ_SCR_HBHALF REQ_VALIDATION REQ_NEXT_CHOICE
609 REQ_PREV_CHOICE MIN_FORM_COMMAND MAX_FORM_COMMAND
610 NO_JUSTIFICATION JUSTIFY_LEFT JUSTIFY_CENTER
611 JUSTIFY_RIGHT O_VISIBLE O_ACTIVE
612 O_PUBLIC O_EDIT O_WRAP
613 O_BLANK O_AUTOSKIP O_NULLOK
614 O_PASSOK O_STATIC O_NL_OVERLOAD
615 O_BS_OVERLOAD
616 curses[1m(3) functions not supported by "Curses"
618 tstp _putchar fullname scanw wscanw mvscanw mvwscanw ripoffline
620 setupterm setterm set_curterm del_curterm restartterm tparm tputs
621 putp vidputs vidattr mvcur tigetflag tigetnum tigetstr tgetent
622 tgetflag tgetnum tgetstr tgoto tputs
623 menu[1m(3) functions not supported by "Curses"
625 set_item_init item_init set_item_term item_term set_menu_init
627 menu_init set_menu_term menu_term
628 form[1m(3) functions not supported by "Curses"
630 new_fieldtype free_fieldtype set_fieldtype_arg
632 set_fieldtype_choice link_fieldtype set_form_init form_init
633 set_form_term form_term set_field_init field_init set_field_term
634 field_term set_field_type field_type
635perl v5.8.8 2006-10-07 Curses(3)