Provided by: libterm-visual-perl_0.08-2.1_all bug

NAME

       Term::Visual - split-terminal user interface

SYNOPSIS

         #!/usr/bin/perl -w
         use strict;

         use Term::Visual;

         my $vt = Term::Visual->new(    Alias => "interface",
                                     Errlevel => 0 );

         $vt->set_palette( mycolor   => "magenta on black",
                           thiscolor => "green on black" );

         my $window_id = $vt->create_window(
               Window_Name  => "foo",

               Status       => { 0 =>
                                  { format => "template for status line 1",
                                    fields => [qw( foo bar )] },
                                 1 =>
                                  { format => "template for status line 2",
                                    fields => [ qw( biz baz ) ] },
                               },

               Buffer_Size  => 1000,
               History_Size => 50,

               Input_Prompt => "[foo] ", # Set the input prompt for the input line.

               Use_Title    => 0, # Don't use a titlebar
               Use_Status   => 0, # Don't use a statusbar

               Title        => "Title of foo"  );

         POE::Session->create
           (inline_states => {
              _start         => \&start_handler,
              got_term_input => \&term_input_handler,
            }
           );

         sub start_handler {
           my $kernel = $_[KERNEL];

           # Tell the terminal to send me input as "got_term_input".
           $kernel->post( interface => send_me_input => "got_term_input" );

           $vt->set_status_field( $window_id, bar => $value );

           $vt->set_input_prompt($window_id, "\$");

           $vt->print( $window_id, "my Window ID is $window_id" );
         }

         sub term_input_handler {
             my ($kernel, $heap, $input, $exception) = @_[KERNEL, HEAP, ARG0, ARG1];

             # Got an exception.  These are interrupt (^C) or quit (^\).
             if (defined $exception) {
               warn "got exception: $exception";
               exit;
             }
             $vt->print($window_id, $input);
         }

         # Only use delete_window if using multiple windows.
         $vt->delete_window( $window_id );

         $vt->shutdown;

DESCRIPTION

       Term::Visual is a "visual" terminal interface for curses applications.  It provides the
       split-screen interface you may have seen in console based IRC and MUD clients.

       Term::Visual uses the POE networking and multitasking framework to support concurrent
       input from network sockets and the console, multiple timers, and more.

