diff options
Diffstat (limited to 'payloads/libpayload/curses/PDCurses-3.4/doc/intro.txt')
| -rw-r--r-- | payloads/libpayload/curses/PDCurses-3.4/doc/intro.txt | 834 |
1 files changed, 834 insertions, 0 deletions
diff --git a/payloads/libpayload/curses/PDCurses-3.4/doc/intro.txt b/payloads/libpayload/curses/PDCurses-3.4/doc/intro.txt new file mode 100644 index 0000000000..a13cb7af2f --- /dev/null +++ b/payloads/libpayload/curses/PDCurses-3.4/doc/intro.txt @@ -0,0 +1,834 @@ +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 + +-------------------------------------------------------------------------- + |