++ed by:
LEONT IOANR JWB SCHWIGON PATCH

139 PAUSE users
117 non-PAUSE users.

William J. Middleton

NAME

Curses - terminal screen handling and optimization

SYNOPSIS

    use Curses;

    initscr;
    ...
    endwin;

DESCRIPTION

Curses is the interface between Perl and your system's curses(3) library. For descriptions on the usage of a given function, variable, or constant, consult your system's documentation, as such information invariably varies (:-) between different curses(3) libraries and operating systems. This document describes the interface itself, and assumes that you already know how your system's curses(3) library works.

Unified Functions

Many curses(3) functions have variants starting with the prefixes w-, mv-, and/or wmv-. These variants differ only in the explicit addition of a window, or by the addition of two coordinates that are used to move the cursor first. For example, addch() has three other variants: waddch(), mvaddch(), and mvwaddch(). The variants aren't very interesting; in fact, we could roll all of the variants into original function by allowing a variable number of arguments and analyzing the argument list for which variant the user wanted to call.

Unfortunately, curses(3) predates varargs(3), so in C we were stuck with all the variants. However, Curses is a Perl interface, so we are free to "unify" these variants into one function. The section "Supported Functions" below lists all curses(3) function supported by Curses, along with a column listing if it is unified. If so, it takes a varying number of arguments as follows:

    function( [win], [y, x], args );

    win is an optional window argument, defaulting to stdscr if not specified.

    y, x is an optional coordinate pair used to move the cursor, defaulting to no move if not specified.

    args are the required arguments of the function. These are the arguments you would specify if you were just calling the base function and not any of the variants.

This makes the variants obsolete, since their functionality has been merged into a single function, so Curses does not define them by default. You can still get them if you want, by setting the variable $Curses::OldCurses to a non-zero value before using the Curses package. See "Perl 4.X cursperl Compatibility" for an example of this.

Objects

Objects are supported. Example:

    $win = new Curses;
    $win->addstr(10, 10, 'foo');
    $win->refresh;
    ...

Any function that has been marked as unified (see "Supported Functions" below and "Unified Functions" above) can be called as a method for a Curses object.

Do not use initscr() if using objects, as the first call to get a new Curses will do it for you.

COMPATIBILITY

Perl 4.X cursperl Compatibility

Curses has been written to take advantage of the new features of Perl. I felt it better to provide an improved curses programming environment rather than to be 100% compatible. However, many old curseperl applications will probably still work by starting the script with:

    BEGIN { $Curses::OldCurses = 1; }
    use Curses;

Any old application that still does not work should print an understandable error message explaining the problem.

Some functions and variables are not supported by Curses, even with the BEGIN line. They are listed under "curses(3) items not supported by Curses".

The variables $stdscr and $curscr are also available as functions stdscr and curscr. This is because of a Perl bug. See the BUGS section for details.

Incompatibilities with previous versions of Curses

In previous versions of this software, some Perl functions took a different set of parameters than their C counterparts. This is no longer true. You should now use getstr($str) and getyx($y, $x) instead of $str = getstr() and ($y, $x) = getyx().

Incompatibilities with other Perl programs

    menu.pl, v3.0 and v3.1
        There were various interaction problems between these two
        releases and Curses.  Please upgrade to the latest version
        (v3.3 as of 3/16/96).

DIAGNOSTICS

  • Curses function '%s' called with too %s arguments at ...

    You have called a Curses function with a wrong number of arguments.

  • argument %d to Curses function '%s' is not a Curses window at ... =item * argument is not a Curses window at ...

    The window argument you gave to the function wasn't really a window.

    This probably means that you didn't give the right arguments to a unified function. See the DESCRIPTION section on "Unified Functions" for more information.

  • Curses function '%s' is not defined by your vendor at ...

    You have a Curses function in your code that your system's curses(3) library doesn't define.

  • Curses constant '%s' is not defined by your vendor at ...

    You have a Curses constant in your code that your system's curses(3) library doesn't define.

  • Curses does not support the curses function '%s', used at ...

    You have a curses(3) function in your code that the Curses module doesn't support.

  • Curses does not support the curses variable '%s', used at ...

    You have a curses(3) variable in your code that the Curses module doesn't support.

  • Curses does not support the curses constant '%s', used at ...

    You have a bareword in your code that is trying to be interpreted as a Curses constant, but Curses doesn't know anything about it.

  • Curses::Vars::FETCH called with bad index at ... =item * Curses::Vars::STORE called with bad index at ...

    You've been playing with the tie interface to the Curses variables. Don't do that. :-)

  • Anything else

    Check out the perldiag man page to see if the error is in there.

