Curses

Curses(3pm)           User Contributed Perl Documentation          Curses(3pm)



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 the
       section on 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 the section on 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 the section on
       Supported Functions below and the section on 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 the section on 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 the BUGS
       manpage 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 the 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
       C<$Curses::OldCurses> must be set to a non-zero value before using the
       C<Curses> package.  See L<"Perl 4.X cursperl Compatibility"> for an
       example of this.


       Supported Variables
           LINES          COLS      stdscr[*] curscr[*]   =head2 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      =head2 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 the section on Perl 4.X cursperl Compatibility for
       more information.

3rd Berkeley Distribution    perl 5.004, patch 04                  Curses(3pm)