PUBLIC METHODS

       Term::Visual->method();

       new
         Create and initialize a new instance of Term::Visual.

           my $vt = Term::Visual->new(
                              Alias => "interface",
                       Common_Input => 1,
                       Tab_Complete => sub { ... },
                           Errlevel => 0 );

         Alias is a session alias for POE.

         Common_Input is an optional flag used
           to globalize History_Position,
                        History_Size,
                        Command_History,
                        Data,
                        Data_Save,
                        Cursor,
                        Cursor_Save,
                        Tab_Complete,
                        Insert,
                        Edit_Position
           in create_window(); Thus all windows created will have common input.

         Tab_Complete is a handler for tab completion.

           Tab_Complete => sub {
             my $left = shift;
             my @return;
             my %complete = (
                 foo => "foobar ",
                 biz => "bizbaz ",
                );
             return $complete{$left};
            }

         Tab_Complete is covered more indepth in the examples directory.

         Errlevel not implemented yet.

         Errlevel sets Term::Visual's error level.

       create_window
           my $window_id = $vt->create_window( ... );

         Set the window's name

           Window_Name => "foo"

         Set the Statusbar's format

           Status => { 0 => # first statusline
                        { format => "\0(st_frames)" .
                                    " [" .
                                    "\0(st_values)" .
                                    "%8.8s" .
                                    "\0(st_frames)" .
                                    "] " .
                                    "\0(st_values)" .
                                    "%s",
                          fields => [qw( time name )] },
                       1 => # second statusline
                        { format => "foo %s bar %s",
                          fields => [qw( foo bar )] },
                     }

         Set the size of the scrollback buffer

           Buffer_Size => 1000

         Set the command history size

           History_Size => 50

         Set the input prompt of the window

           Input_Prompt => "foo"

         Set the title of the window

           Title => "This is the Titlebar"

         Don't use Term::Visual's Titlebar.

           Use_Title => 0

         Don't use Term::Visual's StatusBar.

           Use_Status => 0

         No need to declare Use_Status or Use_Title if you want to use the Statusbar or Titlebar.

       send_me_input
         send_me_input is a handler Term::Visual uses to send the client input from a keyboard
         and mouse.

         create a handler for parsing the input in your POE Session.

           POE::Session->create
             (inline_states => {
                _start         => \&start_handler,
                got_term_input => \&term_input_handler,
              }
             );

         POE's _start handler is a good place to tell Term::Visual how to send you input.

           sub start_handler {
             my $kernel = $_[KERNEL];

             # Tell the terminal to send me input as "got_term_input".
             $kernel->post( interface => send_me_input => "got_term_input" );
             ...
           }

         Now create your "term_input_handler" to parse input.  In this case we simply check for
         exceptions and print the input to the screen.

           sub term_input_handler {
             my ($kernel, $heap, $input, $exception) = @_[KERNEL, HEAP, ARG0, ARG1];

             # Got an exception.  These are interrupt (^C) or quit (^\).
             if (defined $exception) {
               warn "got exception: $exception";
               exit;
             }
             $vt->print($window_id, $input);
           }

       print
         Prints lines of text to the main screen of a window

           $vt->print( $window_id, "this is a string" );

           my @array = qw(foo bar biz baz);
           $vt->print( $window_id, @array );

       current_window
           my $current_window = $vt->current_window;

           $vt->print( $current_window, "current window is $current_window" );

       get_window_name
           my $window_name = $vt->get_window_name( $window_id );

       get_window_id
           my $window_id = $vt->get_window_id( $window_name );

       delete_window
           $vt->delete_window($window_id);

         or

           $vt->delete_window(@window_ids);

       validate_window
           my $validity = $vt->validate_window( $window_id );

         or

           my $validity = $vt->validate_window( $window_name );

           if ($validity) { do stuff };

       get_palette
         Return color palette or a specific colorname's description.

           my %palette = $vt->get_palette();

           my $color_desc = $vt->get_palette($colorname);

           my ($foo, $bar) = $vt->get_palette($biz, $baz);

       set_palette
         Set the color palette or specific colorname's value.

           $vt->set_palette( color_name => "color on color" );

           $vt->set_palette( color_name => "color on color",
                             another    => "color on color" );

           NOTE: (ncolor, st_values, st_frames, stderr_text, stderr_bullet, statcolor)
                  are set and used by Term::Visual internally.
                  It is safe to redifine there values.

       color codes
         Once your color definitions are set in the palette you must insert color codes to your
         output.  These are formatted as follows: "\0(ncolor)"

         So if you wanted to print something with a color you could simply use:

           $vt->print( $window_id, "\0(color_name)My this is a wonderful color." );

       set_title
           $vt->set_title( $window_id, "This is the new Title" );

       get_title
           my $title = $vt->get_title( $window_id );

       change_window
         Switch between windows

           $vt->change_window( $window_id );

           $vt->change_window( 0 );

           ...

           $vt->change_window( 1 );

       set_status_format
           $vt->set_status_format( $window_id,
                     0 => { format => "template for status line 1",
                            fields  => [ qw( foo bar ) ] },
                     1 => { format => "template for status line 2",
                            fields  => [ qw( biz baz ) ] }, );

       set_status_field
           $vt->set_status_field( $window_id, field => "value" );

           $vt->set_status_field( $window_id, foo => "bar", biz => "baz" );

       set_input_prompt
           $vt->set_input_prompt($window_id, "\$");

           $vt->set_input_prompt($window_id, "[foo]");

       columnize columnize takes a list of text and formats it into a columnized table.
           columnize is used internally, but might be of use
           externally as well.

           Arguments given to columnize must be a hash.
           key 'Items' must be an array reference.
           The default value for Maxwidth may change to $COLS.

           my $table = $vt->columnize(
              Items => \@list,
              Padding => 2, # default value and optional
              MaxColumns => 10, # default value and optional
              MaxWidth => 80 # default value and optional
           );

       bind
           bind is used for key bindings.
           our %Bindings = (
               Up   => 'history',
               Down => 'history',
                ...
           );

           $vt->bind(%Bindings);

           sub handler_history {
             my ($kernel, $heap, $key, $win) = @_[KERNEL, HEAP, ARG0, ARG2];
             if ($key eq 'KEY_UP') {
               $vt->command_history($win, 1);
             }
             else {
               $vt->command_history($win, 2);
             }
           }

           POE::Session->create(
               inline_states => {
                   _start => \&handler_start,
                   _stop  => \&handler_stop,
                   history => \&handler_history,
                   ...
               }
           );

       unbind unbind a key
           $vt->unbind('Up', 'Down');
           $vt->unbind(keys %Bindings);

       debug write to the debug file
           $vt->debug("message");

           Debugging must be turned on before using this.

           change sub DEBUG () { 0 } to 1 or
           add this to your program:
           sub Term::Visual::DEBUG () { 1 }
           use Term::Visual;

       shutdown shutdown Term::Visual
           $vt->shutdown();