BUGS

If you use the variables $stdscr and $curscr instead of their functional counterparts (stdscr and curscr), you might run into a bug in Perl where the "magic" isn't called early enough. This is manifested by the Curses package telling you $stdscr isn't a window. One workaround is to put a line like $stdscr = $stdscr near the front of your program.

Probably many more.

AUTHOR

William Setzer <William_Setzer@ncsu.edu>

SYNOPSIS OF PERL CURSES SUPPORT

Supported Functions

        Supported     Unified?          Supported via $OldCurses[*]
        ---------     --------          ------------------------
        addch           Yes             waddch mvaddch mvwaddch
        addchnstr       Yes             waddchnstr mvaddchnstr mvwaddchnstr
        addchstr        Yes             waddchstr mvaddchstr mvwaddchstr
        addnstr         Yes             waddnstr mvaddnstr mvwaddnstr
        addstr          Yes             waddstr mvaddstr mvwaddstr
        attroff         Yes             wattroff
        attron          Yes             wattron
        attrset         Yes             wattrset
        baudrate        No
        beep            No
        bkgd            Yes             wbkgd
        bkgdset         Yes             wbkgdset
        border          Yes             wborder
        box             Yes
        can_change_color No
        cbreak          No
        clear           Yes             wclear
        clearok         Yes
        clrtobot        Yes             wclrtobot
        clrtoeol        Yes             wclrtoeol
        color_content   No
        COLOR_PAIR      No
        copywin         No
        delch           Yes             wdelch mvdelch mvwdelch
        deleteln        Yes             wdeleteln
        delwin          Yes
        derwin          Yes
        doupdate        No
        echo            No
        echochar        Yes             wechochar
        endwin          No
        erase           Yes             werase
        erasechar       No
        flash           No
        flushinp        No
        flusok          Yes
        getattrs        Yes
        getbegyx        Yes
        getbkgd         Yes
        getcap          No
        getch           Yes             wgetch mvgetch mvwgetch
        getmaxyx        Yes
        getnstr         Yes             wgetnstr mvgetnstr mvwgetnstr
        getparyx        Yes
        getstr          Yes             wgetstr mvgetstr mvwgetstr
        gettmode        No
        getyx           Yes
        halfdelay       No
        has_colors      No
        has_ic          No
        has_il          No
        hline           Yes             whline
        idcok           Yes
        idlok           Yes
        immedok         Yes
        inch            Yes             winch mvinch mvwinch
        inchnstr        Yes             winchnstr mvinchnstr mvwinchnstr
        inchstr         Yes             winchstr mvinchstr mvwinchstr
        init_color      No
        init_pair       No
        initscr         No
        innstr          Yes             winnstr mvinnstr mvwinnstr
        insch           Yes             winsch mvinsch mvwinsch
        insdelln        Yes             winsdelln
        insertln        Yes             winsertln
        insnstr         Yes             winsnstr mvinsnstr mvwinsnstr
        insstr          Yes             winsstr mvinsstr mvwinsstr
        instr           Yes             winstr mvinstr mvwinstr
        intrflush       Yes
        is_linetouched  Yes
        is_wintouched   Yes
        isendwin        No
        keyname         No
        keypad          Yes
        killchar        No
        leaveok         Yes
        longname        No
        meta            Yes
        move            Yes             wmove
        mvcur           No
        mvwin           Yes
        newpad          No
        newwin          No
        nl              No
        nocbreak        No
        nodelay         Yes
        noecho          No
        nonl            No
        noqiflush       No
        noraw           No
        notimeout       Yes
        noutrefresh     Yes             wnoutrefresh
        overlay         No
        overwrite       No
        pair_content    No
        PAIR_NUMBER     No
        pechochar       No
        pnoutrefresh    No
        prefresh        No
        qiflush         No
        raw             No
        refresh         Yes             wrefresh
        resetty         No
        savetty         No
        scrl            Yes             wscrl
        scroll          Yes
        scrollok        Yes
        setscrreg       Yes             wsetscrreg
        setterm         No
        slk_clear       No
        slk_init        No
        slk_label       No
        slk_noutrefresh No
        slk_refresh     No
        slk_restore     No
        slk_set         No
        slk_touch       No
        standend        Yes             wstandend
        standout        Yes             wstandout
        start_color     No
        subpad          No
        subwin          Yes
        syncok          Yes
        timeout         Yes             wtimeout
        touchline       Yes
        touchln         Yes             wtouchln
        touchoverlap    No
        touchwin        Yes
        typeahead       No
        unctrl          No
        ungetch         No
        vline           Yes             wvline
        

