PDCurses User's Guide ===================== Curses Overview --------------- The X/Open Curses Interface Definition describes a set of C-Language functions that provide screen-handling and updating, which are collectively known as the curses library. The curses library permits manipulation of data structures called windows which may be thought of as two-dimensional arrays of characters representing all or part of a terminal's screen. The windows are manipulated using a procedural interface described elsewhere. The curses package maintains a record of what characters are on the screen. At the most basic level, manipulation is done with the routines move() and addch() which are used to "move" the curses around and add characters to the default window, stdscr, which represents the whole screen. An application may use these routines to add data to the window in any convenient order. Once all data have been added, the routine refresh() is called. The package then determines what changes have been made which affect the screen. The screen contents are then changed to reflect those characters now in the window, using a sequence of operations optimized for the type of terminal in use. At a higher level routines combining the actions of move() and addch() are defined, as are routines to add whole strings and to perform format conversions in the manner of printf(). Interfaces are also defined to erase the entire window and to specify the attributes of individual characters in the window. Attributes such as inverse video, underline and blink can be used on a per-character basis. New windows can be created by allowing the application to build several images of the screen and display the appropriate one very quickly. New windows are created using the routine newwin(). For each routine that manipulates the default window, stdscr, there is a corresponding routine prefixed with w to manipulate the contents of a specified window; for example, move() and wmove(). In fact, move(...) is functionally equivalent to wmove( stdscr, ...). This is similar to the interface offered by printf(...) and fprintf(stdout, ...). Windows do not have to correspond to the entire screen. It is possible to create smaller windows, and also to indicate that the window is only partially visible on the screen. Furthermore, large windows or pads, which are bigger than the actual screen size, may be created. Interfaces are also defined to allow input character manipulation and to disable and enable many input attributes: character echo, single character input with or without signal processing (cbreak or raw modes), carriage returns mapping to newlines, screen scrolling, etc. Data Types and the <curses.h> Header ------------------------------------ The data types supported by curses are described in this section. As the library supports a procedural interface to the data types, actual structure contents are not described. All curses data are manipulated using the routines provided. THE <curses.h> HEADER The <curses.h> header defines various constants and declares the data types that are available to the application. DATA TYPES The following data types are declared: WINDOW * pointer to screen representation SCREEN * pointer to terminal descriptor bool boolean data type chtype representation of a character in a window cchar_t the wide-character equivalent of chtype attr_t for WA_-style attributes The actual WINDOW and SCREEN objects used to store information are created by the corresponding routines and a pointer to them is provided. All manipulation is through that pointer. VARIABLES The following variables are defined: LINES number of lines on terminal screen COLS number of columns on terminal screen stdscr pointer to the default screen window curscr pointer to the current screen image SP pointer to the current SCREEN struct Mouse_status status of the mouse COLORS number of colors available COLOR_PAIRS number of color pairs available TABSIZE size of one TAB block acs_map[] alternate character set map ttytype[] terminal name/description CONSTANTS The following constants are defined: GENERAL FALSE boolean false value TRUE boolean true value NULL zero pointer value ERR value returned on error condition OK value returned on successful completion VIDEO ATTRIBUTES Normally, attributes are a property of the character. For chtype: A_ALTCHARSET use the alternate character set A_BLINK bright background or blinking A_BOLD bright foreground or bold A_DIM half bright -- no effect in PDCurses A_INVIS invisible A_ITALIC italic A_LEFTLINE line along the left edge A_PROTECT protected (?) -- PDCurses renders this as a combination of the *LINE attributes A_REVERSE reverse video A_RIGHTLINE line along the right edge A_STANDOUT terminal's best highlighting mode A_UNDERLINE underline A_ATTRIBUTES bit-mask to extract attributes A_CHARTEXT bit-mask to extract a character A_COLOR bit-mask to extract a color-pair Not all attributes will work on all terminals. A_RIGHTLINE, A_LEFTLINE and A_ITALIC are specific to PDCurses. A_INVIS and A_ITALIC are given the same value in PDCurses. For attr_t: WA_ALTCHARSET same as A_ALTCHARSET WA_BLINK same as A_BLINK WA_BOLD same as A_BOLD WA_DIM same as A_DIM WA_INVIS same as A_INVIS WA_LEFT same as A_LEFTLINE WA_PROTECT same as A_PROTECT WA_REVERSE same as A_REVERSE WA_RIGHT same as A_RIGHTLINE WA_STANDOUT same as A_STANDOUT WA_UNDERLINE same as A_UNDERLINE Note that while A_LEFTLINE and A_RIGHTLINE are PDCurses-specific, WA_LEFT and WA_RIGHT are standard. The following are also defined, for compatibility, but currently have no effect in PDCurses: WA_HORIZONTAL, WA_LOW, WA_TOP, WA_VERTICAL. THE ALTERNATE CHARACTER SET For use in chtypes and with related functions. These are a portable way to represent graphics characters on different terminals. VT100-compatible symbols -- box characters: ACS_ULCORNER upper left box corner ACS_LLCORNER lower left box corner ACS_URCORNER upper right box corner ACS_LRCORNER lower right box corner ACS_RTEE right "T" ACS_LTEE left "T" ACS_BTEE bottom "T" ACS_TTEE top "T" ACS_HLINE horizontal line ACS_VLINE vertical line ACS_PLUS plus sign, cross, or four-corner piece VT100-compatible symbols -- other: ACS_S1 scan line 1 ACS_S9 scan line 9 ACS_DIAMOND diamond ACS_CKBOARD checkerboard -- 50% grey ACS_DEGREE degree symbol ACS_PLMINUS plus/minus sign ACS_BULLET bullet Teletype 5410v1 symbols -- these are defined in SysV curses, but are not well-supported by most terminals. Stick to VT100 characters for optimum portability: ACS_LARROW left arrow ACS_RARROW right arrow ACS_DARROW down arrow ACS_UARROW up arrow ACS_BOARD checkerboard -- lighter (less dense) than ACS_CKBOARD ACS_LANTERN lantern symbol ACS_BLOCK solid block That goes double for these -- undocumented SysV symbols. Don't use them: ACS_S3 scan line 3 ACS_S7 scan line 7 ACS_LEQUAL less than or equal ACS_GEQUAL greater than or equal ACS_PI pi ACS_NEQUAL not equal ACS_STERLING pounds sterling symbol Box character aliases: ACS_BSSB same as ACS_ULCORNER ACS_SSBB same as ACS_LLCORNER ACS_BBSS same as ACS_URCORNER ACS_SBBS same as ACS_LRCORNER ACS_SBSS same as ACS_RTEE ACS_SSSB same as ACS_LTEE ACS_SSBS same as ACS_BTEE ACS_BSSS same as ACS_TTEE ACS_BSBS same as ACS_HLINE ACS_SBSB same as ACS_VLINE ACS_SSSS same as ACS_PLUS For cchar_t and wide-character functions, WACS_ equivalents are also defined. COLORS For use with init_pair(), color_set(), etc.: COLOR_BLACK COLOR_BLUE COLOR_GREEN COLOR_CYAN COLOR_RED COLOR_MAGENTA COLOR_YELLOW COLOR_WHITE Use these instead of numeric values. The definition of the colors depends on the implementation of curses. INPUT VALUES The following constants might be returned by getch() if keypad() has been enabled. Note that not all of these may be supported on a particular terminal: KEY_BREAK break key KEY_DOWN the four arrow keys KEY_UP KEY_LEFT KEY_RIGHT KEY_HOME home key (upward+left arrow) KEY_BACKSPACE backspace KEY_F0 function keys; space for 64 keys is reserved KEY_F(n) (KEY_F0+(n)) KEY_DL delete line KEY_IL insert line KEY_DC delete character KEY_IC insert character KEY_EIC exit insert character mode KEY_CLEAR clear screen KEY_EOS clear to end of screen KEY_EOL clear to end of line KEY_SF scroll 1 line forwards KEY_SR scroll 1 line backwards (reverse) KEY_NPAGE next page KEY_PPAGE previous page KEY_STAB set tab KEY_CTAB clear tab KEY_CATAB clear all tabs KEY_ENTER enter or send KEY_SRESET soft (partial) reset KEY_RESET reset or hard reset KEY_PRINT print or copy KEY_LL home down or bottom (lower left) KEY_A1 upper left of virtual keypad KEY_A3 upper right of virtual keypad KEY_B2 center of virtual keypad KEY_C1 lower left of virtual keypad KEY_C3 lower right of virtual keypad KEY_BTAB Back tab key KEY_BEG Beginning key KEY_CANCEL Cancel key KEY_CLOSE Close key KEY_COMMAND Cmd (command) key KEY_COPY Copy key KEY_CREATE Create key KEY_END End key KEY_EXIT Exit key KEY_FIND Find key KEY_HELP Help key KEY_MARK Mark key KEY_MESSAGE Message key KEY_MOVE Move key KEY_NEXT Next object key KEY_OPEN Open key KEY_OPTIONS Options key KEY_PREVIOUS Previous object key KEY_REDO Redo key KEY_REFERENCE Reference key KEY_REFRESH Refresh key KEY_REPLACE Replace key KEY_RESTART Restart key KEY_RESUME Resume key KEY_SAVE Save key KEY_SBEG Shifted beginning key KEY_SCANCEL Shifted cancel key KEY_SCOMMAND Shifted command key KEY_SCOPY Shifted copy key KEY_SCREATE Shifted create key KEY_SDC Shifted delete char key KEY_SDL Shifted delete line key KEY_SELECT Select key KEY_SEND Shifted end key KEY_SEOL Shifted clear line key KEY_SEXIT Shifted exit key KEY_SFIND Shifted find key KEY_SHELP Shifted help key KEY_SHOME Shifted home key KEY_SIC Shifted input key KEY_SLEFT Shifted left arrow key KEY_SMESSAGE Shifted message key KEY_SMOVE Shifted move key KEY_SNEXT Shifted next key KEY_SOPTIONS Shifted options key KEY_SPREVIOUS Shifted prev key KEY_SPRINT Shifted print key KEY_SREDO Shifted redo key KEY_SREPLACE Shifted replace key KEY_SRIGHT Shifted right arrow KEY_SRSUME Shifted resume key KEY_SSAVE Shifted save key KEY_SSUSPEND Shifted suspend key KEY_SUNDO Shifted undo key KEY_SUSPEND Suspend key KEY_UNDO Undo key The virtual keypad is arranged like this: A1 up A3 left B2 right C1 down C3 This list is incomplete -- see curses.h for the full list, and use the testcurs demo to see what values are actually returned. The above are just the keys required by X/Open. In particular, PDCurses defines many CTL_ and ALT_ combinations; these are not portable. FUNCTIONS The following table lists each curses routine and the name of the manual page on which it is described. Functions from the X/Open curses standard -- complete, except for getch() and ungetch(), which are implemented as macros for DOS compatibility: Curses Function Manual Page Name addch addch addchnstr addchstr addchstr addchstr addnstr addstr addstr addstr attroff attr attron attr attrset attr attr_get attr attr_off attr attr_on attr attr_set attr baudrate termattr beep beep bkgd bkgd bkgdset bkgd border border box border can_change_color color cbreak inopts chgat attr clearok outopts clear clear clrtobot clear clrtoeol clear color_content color color_set attr copywin overlay curs_set kernel def_prog_mode kernel def_shell_mode kernel del_curterm terminfo delay_output util delch delch deleteln deleteln delscreen initscr delwin window derwin window doupdate refresh dupwin window echochar addch echo inopts endwin initscr erasechar termattr erase clear filter util flash beep flushinp getch getbkgd bkgd getnstr getstr getstr getstr getwin scr_dump halfdelay inopts has_colors color has_ic termattr has_il termattr hline border idcok outopts idlok outopts immedok outopts inchnstr inchstr inchstr inchstr inch inch init_color color init_pair color initscr initscr innstr instr insch insch insdelln deleteln insertln deleteln insnstr innstr insstr innstr instr instr intrflush inopts isendwin initscr is_linetouched touch is_wintouched touch keyname keyname keypad inopts killchar termattr leaveok outopts longname termattr meta inopts move move mvaddch addch mvaddchnstr addchstr mvaddchstr addchstr mvaddnstr addstr mvaddstr addstr mvchgat attr mvcur terminfo mvdelch delch mvderwin window mvgetch getch mvgetnstr getstr mvgetstr getstr mvhline border mvinch inch mvinchnstr inchstr mvinchstr inchstr mvinnstr instr mvinsch insch mvinsnstr insstr mvinsstr insstr mvinstr instr mvprintw printw mvscanw scanw mvvline border mvwaddchnstr addchstr mvwaddchstr addchstr mvwaddch addch mvwaddnstr addstr mvwaddstr addstr mvwchgat attr mvwdelch delch mvwgetch getch mvwgetnstr getstr mvwgetstr getstr mvwhline border mvwinchnstr inchstr mvwinchstr inchstr mvwinch inch mvwinnstr instr mvwinsch insch mvwinsnstr insstr mvwinsstr insstr mvwinstr instr mvwin window mvwprintw printw mvwscanw scanw mvwvline border napms kernel newpad pad newterm initscr newwin window nl inopts nocbreak inopts nodelay inopts noecho inopts nonl inopts noqiflush inopts noraw inopts notimeout inopts overlay overlay overwrite overlay pair_content color pechochar pad pnoutrefresh pad prefresh pad printw printw putp terminfo putwin scr_dump qiflush inopts raw inopts redrawwin refresh refresh refresh reset_prog_mode kernel reset_shell_mode kernel resetty kernel restartterm terminfo ripoffline kernel savetty kernel scanw scanw scr_dump scr_dump scr_init scr_dump scr_restore scr_dump scr_set scr_dump scrl scroll scroll scroll scrollok outopts set_term initscr setscrreg outopts setterm terminfo setupterm terminfo slk_attroff slk slk_attr_off slk slk_attron slk slk_attr_on slk slk_attrset slk slk_attr_set slk slk_clear slk slk_color slk slk_init slk slk_label slk slk_noutrefresh slk slk_refresh slk slk_restore slk slk_set slk slk_touch slk standend attr standout attr start_color color subpad pad subwin window syncok window termattrs termattrs term_attrs termattrs termname termattrs tgetent termcap tgetflag termcap tgetnum termcap tgetstr termcap tgoto termcap tigetflag terminfo tigetnum terminfo tigetstr terminfo timeout inopts touchline touch touchwin touch tparm terminfo tputs terminfo typeahead inopts untouchwin touch use_env util vidattr terminfo vid_attr terminfo vidputs terminfo vid_puts terminfo vline border vw_printw printw vwprintw printw vw_scanw scanw vwscanw scanw waddchnstr addchstr waddchstr addchstr waddch addch waddnstr addstr waddstr addstr wattroff attr wattron attr wattrset attr wattr_get attr wattr_off attr wattr_on attr wattr_set attr wbkgdset bkgd wbkgd bkgd wborder border wchgat attr wclear clear wclrtobot clear wclrtoeol clear wcolor_set attr wcursyncup window wdelch delch wdeleteln deleteln wechochar addch werase clear wgetch getch wgetnstr getstr wgetstr getstr whline border winchnstr inchstr winchstr inchstr winch inch winnstr instr winsch insch winsdelln deleteln winsertln deleteln winsnstr insstr winsstr insstr winstr instr wmove move wnoutrefresh refresh wprintw printw wredrawln refresh wrefresh refresh wscanw scanw wscrl scroll wsetscrreg outopts wstandend attr wstandout attr wsyncdown window wsyncup window wtimeout inopts wtouchln touch wvline border Wide-character functions from the X/Open standard -- these are only available when PDCurses is built with PDC_WIDE defined, and the prototypes are only available from curses.h when PDC_WIDE is defined before its inclusion in your app: addnwstr addstr addwstr addstr add_wch addch add_wchnstr addchstr add_wchstr addchstr border_set border box_set border echo_wchar addch erasewchar termattr getbkgrnd bkgd getcchar util getn_wstr getstr get_wch getch get_wstr getstr hline_set border innwstr instr ins_nwstr insstr ins_wch insch ins_wstr insstr inwstr instr in_wch inch in_wchnstr inchstr in_wchstr inchstr key_name keyname killwchar termattr mvaddnwstr addstr mvaddwstr addstr mvadd_wch addch mvadd_wchnstr addchstr mvadd_wchstr addchstr mvgetn_wstr getstr mvget_wch getch mvget_wstr getstr mvhline_set border mvinnwstr instr mvins_nwstr insstr mvins_wch insch mvins_wstr insstr mvinwstr instr mvwaddnwstr addstr mvwaddwstr addstr mvwadd_wch addch mvwadd_wchnstr addchstr mvwadd_wchstr addchstr mvwgetn_wstr getstr mvwget_wch getch mvwget_wstr getstr mvwhline_set border mvwinnwstr instr mvwins_nwstr insstr mvwins_wch insch mvwins_wstr insstr mvwin_wch inch mvwin_wchnstr inchstr mvwin_wchstr inchstr mvwinwstr instr mvwvline_set border pecho_wchar pad setcchar util slk_wset slk unget_wch getch vline_set border waddnwstr addstr waddwstr addstr wadd_wch addch wadd_wchnstr addchstr wadd_wchstr addchstr wbkgrnd bkgd wbkgrndset bkgd wborder_set border wecho_wchar addch wgetbkgrnd bkgd wgetn_wstr getstr wget_wch getch wget_wstr getstr whline_set border winnwstr instr wins_nwstr insstr wins_wch insch wins_wstr insstr winwstr instr win_wch inch win_wchnstr inchstr win_wchstr inchstr wunctrl util wvline_set border Quasi-standard functions, from Sys V or BSD curses: getattrs attr getbegx getyx getbegy getyx getmaxx getyx getmaxy getyx getparx getyx getparx getyx traceoff debug traceon debug unctrl util Classic PDCurses mouse functions, based on Sys V: mouse_set mouse mouse_on mouse mouse_off mouse request_mouse_pos mouse map_button mouse wmouse_position mouse getmouse mouse getbmap mouse Functions from ncurses: assume_default_colors color curses_version initscr has_key keyname use_default_colors color wresize window mouseinterval mouse mousemask mouse mouse_trafo mouse nc_getmouse mouse ungetmouse mouse wenclose mouse wmouse_trafo mouse PDCurses-specific functions -- avoid these in code that's intended to be portable: addrawch addch insrawch insch is_termresized initscr mvaddrawch addch mvdeleteln deleteln mvinsertln deleteln mvinsrawch insch mvwaddrawch addch mvwdeleteln deleteln mvwinsertln deleteln mvwinsrawch insch raw_output outopts resize_term initscr resize_window window slk_wlabel slk waddrawch addch winsrawch insch wordchar termattr PDC_debug debug PDC_ungetch getch PDC_set_blink pdcsetsc PDC_set_line_color color PDC_set_title pdcsetsc PDC_clearclipboard pdcclip PDC_freeclipboard pdcclip PDC_getclipboard pdcclip PDC_setclipboard pdcclip PDC_get_input_fd pdckbd PDC_get_key_modifiers getch PDC_return_key_modifiers getch PDC_save_key_modifiers getch Functions specific to the X11 port of PDCurses: Xinitscr initscr XCursesExit - sb_init sb sb_set_horz sb sb_set_vert sb sb_get_horz sb sb_get_vert sb sb_refresh sb --------------------------------------------------------------------------