URL
https://opencores.org/ocsvn/openrisc/openrisc/trunk
Subversion Repositories openrisc
[/] [openrisc/] [trunk/] [rtos/] [ecos-3.0/] [packages/] [services/] [curses/] [pdcurses/] [current/] [doc/] [intro.txt] - Rev 786
Compare with Previous | Blame | View Log
PDCurses User's Guide=====================Curses Overview---------------The X/Open Curses Interface Definition describes a set of C-Languagefunctions that provide screen-handling and updating, which arecollectively known as the curses library.The curses library permits manipulation of data structures calledwindows which may be thought of as two-dimensional arrays ofcharacters representing all or part of a terminal's screen. Thewindows are manipulated using a procedural interface describedelsewhere. The curses package maintains a record of what charactersare on the screen. At the most basic level, manipulation is done withthe routines move() and addch() which are used to "move" the cursesaround and add characters to the default window, stdscr, whichrepresents the whole screen.An application may use these routines to add data to the window in anyconvenient order. Once all data have been added, the routinerefresh() is called. The package then determines what changes havebeen made which affect the screen. The screen contents are thenchanged to reflect those characters now in the window, using asequence 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 performformat conversions in the manner of printf().Interfaces are also defined to erase the entire window and to specifythe attributes of individual characters in the window. Attributessuch as inverse video, underline and blink can be used on aper-character basis.New windows can be created by allowing the application to buildseveral images of the screen and display the appropriate one veryquickly. New windows are created using the routine newwin(). Foreach routine that manipulates the default window, stdscr, there is acorresponding routine prefixed with w to manipulate the contents of aspecified window; for example, move() and wmove(). In fact, move(...)is functionally equivalent to wmove( stdscr, ...). This is similar tothe interface offered by printf(...) and fprintf(stdout, ...).Windows do not have to correspond to the entire screen. It ispossible to create smaller windows, and also to indicate that thewindow is only partially visible on the screen. Furthermore, largewindows or pads, which are bigger than the actual screen size, may becreated.Interfaces are also defined to allow input character manipulation andto disable and enable many input attributes: character echo, singlecharacter input with or without signal processing (cbreak or rawmodes), 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, actualstructure contents are not described. All curses data are manipulatedusing the routines provided.THE <curses.h> HEADERThe <curses.h> header defines various constants and declares the datatypes that are available to the application.DATA TYPESThe following data types are declared:WINDOW * pointer to screen representationSCREEN * pointer to terminal descriptorbool boolean data typechtype representation of a character in a windowcchar_t the wide-character equivalent of chtypeattr_t for WA_-style attributesThe actual WINDOW and SCREEN objects used to store information arecreated by the corresponding routines and a pointer to them is provided.All manipulation is through that pointer.VARIABLESThe following variables are defined:LINES number of lines on terminal screenCOLS number of columns on terminal screenstdscr pointer to the default screen windowcurscr pointer to the current screen imageSP pointer to the current SCREEN structMouse_status status of the mouseCOLORS number of colors availableCOLOR_PAIRS number of color pairs availableTABSIZE size of one TAB blockacs_map[] alternate character set mapttytype[] terminal name/descriptionCONSTANTSThe following constants are defined:GENERALFALSE boolean false valueTRUE boolean true valueNULL zero pointer valueERR value returned on error conditionOK value returned on successful completionVIDEO ATTRIBUTESNormally, attributes are a property of the character.For chtype:A_ALTCHARSET use the alternate character setA_BLINK bright background or blinkingA_BOLD bright foreground or boldA_DIM half bright -- no effect in PDCursesA_INVIS invisibleA_ITALIC italicA_LEFTLINE line along the left edgeA_PROTECT protected (?) -- PDCurses renders this as acombination of the *LINE attributesA_REVERSE reverse videoA_RIGHTLINE line along the right edgeA_STANDOUT terminal's best highlighting modeA_UNDERLINE underlineA_ATTRIBUTES bit-mask to extract attributesA_CHARTEXT bit-mask to extract a characterA_COLOR bit-mask to extract a color-pairNot all attributes will work on all terminals. A_RIGHTLINE, A_LEFTLINEand A_ITALIC are specific to PDCurses. A_INVIS and A_ITALIC are giventhe same value in PDCurses.For attr_t:WA_ALTCHARSET same as A_ALTCHARSETWA_BLINK same as A_BLINKWA_BOLD same as A_BOLDWA_DIM same as A_DIMWA_INVIS same as A_INVISWA_LEFT same as A_LEFTLINEWA_PROTECT same as A_PROTECTWA_REVERSE same as A_REVERSEWA_RIGHT same as A_RIGHTLINEWA_STANDOUT same as A_STANDOUTWA_UNDERLINE same as A_UNDERLINENote that while A_LEFTLINE and A_RIGHTLINE are PDCurses-specific,WA_LEFT and WA_RIGHT are standard. The following are also defined, forcompatibility, but currently have no effect in PDCurses: WA_HORIZONTAL,WA_LOW, WA_TOP, WA_VERTICAL.THE ALTERNATE CHARACTER SETFor use in chtypes and with related functions. These are a portable wayto represent graphics characters on different terminals.VT100-compatible symbols -- box characters:ACS_ULCORNER upper left box cornerACS_LLCORNER lower left box cornerACS_URCORNER upper right box cornerACS_LRCORNER lower right box cornerACS_RTEE right "T"ACS_LTEE left "T"ACS_BTEE bottom "T"ACS_TTEE top "T"ACS_HLINE horizontal lineACS_VLINE vertical lineACS_PLUS plus sign, cross, or four-corner pieceVT100-compatible symbols -- other:ACS_S1 scan line 1ACS_S9 scan line 9ACS_DIAMOND diamondACS_CKBOARD checkerboard -- 50% greyACS_DEGREE degree symbolACS_PLMINUS plus/minus signACS_BULLET bulletTeletype 5410v1 symbols -- these are defined in SysV curses, butare not well-supported by most terminals. Stick to VT100 charactersfor optimum portability:ACS_LARROW left arrowACS_RARROW right arrowACS_DARROW down arrowACS_UARROW up arrowACS_BOARD checkerboard -- lighter (less dense) thanACS_CKBOARDACS_LANTERN lantern symbolACS_BLOCK solid blockThat goes double for these -- undocumented SysV symbols. Don't usethem:ACS_S3 scan line 3ACS_S7 scan line 7ACS_LEQUAL less than or equalACS_GEQUAL greater than or equalACS_PI piACS_NEQUAL not equalACS_STERLING pounds sterling symbolBox character aliases:ACS_BSSB same as ACS_ULCORNERACS_SSBB same as ACS_LLCORNERACS_BBSS same as ACS_URCORNERACS_SBBS same as ACS_LRCORNERACS_SBSS same as ACS_RTEEACS_SSSB same as ACS_LTEEACS_SSBS same as ACS_BTEEACS_BSSS same as ACS_TTEEACS_BSBS same as ACS_HLINEACS_SBSB same as ACS_VLINEACS_SSSS same as ACS_PLUSFor cchar_t and wide-character functions, WACS_ equivalents are alsodefined.COLORSFor use with init_pair(), color_set(), etc.:COLOR_BLACKCOLOR_BLUECOLOR_GREENCOLOR_CYANCOLOR_REDCOLOR_MAGENTACOLOR_YELLOWCOLOR_WHITEUse these instead of numeric values. The definition of the colorsdepends on the implementation of curses.INPUT VALUESThe following constants might be returned by getch() if keypad() hasbeen enabled. Note that not all of these may be supported on aparticular terminal:KEY_BREAK break keyKEY_DOWN the four arrow keysKEY_UPKEY_LEFTKEY_RIGHTKEY_HOME home key (upward+left arrow)KEY_BACKSPACE backspaceKEY_F0 function keys; space for 64 keys is reservedKEY_F(n) (KEY_F0+(n))KEY_DL delete lineKEY_IL insert lineKEY_DC delete characterKEY_IC insert characterKEY_EIC exit insert character modeKEY_CLEAR clear screenKEY_EOS clear to end of screenKEY_EOL clear to end of lineKEY_SF scroll 1 line forwardsKEY_SR scroll 1 line backwards (reverse)KEY_NPAGE next pageKEY_PPAGE previous pageKEY_STAB set tabKEY_CTAB clear tabKEY_CATAB clear all tabsKEY_ENTER enter or sendKEY_SRESET soft (partial) resetKEY_RESET reset or hard resetKEY_PRINT print or copyKEY_LL home down or bottom (lower left)KEY_A1 upper left of virtual keypadKEY_A3 upper right of virtual keypadKEY_B2 center of virtual keypadKEY_C1 lower left of virtual keypadKEY_C3 lower right of virtual keypadKEY_BTAB Back tab keyKEY_BEG Beginning keyKEY_CANCEL Cancel keyKEY_CLOSE Close keyKEY_COMMAND Cmd (command) keyKEY_COPY Copy keyKEY_CREATE Create keyKEY_END End keyKEY_EXIT Exit keyKEY_FIND Find keyKEY_HELP Help keyKEY_MARK Mark keyKEY_MESSAGE Message keyKEY_MOVE Move keyKEY_NEXT Next object keyKEY_OPEN Open keyKEY_OPTIONS Options keyKEY_PREVIOUS Previous object keyKEY_REDO Redo keyKEY_REFERENCE Reference keyKEY_REFRESH Refresh keyKEY_REPLACE Replace keyKEY_RESTART Restart keyKEY_RESUME Resume keyKEY_SAVE Save keyKEY_SBEG Shifted beginning keyKEY_SCANCEL Shifted cancel keyKEY_SCOMMAND Shifted command keyKEY_SCOPY Shifted copy keyKEY_SCREATE Shifted create keyKEY_SDC Shifted delete char keyKEY_SDL Shifted delete line keyKEY_SELECT Select keyKEY_SEND Shifted end keyKEY_SEOL Shifted clear line keyKEY_SEXIT Shifted exit keyKEY_SFIND Shifted find keyKEY_SHELP Shifted help keyKEY_SHOME Shifted home keyKEY_SIC Shifted input keyKEY_SLEFT Shifted left arrow keyKEY_SMESSAGE Shifted message keyKEY_SMOVE Shifted move keyKEY_SNEXT Shifted next keyKEY_SOPTIONS Shifted options keyKEY_SPREVIOUS Shifted prev keyKEY_SPRINT Shifted print keyKEY_SREDO Shifted redo keyKEY_SREPLACE Shifted replace keyKEY_SRIGHT Shifted right arrowKEY_SRSUME Shifted resume keyKEY_SSAVE Shifted save keyKEY_SSUSPEND Shifted suspend keyKEY_SUNDO Shifted undo keyKEY_SUSPEND Suspend keyKEY_UNDO Undo keyThe virtual keypad is arranged like this:A1 up A3left B2 rightC1 down C3This list is incomplete -- see curses.h for the full list, and use thetestcurs demo to see what values are actually returned. The above arejust the keys required by X/Open. In particular, PDCurses defines manyCTL_ and ALT_ combinations; these are not portable.FUNCTIONSThe following table lists each curses routine and the name of the manualpage on which it is described.Functions from the X/Open curses standard -- complete, except forgetch() and ungetch(), which are implemented as macros for DOScompatibility:Curses Function Manual Page Nameaddch addchaddchnstr addchstraddchstr addchstraddnstr addstraddstr addstrattroff attrattron attrattrset attrattr_get attrattr_off attrattr_on attrattr_set attrbaudrate termattrbeep beepbkgd bkgdbkgdset bkgdborder borderbox bordercan_change_color colorcbreak inoptschgat attrclearok outoptsclear clearclrtobot clearclrtoeol clearcolor_content colorcolor_set attrcopywin overlaycurs_set kerneldef_prog_mode kerneldef_shell_mode kerneldel_curterm terminfodelay_output utildelch delchdeleteln deletelndelscreen initscrdelwin windowderwin windowdoupdate refreshdupwin windowechochar addchecho inoptsendwin initscrerasechar termattrerase clearfilter utilflash beepflushinp getchgetbkgd bkgdgetnstr getstrgetstr getstrgetwin scr_dumphalfdelay inoptshas_colors colorhas_ic termattrhas_il termattrhline borderidcok outoptsidlok outoptsimmedok outoptsinchnstr inchstrinchstr inchstrinch inchinit_color colorinit_pair colorinitscr initscrinnstr instrinsch inschinsdelln deletelninsertln deletelninsnstr innstrinsstr innstrinstr instrintrflush inoptsisendwin initscris_linetouched touchis_wintouched touchkeyname keynamekeypad inoptskillchar termattrleaveok outoptslongname termattrmeta inoptsmove movemvaddch addchmvaddchnstr addchstrmvaddchstr addchstrmvaddnstr addstrmvaddstr addstrmvchgat attrmvcur terminfomvdelch delchmvderwin windowmvgetch getchmvgetnstr getstrmvgetstr getstrmvhline bordermvinch inchmvinchnstr inchstrmvinchstr inchstrmvinnstr instrmvinsch inschmvinsnstr insstrmvinsstr insstrmvinstr instrmvprintw printwmvscanw scanwmvvline bordermvwaddchnstr addchstrmvwaddchstr addchstrmvwaddch addchmvwaddnstr addstrmvwaddstr addstrmvwchgat attrmvwdelch delchmvwgetch getchmvwgetnstr getstrmvwgetstr getstrmvwhline bordermvwinchnstr inchstrmvwinchstr inchstrmvwinch inchmvwinnstr instrmvwinsch inschmvwinsnstr insstrmvwinsstr insstrmvwinstr instrmvwin windowmvwprintw printwmvwscanw scanwmvwvline bordernapms kernelnewpad padnewterm initscrnewwin windownl inoptsnocbreak inoptsnodelay inoptsnoecho inoptsnonl inoptsnoqiflush inoptsnoraw inoptsnotimeout inoptsoverlay overlayoverwrite overlaypair_content colorpechochar padpnoutrefresh padprefresh padprintw printwputp terminfoputwin scr_dumpqiflush inoptsraw inoptsredrawwin refreshrefresh refreshreset_prog_mode kernelreset_shell_mode kernelresetty kernelrestartterm terminforipoffline kernelsavetty kernelscanw scanwscr_dump scr_dumpscr_init scr_dumpscr_restore scr_dumpscr_set scr_dumpscrl scrollscroll scrollscrollok outoptsset_term initscrsetscrreg outoptssetterm terminfosetupterm terminfoslk_attroff slkslk_attr_off slkslk_attron slkslk_attr_on slkslk_attrset slkslk_attr_set slkslk_clear slkslk_color slkslk_init slkslk_label slkslk_noutrefresh slkslk_refresh slkslk_restore slkslk_set slkslk_touch slkstandend attrstandout attrstart_color colorsubpad padsubwin windowsyncok windowtermattrs termattrsterm_attrs termattrstermname termattrstgetent termcaptgetflag termcaptgetnum termcaptgetstr termcaptgoto termcaptigetflag terminfotigetnum terminfotigetstr terminfotimeout inoptstouchline touchtouchwin touchtparm terminfotputs terminfotypeahead inoptsuntouchwin touchuse_env utilvidattr terminfovid_attr terminfovidputs terminfovid_puts terminfovline bordervw_printw printwvwprintw printwvw_scanw scanwvwscanw scanwwaddchnstr addchstrwaddchstr addchstrwaddch addchwaddnstr addstrwaddstr addstrwattroff attrwattron attrwattrset attrwattr_get attrwattr_off attrwattr_on attrwattr_set attrwbkgdset bkgdwbkgd bkgdwborder borderwchgat attrwclear clearwclrtobot clearwclrtoeol clearwcolor_set attrwcursyncup windowwdelch delchwdeleteln deletelnwechochar addchwerase clearwgetch getchwgetnstr getstrwgetstr getstrwhline borderwinchnstr inchstrwinchstr inchstrwinch inchwinnstr instrwinsch inschwinsdelln deletelnwinsertln deletelnwinsnstr insstrwinsstr insstrwinstr instrwmove movewnoutrefresh refreshwprintw printwwredrawln refreshwrefresh refreshwscanw scanwwscrl scrollwsetscrreg outoptswstandend attrwstandout attrwsyncdown windowwsyncup windowwtimeout inoptswtouchln touchwvline borderWide-character functions from the X/Open standard -- these are onlyavailable when PDCurses is built with PDC_WIDE defined, and theprototypes are only available from curses.h when PDC_WIDE is definedbefore its inclusion in your app:addnwstr addstraddwstr addstradd_wch addchadd_wchnstr addchstradd_wchstr addchstrborder_set borderbox_set borderecho_wchar addcherasewchar termattrgetbkgrnd bkgdgetcchar utilgetn_wstr getstrget_wch getchget_wstr getstrhline_set borderinnwstr instrins_nwstr insstrins_wch inschins_wstr insstrinwstr instrin_wch inchin_wchnstr inchstrin_wchstr inchstrkey_name keynamekillwchar termattrmvaddnwstr addstrmvaddwstr addstrmvadd_wch addchmvadd_wchnstr addchstrmvadd_wchstr addchstrmvgetn_wstr getstrmvget_wch getchmvget_wstr getstrmvhline_set bordermvinnwstr instrmvins_nwstr insstrmvins_wch inschmvins_wstr insstrmvinwstr instrmvwaddnwstr addstrmvwaddwstr addstrmvwadd_wch addchmvwadd_wchnstr addchstrmvwadd_wchstr addchstrmvwgetn_wstr getstrmvwget_wch getchmvwget_wstr getstrmvwhline_set bordermvwinnwstr instrmvwins_nwstr insstrmvwins_wch inschmvwins_wstr insstrmvwin_wch inchmvwin_wchnstr inchstrmvwin_wchstr inchstrmvwinwstr instrmvwvline_set borderpecho_wchar padsetcchar utilslk_wset slkunget_wch getchvline_set borderwaddnwstr addstrwaddwstr addstrwadd_wch addchwadd_wchnstr addchstrwadd_wchstr addchstrwbkgrnd bkgdwbkgrndset bkgdwborder_set borderwecho_wchar addchwgetbkgrnd bkgdwgetn_wstr getstrwget_wch getchwget_wstr getstrwhline_set borderwinnwstr instrwins_nwstr insstrwins_wch inschwins_wstr insstrwinwstr instrwin_wch inchwin_wchnstr inchstrwin_wchstr inchstrwunctrl utilwvline_set borderQuasi-standard functions, from Sys V or BSD curses:getattrs attrgetbegx getyxgetbegy getyxgetmaxx getyxgetmaxy getyxgetparx getyxgetparx getyxtraceoff debugtraceon debugunctrl utilClassic PDCurses mouse functions, based on Sys V:mouse_set mousemouse_on mousemouse_off mouserequest_mouse_pos mousemap_button mousewmouse_position mousegetmouse mousegetbmap mouseFunctions from ncurses:assume_default_colors colorcurses_version initscrhas_key keynameuse_default_colors colorwresize windowmouseinterval mousemousemask mousemouse_trafo mousenc_getmouse mouseungetmouse mousewenclose mousewmouse_trafo mousePDCurses-specific functions -- avoid these in code that's intended to beportable:addrawch addchinsrawch inschis_termresized initscrmvaddrawch addchmvdeleteln deletelnmvinsertln deletelnmvinsrawch inschmvwaddrawch addchmvwdeleteln deletelnmvwinsertln deletelnmvwinsrawch inschraw_output outoptsresize_term initscrresize_window windowslk_wlabel slkwaddrawch addchwinsrawch inschwordchar termattrPDC_debug debugPDC_ungetch getchPDC_set_blink pdcsetscPDC_set_line_color colorPDC_set_title pdcsetscPDC_clearclipboard pdcclipPDC_freeclipboard pdcclipPDC_getclipboard pdcclipPDC_setclipboard pdcclipPDC_get_input_fd pdckbdPDC_get_key_modifiers getchPDC_return_key_modifiers getchPDC_save_key_modifiers getchFunctions specific to the X11 port of PDCurses:Xinitscr initscrXCursesExit -sb_init sbsb_set_horz sbsb_set_vert sbsb_get_horz sbsb_get_vert sbsb_refresh sb--------------------------------------------------------------------------