[*] To use any functions in this column, the variable $Curses::OldCurses must be set to a non-zero value before using the Curses package. See "Perl 4.X cursperl Compatibility" for an example of this.

Supported Variables

        LINES           COLS            stdscr[*]       curscr[*]
        

Supported Constants

        OK              ERR
        
        ACS_BLOCK       ACS_BOARD       ACS_BTEE        ACS_BULLET
        ACS_CKBOARD     ACS_DARROW      ACS_DEGREE      ACS_DIAMOND
        ACS_HLINE       ACS_LANTERN     ACS_LARROW      ACS_LLCORNER
        ACS_LRCORNER    ACS_LTEE        ACS_PLMINUS     ACS_PLUS
        ACS_RARROW      ACS_RTEE        ACS_S1          ACS_S9
        ACS_TTEE        ACS_UARROW      ACS_ULCORNER    ACS_URCORNER
        ACS_VLINE
        
        A_ALTCHARSET    A_ATTRIBUTES    A_BLINK         A_BOLD
        A_CHARTEXT      A_COLOR         A_DIM           A_INVIS
        A_NORMAL        A_PROTECT       A_REVERSE       A_STANDOUT
        A_UNDERLINE
        
        COLOR_BLACK     COLOR_BLUE      COLOR_CYAN      COLOR_GREEN
        COLOR_MAGENTA   COLOR_RED       COLOR_WHITE     COLOR_YELLOW
        
        KEY_A1          KEY_A3          KEY_B2          KEY_BACKSPACE
        KEY_BEG         KEY_BREAK       KEY_BTAB        KEY_C1
        KEY_C3          KEY_CANCEL      KEY_CATAB       KEY_CLEAR
        KEY_CLOSE       KEY_COMMAND     KEY_COPY        KEY_CREATE
        KEY_CTAB        KEY_DC          KEY_DL          KEY_DOWN
        KEY_EIC         KEY_END         KEY_ENTER       KEY_EOL
        KEY_EOS         KEY_EXIT        KEY_F0          KEY_FIND
        KEY_HELP        KEY_HOME        KEY_IC          KEY_IL
        KEY_LEFT        KEY_LL          KEY_MARK        KEY_MAX
        KEY_MESSAGE     KEY_MIN         KEY_MOVE        KEY_NEXT
        KEY_NPAGE       KEY_OPEN        KEY_OPTIONS     KEY_PPAGE
        KEY_PREVIOUS    KEY_PRINT       KEY_REDO        KEY_REFERENCE
        KEY_REFRESH     KEY_REPLACE     KEY_RESET       KEY_RESTART
        KEY_RESUME      KEY_RIGHT       KEY_SAVE        KEY_SBEG
        KEY_SCANCEL     KEY_SCOMMAND    KEY_SCOPY       KEY_SCREATE
        KEY_SDC         KEY_SDL         KEY_SELECT      KEY_SEND
        KEY_SEOL        KEY_SEXIT       KEY_SF          KEY_SFIND
        KEY_SHELP       KEY_SHOME       KEY_SIC         KEY_SLEFT
        KEY_SMESSAGE    KEY_SMOVE       KEY_SNEXT       KEY_SOPTIONS
        KEY_SPREVIOUS   KEY_SPRINT      KEY_SR          KEY_SREDO
        KEY_SREPLACE    KEY_SRESET      KEY_SRIGHT      KEY_SRSUME
        KEY_SSAVE       KEY_SSUSPEND    KEY_STAB        KEY_SUNDO
        KEY_SUSPEND     KEY_UNDO        KEY_UP
        

curses(3) items not supported by Curses

        Functions
        ---------
        tstp printw wprintw mvprintw mvwprintw scanw wscanw mvscanw mvwscanw
        _putchar fullname
        
        Variables
        ---------
        ttytype Def_term My_term
 

[*] stdscr and curscr are also available via the Perl functions stdscr and curscr. See "Perl 4.X cursperl Compatibility" for more information.