1PDCurses User's Guide 2===================== 3 4Curses Overview 5--------------- 6 7The X/Open Curses Interface Definition describes a set of C-Language 8functions that provide screen-handling and updating, which are 9collectively known as the curses library. 10 11The curses library permits manipulation of data structures called 12windows which may be thought of as two-dimensional arrays of 13characters representing all or part of a terminal's screen. The 14windows are manipulated using a procedural interface described 15elsewhere. The curses package maintains a record of what characters 16are on the screen. At the most basic level, manipulation is done with 17the routines move() and addch() which are used to "move" the curses 18around and add characters to the default window, stdscr, which 19represents the whole screen. 20 21An application may use these routines to add data to the window in any 22convenient order. Once all data have been added, the routine 23refresh() is called. The package then determines what changes have 24been made which affect the screen. The screen contents are then 25changed to reflect those characters now in the window, using a 26sequence of operations optimized for the type of terminal in use. 27 28At a higher level routines combining the actions of move() and addch() 29are defined, as are routines to add whole strings and to perform 30format conversions in the manner of printf(). 31 32Interfaces are also defined to erase the entire window and to specify 33the attributes of individual characters in the window. Attributes 34such as inverse video, underline and blink can be used on a 35per-character basis. 36 37New windows can be created by allowing the application to build 38several images of the screen and display the appropriate one very 39quickly. New windows are created using the routine newwin(). For 40each routine that manipulates the default window, stdscr, there is a 41corresponding routine prefixed with w to manipulate the contents of a 42specified window; for example, move() and wmove(). In fact, move(...) 43is functionally equivalent to wmove( stdscr, ...). This is similar to 44the interface offered by printf(...) and fprintf(stdout, ...). 45 46Windows do not have to correspond to the entire screen. It is 47possible to create smaller windows, and also to indicate that the 48window is only partially visible on the screen. Furthermore, large 49windows or pads, which are bigger than the actual screen size, may be 50created. 51 52Interfaces are also defined to allow input character manipulation and 53to disable and enable many input attributes: character echo, single 54character input with or without signal processing (cbreak or raw 55modes), carriage returns mapping to newlines, screen scrolling, etc. 56 57 58Data Types and the <curses.h> Header 59------------------------------------ 60 61The data types supported by curses are described in this section. 62 63As the library supports a procedural interface to the data types, actual 64structure contents are not described. All curses data are manipulated 65using the routines provided. 66 67 68THE <curses.h> HEADER 69 70The <curses.h> header defines various constants and declares the data 71types that are available to the application. 72 73 74DATA TYPES 75 76The following data types are declared: 77 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 84 85The actual WINDOW and SCREEN objects used to store information are 86created by the corresponding routines and a pointer to them is provided. 87All manipulation is through that pointer. 88 89 90VARIABLES 91 92The following variables are defined: 93 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 105 106 107CONSTANTS 108 109The following constants are defined: 110 111GENERAL 112 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 118 119VIDEO ATTRIBUTES 120 121Normally, attributes are a property of the character. 122 123For chtype: 124 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 138 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 142 143Not all attributes will work on all terminals. A_RIGHTLINE, A_LEFTLINE 144and A_ITALIC are specific to PDCurses. A_INVIS and A_ITALIC are given 145the same value in PDCurses. 146 147For attr_t: 148 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 160 161Note that while A_LEFTLINE and A_RIGHTLINE are PDCurses-specific, 162WA_LEFT and WA_RIGHT are standard. The following are also defined, for 163compatibility, but currently have no effect in PDCurses: WA_HORIZONTAL, 164WA_LOW, WA_TOP, WA_VERTICAL. 165 166THE ALTERNATE CHARACTER SET 167 168For use in chtypes and with related functions. These are a portable way 169to represent graphics characters on different terminals. 170 171VT100-compatible symbols -- box characters: 172 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 184 185VT100-compatible symbols -- other: 186 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 194 195Teletype 5410v1 symbols -- these are defined in SysV curses, but 196are not well-supported by most terminals. Stick to VT100 characters 197for optimum portability: 198 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 207 208That goes double for these -- undocumented SysV symbols. Don't use 209them: 210 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 218 219Box character aliases: 220 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 232 233For cchar_t and wide-character functions, WACS_ equivalents are also 234defined. 235 236COLORS 237 238For use with init_pair(), color_set(), etc.: 239 240 COLOR_BLACK 241 COLOR_BLUE 242 COLOR_GREEN 243 COLOR_CYAN 244 COLOR_RED 245 COLOR_MAGENTA 246 COLOR_YELLOW 247 COLOR_WHITE 248 249Use these instead of numeric values. The definition of the colors 250depends on the implementation of curses. 251 252 253INPUT VALUES 254 255The following constants might be returned by getch() if keypad() has 256been enabled. Note that not all of these may be supported on a 257particular terminal: 258 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 293 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 350 351The virtual keypad is arranged like this: 352 353 A1 up A3 354 left B2 right 355 C1 down C3 356 357This list is incomplete -- see curses.h for the full list, and use the 358testcurs demo to see what values are actually returned. The above are 359just the keys required by X/Open. In particular, PDCurses defines many 360CTL_ and ALT_ combinations; these are not portable. 361 362 363FUNCTIONS 364 365The following table lists each curses routine and the name of the manual 366page on which it is described. 367 368Functions from the X/Open curses standard -- complete, except for 369getch() and ungetch(), which are implemented as macros for DOS 370compatibility: 371 372 Curses Function Manual Page Name 373 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 651 652Wide-character functions from the X/Open standard -- these are only 653available when PDCurses is built with PDC_WIDE defined, and the 654prototypes are only available from curses.h when PDC_WIDE is defined 655before its inclusion in your app: 656 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 743 744Quasi-standard functions, from Sys V or BSD curses: 745 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 756 757Classic PDCurses mouse functions, based on Sys V: 758 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 767 768Functions from ncurses: 769 770 assume_default_colors color 771 curses_version initscr 772 has_key keyname 773 use_default_colors color 774 wresize window 775 776 mouseinterval mouse 777 mousemask mouse 778 mouse_trafo mouse 779 nc_getmouse mouse 780 ungetmouse mouse 781 wenclose mouse 782 wmouse_trafo mouse 783 784PDCurses-specific functions -- avoid these in code that's intended to be 785portable: 786 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 805 806 PDC_debug debug 807 PDC_ungetch getch 808 PDC_set_blink pdcsetsc 809 PDC_set_line_color color 810 PDC_set_title pdcsetsc 811 812 PDC_clearclipboard pdcclip 813 PDC_freeclipboard pdcclip 814 PDC_getclipboard pdcclip 815 PDC_setclipboard pdcclip 816 817 PDC_get_input_fd pdckbd 818 PDC_get_key_modifiers getch 819 PDC_return_key_modifiers getch 820 PDC_save_key_modifiers getch 821 822Functions specific to the X11 port of PDCurses: 823 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 832 833-------------------------------------------------------------------------- 834