| blob | d9653281eb5d127345d1bd7712881c8162c5cf8c |
1 PDCurses User's Guide
2 =====================
4 Curses Overview
5 ---------------
7 The X/Open Curses Interface Definition describes a set of C-Language
8 functions that provide screen-handling and updating, which are
9 collectively known as the curses library.
11 The curses library permits manipulation of data structures called
12 windows which may be thought of as two-dimensional arrays of
13 characters representing all or part of a terminal's screen. The
14 windows are manipulated using a procedural interface described
15 elsewhere. The curses package maintains a record of what characters
16 are on the screen. At the most basic level, manipulation is done with
17 the routines move() and addch() which are used to "move" the curses
18 around and add characters to the default window, stdscr, which
19 represents the whole screen.
21 An application may use these routines to add data to the window in any
22 convenient order. Once all data have been added, the routine
23 refresh() is called. The package then determines what changes have
24 been made which affect the screen. The screen contents are then
25 changed to reflect those characters now in the window, using a
26 sequence of operations optimized for the type of terminal in use.
28 At a higher level routines combining the actions of move() and addch()
29 are defined, as are routines to add whole strings and to perform
30 format conversions in the manner of printf().
32 Interfaces are also defined to erase the entire window and to specify
33 the attributes of individual characters in the window. Attributes
34 such as inverse video, underline and blink can be used on a
35 per-character basis.
37 New windows can be created by allowing the application to build
38 several images of the screen and display the appropriate one very
39 quickly. New windows are created using the routine newwin(). For
40 each routine that manipulates the default window, stdscr, there is a
41 corresponding routine prefixed with w to manipulate the contents of a
42 specified window; for example, move() and wmove(). In fact, move(...)
43 is functionally equivalent to wmove( stdscr, ...). This is similar to
44 the interface offered by printf(...) and fprintf(stdout, ...).
46 Windows do not have to correspond to the entire screen. It is
47 possible to create smaller windows, and also to indicate that the
48 window is only partially visible on the screen. Furthermore, large
49 windows or pads, which are bigger than the actual screen size, may be
50 created.
52 Interfaces are also defined to allow input character manipulation and
53 to disable and enable many input attributes: character echo, single
54 character input with or without signal processing (cbreak or raw
55 modes), carriage returns mapping to newlines, screen scrolling, etc.
58 Data Types and the <curses.h> Header
59 ------------------------------------
61 The data types supported by curses are described in this section.
63 As the library supports a procedural interface to the data types, actual
64 structure contents are not described. All curses data are manipulated
65 using the routines provided.
68 THE <curses.h> HEADER
70 The <curses.h> header defines various constants and declares the data
71 types that are available to the application.
74 DATA TYPES
76 The following data types are declared:
78 WINDOW * pointer to screen representation
79 SCREEN * pointer to terminal descriptor
80 bool boolean data type
81 chtype representation of a character in a window
82 cchar_t the wide-character equivalent of chtype
83 attr_t for WA_-style attributes
85 The actual WINDOW and SCREEN objects used to store information are
86 created by the corresponding routines and a pointer to them is provided.
87 All manipulation is through that pointer.
90 VARIABLES
92 The following variables are defined:
94 LINES number of lines on terminal screen
95 COLS number of columns on terminal screen
96 stdscr pointer to the default screen window
97 curscr pointer to the current screen image
98 SP pointer to the current SCREEN struct
99 Mouse_status status of the mouse
100 COLORS number of colors available
101 COLOR_PAIRS number of color pairs available
102 TABSIZE size of one TAB block
103 acs_map[] alternate character set map
104 ttytype[] terminal name/description
107 CONSTANTS
109 The following constants are defined:
111 GENERAL
113 FALSE boolean false value
114 TRUE boolean true value
115 NULL zero pointer value
116 ERR value returned on error condition
117 OK value returned on successful completion
119 VIDEO ATTRIBUTES
121 Normally, attributes are a property of the character.
123 For chtype:
125 A_ALTCHARSET use the alternate character set
126 A_BLINK bright background or blinking
127 A_BOLD bright foreground or bold
128 A_DIM half bright -- no effect in PDCurses
129 A_INVIS invisible
130 A_ITALIC italic
131 A_LEFTLINE line along the left edge
132 A_PROTECT protected (?) -- PDCurses renders this as a
133 combination of the *LINE attributes
134 A_REVERSE reverse video
135 A_RIGHTLINE line along the right edge
136 A_STANDOUT terminal's best highlighting mode
137 A_UNDERLINE underline
139 A_ATTRIBUTES bit-mask to extract attributes
140 A_CHARTEXT bit-mask to extract a character
141 A_COLOR bit-mask to extract a color-pair
143 Not all attributes will work on all terminals. A_RIGHTLINE, A_LEFTLINE
144 and A_ITALIC are specific to PDCurses. A_INVIS and A_ITALIC are given
145 the same value in PDCurses.
147 For attr_t:
149 WA_ALTCHARSET same as A_ALTCHARSET
150 WA_BLINK same as A_BLINK
151 WA_BOLD same as A_BOLD
152 WA_DIM same as A_DIM
153 WA_INVIS same as A_INVIS
154 WA_LEFT same as A_LEFTLINE
155 WA_PROTECT same as A_PROTECT
156 WA_REVERSE same as A_REVERSE
157 WA_RIGHT same as A_RIGHTLINE
158 WA_STANDOUT same as A_STANDOUT
159 WA_UNDERLINE same as A_UNDERLINE
161 Note that while A_LEFTLINE and A_RIGHTLINE are PDCurses-specific,
162 WA_LEFT and WA_RIGHT are standard. The following are also defined, for
163 compatibility, but currently have no effect in PDCurses: WA_HORIZONTAL,
164 WA_LOW, WA_TOP, WA_VERTICAL.
166 THE ALTERNATE CHARACTER SET
168 For use in chtypes and with related functions. These are a portable way
169 to represent graphics characters on different terminals.
171 VT100-compatible symbols -- box characters:
173 ACS_ULCORNER upper left box corner
174 ACS_LLCORNER lower left box corner
175 ACS_URCORNER upper right box corner
176 ACS_LRCORNER lower right box corner
177 ACS_RTEE right "T"
178 ACS_LTEE left "T"
179 ACS_BTEE bottom "T"
180 ACS_TTEE top "T"
181 ACS_HLINE horizontal line
182 ACS_VLINE vertical line
183 ACS_PLUS plus sign, cross, or four-corner piece
185 VT100-compatible symbols -- other:
187 ACS_S1 scan line 1
188 ACS_S9 scan line 9
189 ACS_DIAMOND diamond
190 ACS_CKBOARD checkerboard -- 50% grey
191 ACS_DEGREE degree symbol
192 ACS_PLMINUS plus/minus sign
193 ACS_BULLET bullet
195 Teletype 5410v1 symbols -- these are defined in SysV curses, but
196 are not well-supported by most terminals. Stick to VT100 characters
197 for optimum portability:
199 ACS_LARROW left arrow
200 ACS_RARROW right arrow
201 ACS_DARROW down arrow
202 ACS_UARROW up arrow
203 ACS_BOARD checkerboard -- lighter (less dense) than
204 ACS_CKBOARD
205 ACS_LANTERN lantern symbol
206 ACS_BLOCK solid block
208 That goes double for these -- undocumented SysV symbols. Don't use
209 them:
211 ACS_S3 scan line 3
212 ACS_S7 scan line 7
213 ACS_LEQUAL less than or equal
214 ACS_GEQUAL greater than or equal
215 ACS_PI pi
216 ACS_NEQUAL not equal
217 ACS_STERLING pounds sterling symbol
219 Box character aliases:
221 ACS_BSSB same as ACS_ULCORNER
222 ACS_SSBB same as ACS_LLCORNER
223 ACS_BBSS same as ACS_URCORNER
224 ACS_SBBS same as ACS_LRCORNER
225 ACS_SBSS same as ACS_RTEE
226 ACS_SSSB same as ACS_LTEE
227 ACS_SSBS same as ACS_BTEE
228 ACS_BSSS same as ACS_TTEE
229 ACS_BSBS same as ACS_HLINE
230 ACS_SBSB same as ACS_VLINE
231 ACS_SSSS same as ACS_PLUS
233 For cchar_t and wide-character functions, WACS_ equivalents are also
234 defined.
236 COLORS
238 For use with init_pair(), color_set(), etc.:
240 COLOR_BLACK
241 COLOR_BLUE
242 COLOR_GREEN
243 COLOR_CYAN
244 COLOR_RED
245 COLOR_MAGENTA
246 COLOR_YELLOW
247 COLOR_WHITE
249 Use these instead of numeric values. The definition of the colors
250 depends on the implementation of curses.
253 INPUT VALUES
255 The following constants might be returned by getch() if keypad() has
256 been enabled. Note that not all of these may be supported on a
257 particular terminal:
259 KEY_BREAK break key
260 KEY_DOWN the four arrow keys
261 KEY_UP
262 KEY_LEFT
263 KEY_RIGHT
264 KEY_HOME home key (upward+left arrow)
265 KEY_BACKSPACE backspace
266 KEY_F0 function keys; space for 64 keys is reserved
267 KEY_F(n) (KEY_F0+(n))
268 KEY_DL delete line
269 KEY_IL insert line
270 KEY_DC delete character
271 KEY_IC insert character
272 KEY_EIC exit insert character mode
273 KEY_CLEAR clear screen
274 KEY_EOS clear to end of screen
275 KEY_EOL clear to end of line
276 KEY_SF scroll 1 line forwards
277 KEY_SR scroll 1 line backwards (reverse)
278 KEY_NPAGE next page
279 KEY_PPAGE previous page
280 KEY_STAB set tab
281 KEY_CTAB clear tab
282 KEY_CATAB clear all tabs
283 KEY_ENTER enter or send
284 KEY_SRESET soft (partial) reset
285 KEY_RESET reset or hard reset
286 KEY_PRINT print or copy
287 KEY_LL home down or bottom (lower left)
288 KEY_A1 upper left of virtual keypad
289 KEY_A3 upper right of virtual keypad
290 KEY_B2 center of virtual keypad
291 KEY_C1 lower left of virtual keypad
292 KEY_C3 lower right of virtual keypad
294 KEY_BTAB Back tab key
295 KEY_BEG Beginning key
296 KEY_CANCEL Cancel key
297 KEY_CLOSE Close key
298 KEY_COMMAND Cmd (command) key
299 KEY_COPY Copy key
300 KEY_CREATE Create key
301 KEY_END End key
302 KEY_EXIT Exit key
303 KEY_FIND Find key
304 KEY_HELP Help key
305 KEY_MARK Mark key
306 KEY_MESSAGE Message key
307 KEY_MOVE Move key
308 KEY_NEXT Next object key
309 KEY_OPEN Open key
310 KEY_OPTIONS Options key
311 KEY_PREVIOUS Previous object key
312 KEY_REDO Redo key
313 KEY_REFERENCE Reference key
314 KEY_REFRESH Refresh key
315 KEY_REPLACE Replace key
316 KEY_RESTART Restart key
317 KEY_RESUME Resume key
318 KEY_SAVE Save key
319 KEY_SBEG Shifted beginning key
320 KEY_SCANCEL Shifted cancel key
321 KEY_SCOMMAND Shifted command key
322 KEY_SCOPY Shifted copy key
323 KEY_SCREATE Shifted create key
324 KEY_SDC Shifted delete char key
325 KEY_SDL Shifted delete line key
326 KEY_SELECT Select key
327 KEY_SEND Shifted end key
328 KEY_SEOL Shifted clear line key
329 KEY_SEXIT Shifted exit key
330 KEY_SFIND Shifted find key
331 KEY_SHELP Shifted help key
332 KEY_SHOME Shifted home key
333 KEY_SIC Shifted input key
334 KEY_SLEFT Shifted left arrow key
335 KEY_SMESSAGE Shifted message key
336 KEY_SMOVE Shifted move key
337 KEY_SNEXT Shifted next key
338 KEY_SOPTIONS Shifted options key
339 KEY_SPREVIOUS Shifted prev key
340 KEY_SPRINT Shifted print key
341 KEY_SREDO Shifted redo key
342 KEY_SREPLACE Shifted replace key
343 KEY_SRIGHT Shifted right arrow
344 KEY_SRSUME Shifted resume key
345 KEY_SSAVE Shifted save key
346 KEY_SSUSPEND Shifted suspend key
347 KEY_SUNDO Shifted undo key
348 KEY_SUSPEND Suspend key
349 KEY_UNDO Undo key
351 The virtual keypad is arranged like this:
353 A1 up A3
354 left B2 right
355 C1 down C3
357 This list is incomplete -- see curses.h for the full list, and use the
358 testcurs demo to see what values are actually returned. The above are
359 just the keys required by X/Open. In particular, PDCurses defines many
360 CTL_ and ALT_ combinations; these are not portable.
363 FUNCTIONS
365 The following table lists each curses routine and the name of the manual
366 page on which it is described.
368 Functions from the X/Open curses standard -- complete, except for
369 getch() and ungetch(), which are implemented as macros for DOS
370 compatibility:
372 Curses Function Manual Page Name
374 addch addch
375 addchnstr addchstr
376 addchstr addchstr
377 addnstr addstr
378 addstr addstr
379 attroff attr
380 attron attr
381 attrset attr
382 attr_get attr
383 attr_off attr
384 attr_on attr
385 attr_set attr
386 baudrate termattr
387 beep beep
388 bkgd bkgd
389 bkgdset bkgd
390 border border
391 box border
392 can_change_color color
393 cbreak inopts
394 chgat attr
395 clearok outopts
396 clear clear
397 clrtobot clear
398 clrtoeol clear
399 color_content color
400 color_set attr
401 copywin overlay
402 curs_set kernel
403 def_prog_mode kernel
404 def_shell_mode kernel
405 del_curterm terminfo
406 delay_output util
407 delch delch
408 deleteln deleteln
409 delscreen initscr
410 delwin window
411 derwin window
412 doupdate refresh
413 dupwin window
414 echochar addch
415 echo inopts
416 endwin initscr
417 erasechar termattr
418 erase clear
419 filter util
420 flash beep
421 flushinp getch
422 getbkgd bkgd
423 getnstr getstr
424 getstr getstr
425 getwin scr_dump
426 halfdelay inopts
427 has_colors color
428 has_ic termattr
429 has_il termattr
430 hline border
431 idcok outopts
432 idlok outopts
433 immedok outopts
434 inchnstr inchstr
435 inchstr inchstr
436 inch inch
437 init_color color
438 init_pair color
439 initscr initscr
440 innstr instr
441 insch insch
442 insdelln deleteln
443 insertln deleteln
444 insnstr innstr
445 insstr innstr
446 instr instr
447 intrflush inopts
448 isendwin initscr
449 is_linetouched touch
450 is_wintouched touch
451 keyname keyname
452 keypad inopts
453 killchar termattr
454 leaveok outopts
455 longname termattr
456 meta inopts
457 move move
458 mvaddch addch
459 mvaddchnstr addchstr
460 mvaddchstr addchstr
461 mvaddnstr addstr
462 mvaddstr addstr
463 mvchgat attr
464 mvcur terminfo
465 mvdelch delch
466 mvderwin window
467 mvgetch getch
468 mvgetnstr getstr
469 mvgetstr getstr
470 mvhline border
471 mvinch inch
472 mvinchnstr inchstr
473 mvinchstr inchstr
474 mvinnstr instr
475 mvinsch insch
476 mvinsnstr insstr
477 mvinsstr insstr
478 mvinstr instr
479 mvprintw printw
480 mvscanw scanw
481 mvvline border
482 mvwaddchnstr addchstr
483 mvwaddchstr addchstr
484 mvwaddch addch
485 mvwaddnstr addstr
486 mvwaddstr addstr
487 mvwchgat attr
488 mvwdelch delch
489 mvwgetch getch
490 mvwgetnstr getstr
491 mvwgetstr getstr
492 mvwhline border
493 mvwinchnstr inchstr
494 mvwinchstr inchstr
495 mvwinch inch
496 mvwinnstr instr
497 mvwinsch insch
498 mvwinsnstr insstr
499 mvwinsstr insstr
500 mvwinstr instr
501 mvwin window
502 mvwprintw printw
503 mvwscanw scanw
504 mvwvline border
505 napms kernel
506 newpad pad
507 newterm initscr
508 newwin window
509 nl inopts
510 nocbreak inopts
511 nodelay inopts
512 noecho inopts
513 nonl inopts
514 noqiflush inopts
515 noraw inopts
516 notimeout inopts
517 overlay overlay
518 overwrite overlay
519 pair_content color
520 pechochar pad
521 pnoutrefresh pad
522 prefresh pad
523 printw printw
524 putp terminfo
525 putwin scr_dump
526 qiflush inopts
527 raw inopts
528 redrawwin refresh
529 refresh refresh
530 reset_prog_mode kernel
531 reset_shell_mode kernel
532 resetty kernel
533 restartterm terminfo
534 ripoffline kernel
535 savetty kernel
536 scanw scanw
537 scr_dump scr_dump
538 scr_init scr_dump
539 scr_restore scr_dump
540 scr_set scr_dump
541 scrl scroll
542 scroll scroll
543 scrollok outopts
544 set_term initscr
545 setscrreg outopts
546 setterm terminfo
547 setupterm terminfo
548 slk_attroff slk
549 slk_attr_off slk
550 slk_attron slk
551 slk_attr_on slk
552 slk_attrset slk
553 slk_attr_set slk
554 slk_clear slk
555 slk_color slk
556 slk_init slk
557 slk_label slk
558 slk_noutrefresh slk
559 slk_refresh slk
560 slk_restore slk
561 slk_set slk
562 slk_touch slk
563 standend attr
564 standout attr
565 start_color color
566 subpad pad
567 subwin window
568 syncok window
569 termattrs termattrs
570 term_attrs termattrs
571 termname termattrs
572 tgetent termcap
573 tgetflag termcap
574 tgetnum termcap
575 tgetstr termcap
576 tgoto termcap
577 tigetflag terminfo
578 tigetnum terminfo
579 tigetstr terminfo
580 timeout inopts
581 touchline touch
582 touchwin touch
583 tparm terminfo
584 tputs terminfo
585 typeahead inopts
586 untouchwin touch
587 use_env util
588 vidattr terminfo
589 vid_attr terminfo
590 vidputs terminfo
591 vid_puts terminfo
592 vline border
593 vw_printw printw
594 vwprintw printw
595 vw_scanw scanw
596 vwscanw scanw
597 waddchnstr addchstr
598 waddchstr addchstr
599 waddch addch
600 waddnstr addstr
601 waddstr addstr
602 wattroff attr
603 wattron attr
604 wattrset attr
605 wattr_get attr
606 wattr_off attr
607 wattr_on attr
608 wattr_set attr
609 wbkgdset bkgd
610 wbkgd bkgd
611 wborder border
612 wchgat attr
613 wclear clear
614 wclrtobot clear
615 wclrtoeol clear
616 wcolor_set attr
617 wcursyncup window
618 wdelch delch
619 wdeleteln deleteln
620 wechochar addch
621 werase clear
622 wgetch getch
623 wgetnstr getstr
624 wgetstr getstr
625 whline border
626 winchnstr inchstr
627 winchstr inchstr
628 winch inch
629 winnstr instr
630 winsch insch
631 winsdelln deleteln
632 winsertln deleteln
633 winsnstr insstr
634 winsstr insstr
635 winstr instr
636 wmove move
637 wnoutrefresh refresh
638 wprintw printw
639 wredrawln refresh
640 wrefresh refresh
641 wscanw scanw
642 wscrl scroll
643 wsetscrreg outopts
644 wstandend attr
645 wstandout attr
646 wsyncdown window
647 wsyncup window
648 wtimeout inopts
649 wtouchln touch
650 wvline border
652 Wide-character functions from the X/Open standard -- these are only
653 available when PDCurses is built with PDC_WIDE defined, and the
654 prototypes are only available from curses.h when PDC_WIDE is defined
655 before its inclusion in your app:
657 addnwstr addstr
658 addwstr addstr
659 add_wch addch
660 add_wchnstr addchstr
661 add_wchstr addchstr
662 border_set border
663 box_set border
664 echo_wchar addch
665 erasewchar termattr
666 getbkgrnd bkgd
667 getcchar util
668 getn_wstr getstr
669 get_wch getch
670 get_wstr getstr
671 hline_set border
672 innwstr instr
673 ins_nwstr insstr
674 ins_wch insch
675 ins_wstr insstr
676 inwstr instr
677 in_wch inch
678 in_wchnstr inchstr
679 in_wchstr inchstr
680 key_name keyname
681 killwchar termattr
682 mvaddnwstr addstr
683 mvaddwstr addstr
684 mvadd_wch addch
685 mvadd_wchnstr addchstr
686 mvadd_wchstr addchstr
687 mvgetn_wstr getstr
688 mvget_wch getch
689 mvget_wstr getstr
690 mvhline_set border
691 mvinnwstr instr
692 mvins_nwstr insstr
693 mvins_wch insch
694 mvins_wstr insstr
695 mvinwstr instr
696 mvwaddnwstr addstr
697 mvwaddwstr addstr
698 mvwadd_wch addch
699 mvwadd_wchnstr addchstr
700 mvwadd_wchstr addchstr
701 mvwgetn_wstr getstr
702 mvwget_wch getch
703 mvwget_wstr getstr
704 mvwhline_set border
705 mvwinnwstr instr
706 mvwins_nwstr insstr
707 mvwins_wch insch
708 mvwins_wstr insstr
709 mvwin_wch inch
710 mvwin_wchnstr inchstr
711 mvwin_wchstr inchstr
712 mvwinwstr instr
713 mvwvline_set border
714 pecho_wchar pad
715 setcchar util
716 slk_wset slk
717 unget_wch getch
718 vline_set border
719 waddnwstr addstr
720 waddwstr addstr
721 wadd_wch addch
722 wadd_wchnstr addchstr
723 wadd_wchstr addchstr
724 wbkgrnd bkgd
725 wbkgrndset bkgd
726 wborder_set border
727 wecho_wchar addch
728 wgetbkgrnd bkgd
729 wgetn_wstr getstr
730 wget_wch getch
731 wget_wstr getstr
732 whline_set border
733 winnwstr instr
734 wins_nwstr insstr
735 wins_wch insch
736 wins_wstr insstr
737 winwstr instr
738 win_wch inch
739 win_wchnstr inchstr
740 win_wchstr inchstr
741 wunctrl util
742 wvline_set border
744 Quasi-standard functions, from Sys V or BSD curses:
746 getattrs attr
747 getbegx getyx
748 getbegy getyx
749 getmaxx getyx
750 getmaxy getyx
751 getparx getyx
752 getparx getyx
753 traceoff debug
754 traceon debug
755 unctrl util
757 Classic PDCurses mouse functions, based on Sys V:
759 mouse_set mouse
760 mouse_on mouse
761 mouse_off mouse
762 request_mouse_pos mouse
763 map_button mouse
764 wmouse_position mouse
765 getmouse mouse
766 getbmap mouse
768 Functions from ncurses:
770 assume_default_colors color
771 curses_version initscr
772 has_key keyname
773 use_default_colors color
774 wresize window
776 mouseinterval mouse
777 mousemask mouse
778 mouse_trafo mouse
779 nc_getmouse mouse
780 ungetmouse mouse
781 wenclose mouse
782 wmouse_trafo mouse
784 PDCurses-specific functions -- avoid these in code that's intended to be
785 portable:
787 addrawch addch
788 insrawch insch
789 is_termresized initscr
790 mvaddrawch addch
791 mvdeleteln deleteln
792 mvinsertln deleteln
793 mvinsrawch insch
794 mvwaddrawch addch
795 mvwdeleteln deleteln
796 mvwinsertln deleteln
797 mvwinsrawch insch
798 raw_output outopts
799 resize_term initscr
800 resize_window window
801 slk_wlabel slk
802 waddrawch addch
803 winsrawch insch
804 wordchar termattr
806 PDC_debug debug
807 PDC_ungetch getch
808 PDC_set_blink pdcsetsc
809 PDC_set_line_color color
810 PDC_set_title pdcsetsc
812 PDC_clearclipboard pdcclip
813 PDC_freeclipboard pdcclip
814 PDC_getclipboard pdcclip
815 PDC_setclipboard pdcclip
817 PDC_get_input_fd pdckbd
818 PDC_get_key_modifiers getch
819 PDC_return_key_modifiers getch
820 PDC_save_key_modifiers getch
822 Functions specific to the X11 port of PDCurses:
824 Xinitscr initscr
825 XCursesExit -
826 sb_init sb
827 sb_set_horz sb
828 sb_set_vert sb
829 sb_get_horz sb
830 sb_get_vert sb
831 sb_refresh sb
833 --------------------------------------------------------------------------