/ 
Term-Visual-0.05
River stage one • 1 direct dependent • 1 total dependent
/ Term::Visual

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,

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

       Title        => "Title of foo"  );
                   
 $vt->set_status_field( $window_id, bar => $value );

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

 $vt->shutdown; # not implemented yet.

 for now use delete_window

 $vt->delete_window( $window_id );

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 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.

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.
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" );
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, 2003, 2004 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+visterm@ambientheory.com

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!