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