Internal Keystrokes

       Ctrl A or KEY_HOME
         Move to BOL.

       KEY_LEFT
         Back one character.

       Alt P or Esc KEY_LEFT
         Switch Windows decrementaly.

       Alt N or Esc KEY_RIGHT
         Switch Windows incrementaly.

       Alt K or KEY_END
         Not implemented yet.

         Kill a Window.

       Ctrl \
         Kill Term::Visual.

       Ctrl D or KEY_DC
         Delete a character.

       Ctrl E or KEY_LL
         Move to EOL.

       Ctrl F or KEY_RIGHT
         Forward a character.

       Ctrl H or KEY_BACKSPACE
         Backward delete character.

       Ctrl J or Ctrl M 'Return'
         Accept a line.

       Ctrl K
         Kill to EOL.

       Ctrl L or KEY_RESIZE
         Refresh screen.

       Ctrl N
         Next in history.

       Ctrl P
         Previous in history.

       Ctrl Q
         Display input status.

       Ctrl T
         Transpose characters.

       Ctrl U
         Discard line.

       Ctrl W
         Word rubout.

       Esc C
         Capitalize word to right of cursor.

       Esc U
         Uppercase WORD.

       Esc L
         Lowercase word.

       Esc F
         Forward one word.

       Esc B
         Backward one word.

       Esc D
         Delete a word forward.

       Esc T
         Transpose words.

       KEY_IC 'Insert'
         Toggle Insert mode.

       KEY_SELECT 'Home'
         If window is scrolled up, page all the way down.

       KEY_PPAGE 'Page Down'
         Scroll down a page.

       KEY_NPAGE 'Page Up'
         Scroll up a page.

       KEY_UP
         Scroll up a line.

       KEY_DOWN
         Scroll down a line.

Author

       Charles Ayres
         Except where otherwise noted, Term::Visual is Copyright 2002-2007 Charles Ayres. All
         rights reserved.  Term::Visual is free software; you may redistribute it and/or modify
         it under the same terms as Perl itself.

         Questions and Comments can be sent to lunartear@cpan.org

         Please send bug reports and wishlist items to:
          http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Term-Visual

Acknowledgments

       Rocco Caputo
         A Big thanks to Rocco Caputo.

         Rocco has contributed to the development of Term::Visual In many ways.

         Rocco Caputo <troc+visterm@pobox.com>

       Thank you!