Subversion Repositories openrisc

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

--------------------------------------------------------------------------