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); }
-
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!