.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Visual 3pm"
.TH Visual 3pm "2007-10-18" "perl v5.12.4" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Term::Visual \- split\-terminal user interface
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  #!/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\*(Aqt use a titlebar 
\&        Use_Status   => 0, # Don\*(Aqt use a statusbar
\&
\&        Title        => "Title of foo"  );
\&
\&  POE::Session\->create
\&    (inline_states => {
\&       _start         => \e&start_handler,
\&       got_term_input => \e&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, "\e$");
\&
\&    $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 (^\e).
\&      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;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Term::Visual is a \*(L"visual\*(R" terminal interface for curses applications.
It provides the split-screen interface you may have seen in console
based \s-1IRC\s0 and \s-1MUD\s0 clients.
.PP
Term::Visual uses the \s-1POE\s0 networking and multitasking framework to support
concurrent input from network sockets and the console, multiple
timers, and more.
.SH "PUBLIC METHODS"
.IX Header "PUBLIC METHODS"
Term::Visual\->\fImethod()\fR;
.IP "new" 2
.IX Item "new"
Create and initialize a new instance of Term::Visual.
.Sp
.Vb 5
\&  my $vt = Term::Visual\->new( 
\&                     Alias => "interface",
\&              Common_Input => 1,
\&              Tab_Complete => sub { ... },                 
\&                  Errlevel => 0 );
.Ve
.Sp
Alias is a session alias for \s-1POE\s0.
.Sp
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 \fIcreate_window()\fR;
Thus all windows created will have common input.
.Sp
Tab_Complete is a handler for tab completion.
.Sp
.Vb 9
\&  Tab_Complete => sub {
\&    my $left = shift;
\&    my @return;
\&    my %complete = (
\&        foo => "foobar ",
\&        biz => "bizbaz ",
\&       );
\&    return $complete{$left};
\&   }
.Ve
.Sp
Tab_Complete is covered more indepth in the examples directory.
.Sp
Errlevel not implemented yet.
.Sp
Errlevel sets Term::Visual's error level.
.IP "create_window" 2
.IX Item "create_window"
.Vb 1
\&  my $window_id = $vt\->create_window( ... );
.Ve
.Sp
Set the window's name
.Sp
.Vb 1
\&  Window_Name => "foo"
.Ve
.Sp
Set the Statusbar's format
.Sp
.Vb 10
\&  Status => { 0 => # first statusline
\&               { format => "\e0(st_frames)" .
\&                           " [" .
\&                           "\e0(st_values)" .
\&                           "%8.8s" .
\&                           "\e0(st_frames)" .
\&                           "] " .
\&                           "\e0(st_values)" .
\&                           "%s",
\&                 fields => [qw( time name )] },
\&              1 => # second statusline
\&               { format => "foo %s bar %s",
\&                 fields => [qw( foo bar )] },
\&            }
.Ve
.Sp
Set the size of the scrollback buffer
.Sp
.Vb 1
\&  Buffer_Size => 1000
.Ve
.Sp
Set the command history size
.Sp
.Vb 1
\&  History_Size => 50
.Ve
.Sp
Set the input prompt of the window
.Sp
.Vb 1
\&  Input_Prompt => "foo"
.Ve
.Sp
Set the title of the window
.Sp
.Vb 1
\&  Title => "This is the Titlebar"
.Ve
.Sp
Don't use Term::Visual's Titlebar.
.Sp
.Vb 1
\&  Use_Title => 0
.Ve
.Sp
Don't use Term::Visual's StatusBar.
.Sp
.Vb 1
\&  Use_Status => 0
.Ve
.Sp
No need to declare Use_Status or Use_Title if you want to use
the Statusbar or Titlebar.
.IP "send_me_input" 2
.IX Item "send_me_input"
send_me_input is a handler Term::Visual uses to send the client input
from a keyboard and mouse.
.Sp
create a handler for parsing the input in your \s-1POE\s0 Session.
.Sp
.Vb 6
\&  POE::Session\->create
\&    (inline_states => {
\&       _start         => \e&start_handler,
\&       got_term_input => \e&term_input_handler,
\&     }
\&    );
.Ve
.Sp
\&\s-1POE\s0's _start handler is a good place to tell Term::Visual how to send you input.
.Sp
.Vb 2
\&  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" );
\&    ...
\&  }
.Ve
.Sp
Now create your \*(L"term_input_handler\*(R" to parse input.
In this case we simply check for exceptions and print 
the input to the screen.
.Sp
.Vb 2
\&  sub term_input_handler {
\&    my ($kernel, $heap, $input, $exception) = @_[KERNEL, HEAP, ARG0, ARG1];
\&
\&    # Got an exception.  These are interrupt (^C) or quit (^\e).
\&    if (defined $exception) {
\&      warn "got exception: $exception";
\&      exit;
\&    }
\&    $vt\->print($window_id, $input);
\&  }
.Ve
.IP "print" 2
.IX Item "print"
Prints lines of text to the main screen of a window
.Sp
.Vb 1
\&  $vt\->print( $window_id, "this is a string" );
\&
\&  my @array = qw(foo bar biz baz);
\&  $vt\->print( $window_id, @array );
.Ve
.IP "current_window" 2
.IX Item "current_window"
.Vb 1
\&  my $current_window = $vt\->current_window;
\&
\&  $vt\->print( $current_window, "current window is $current_window" );
.Ve
.IP "get_window_name" 2
.IX Item "get_window_name"
.Vb 1
\&  my $window_name = $vt\->get_window_name( $window_id );
.Ve
.IP "get_window_id" 2
.IX Item "get_window_id"
.Vb 1
\&  my $window_id = $vt\->get_window_id( $window_name );
.Ve
.IP "delete_window" 2
.IX Item "delete_window"
.Vb 1
\&  $vt\->delete_window($window_id);
.Ve
.Sp
or
.Sp
.Vb 1
\&  $vt\->delete_window(@window_ids);
.Ve
.IP "validate_window" 2
.IX Item "validate_window"
.Vb 1
\&  my $validity = $vt\->validate_window( $window_id );
.Ve
.Sp
or
.Sp
.Vb 1
\&  my $validity = $vt\->validate_window( $window_name );
\&
\&  if ($validity) { do stuff };
.Ve
.IP "get_palette" 2
.IX Item "get_palette"
Return color palette or a specific colorname's description.
.Sp
.Vb 1
\&  my %palette = $vt\->get_palette();
\&
\&  my $color_desc = $vt\->get_palette($colorname);
\&
\&  my ($foo, $bar) = $vt\->get_palette($biz, $baz);
.Ve
.IP "set_palette" 2
.IX Item "set_palette"
Set the color palette or specific colorname's value.
.Sp
.Vb 1
\&  $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.
.Ve
.IP "color codes" 2
.IX Item "color codes"
Once your color definitions are set in the palette you must insert
color codes to your output.
These are formatted as follows: \*(L"\e0(ncolor)\*(R"
.Sp
So if you wanted to print something with a color you could simply use:
.Sp
.Vb 1
\&  $vt\->print( $window_id, "\e0(color_name)My this is a wonderful color." );
.Ve
.IP "set_title" 2
.IX Item "set_title"
.Vb 1
\&  $vt\->set_title( $window_id, "This is the new Title" );
.Ve
.IP "get_title" 2
.IX Item "get_title"
.Vb 1
\&  my $title = $vt\->get_title( $window_id );
.Ve
.IP "change_window" 2
.IX Item "change_window"
Switch between windows
.Sp
.Vb 1
\&  $vt\->change_window( $window_id );
\&
\&  $vt\->change_window( 0 );
\&
\&  ...
\&
\&  $vt\->change_window( 1 );
.Ve
.IP "set_status_format" 2
.IX Item "set_status_format"
.Vb 5
\&  $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 ) ] }, );
.Ve
.IP "set_status_field" 2
.IX Item "set_status_field"
.Vb 1
\&  $vt\->set_status_field( $window_id, field => "value" );
\&
\&  $vt\->set_status_field( $window_id, foo => "bar", biz => "baz" );
.Ve
.IP "set_input_prompt" 2
.IX Item "set_input_prompt"
.Vb 1
\&  $vt\->set_input_prompt($window_id, "\e$");
\&
\&  $vt\->set_input_prompt($window_id, "[foo]");
.Ve
.IP "columnize columnize takes a list of text and formats it into a columnized table." 2
.IX Item "columnize columnize takes a list of text and formats it into a columnized table."
.Vb 2
\&  columnize is used internally, but might be of use 
\&  externally as well.
\&
\&  Arguments given to columnize must be a hash.
\&  key \*(AqItems\*(Aq must be an array reference.
\&  The default value for Maxwidth may change to $COLS.
\&
\&  my $table = $vt\->columnize( 
\&     Items => \e@list, 
\&     Padding => 2, # default value and optional
\&     MaxColumns => 10, # default value and optional
\&     MaxWidth => 80 # default value and optional
\&  );
.Ve
.IP "bind" 2
.IX Item "bind"
.Vb 6
\&  bind is used for key bindings.
\&  our %Bindings = (
\&      Up   => \*(Aqhistory\*(Aq,
\&      Down => \*(Aqhistory\*(Aq,
\&       ...
\&  );
\&
\&  $vt\->bind(%Bindings);
\&
\&  sub handler_history {
\&    my ($kernel, $heap, $key, $win) = @_[KERNEL, HEAP, ARG0, ARG2];
\&    if ($key eq \*(AqKEY_UP\*(Aq) {
\&      $vt\->command_history($win, 1);
\&    }
\&    else {
\&      $vt\->command_history($win, 2);
\&    }
\&  }
\&
\&  POE::Session\->create(
\&      inline_states => {
\&          _start => \e&handler_start,
\&          _stop  => \e&handler_stop,
\&          history => \e&handler_history,
\&          ...
\&      }
\&  );
.Ve
.IP "unbind unbind a key" 2
.IX Item "unbind unbind a key"
.Vb 2
\&  $vt\->unbind(\*(AqUp\*(Aq, \*(AqDown\*(Aq);
\&  $vt\->unbind(keys %Bindings);
.Ve
.IP "debug write to the debug file" 2
.IX Item "debug write to the debug file"
.Vb 1
\&  $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;
.Ve
.IP "shutdown shutdown Term::Visual" 2
.IX Item "shutdown shutdown Term::Visual"
.Vb 1
\&  $vt\->shutdown();
.Ve
.SH "Internal Keystrokes"
.IX Header "Internal Keystrokes"
.IP "Ctrl A or \s-1KEY_HOME\s0" 2
.IX Item "Ctrl A or KEY_HOME"
Move to \s-1BOL\s0.
.IP "\s-1KEY_LEFT\s0" 2
.IX Item "KEY_LEFT"
Back one character.
.IP "Alt P or Esc \s-1KEY_LEFT\s0" 2
.IX Item "Alt P or Esc KEY_LEFT"
Switch Windows decrementaly.
.IP "Alt N or Esc \s-1KEY_RIGHT\s0" 2
.IX Item "Alt N or Esc KEY_RIGHT"
Switch Windows incrementaly.
.IP "Alt K or \s-1KEY_END\s0" 2
.IX Item "Alt K or KEY_END"
Not implemented yet.
.Sp
Kill a Window.
.IP "Ctrl \e" 2
.IX Item "Ctrl "
Kill Term::Visual.
.IP "Ctrl D or \s-1KEY_DC\s0" 2
.IX Item "Ctrl D or KEY_DC"
Delete a character.
.IP "Ctrl E or \s-1KEY_LL\s0" 2
.IX Item "Ctrl E or KEY_LL"
Move to \s-1EOL\s0.
.IP "Ctrl F or \s-1KEY_RIGHT\s0" 2
.IX Item "Ctrl F or KEY_RIGHT"
Forward a character.
.IP "Ctrl H or \s-1KEY_BACKSPACE\s0" 2
.IX Item "Ctrl H or KEY_BACKSPACE"
Backward delete character.
.IP "Ctrl J or Ctrl M 'Return'" 2
.IX Item "Ctrl J or Ctrl M 'Return'"
Accept a line.
.IP "Ctrl K" 2
.IX Item "Ctrl K"
Kill to \s-1EOL\s0.
.IP "Ctrl L or \s-1KEY_RESIZE\s0" 2
.IX Item "Ctrl L or KEY_RESIZE"
Refresh screen.
.IP "Ctrl N" 2
.IX Item "Ctrl N"
Next in history.
.IP "Ctrl P" 2
.IX Item "Ctrl P"
Previous in history.
.IP "Ctrl Q" 2
.IX Item "Ctrl Q"
Display input status.
.IP "Ctrl T" 2
.IX Item "Ctrl T"
Transpose characters.
.IP "Ctrl U" 2
.IX Item "Ctrl U"
Discard line.
.IP "Ctrl W" 2
.IX Item "Ctrl W"
Word rubout.
.IP "Esc C" 2
.IX Item "Esc C"
Capitalize word to right of cursor.
.IP "Esc U" 2
.IX Item "Esc U"
Uppercase \s-1WORD\s0.
.IP "Esc L" 2
.IX Item "Esc L"
Lowercase word.
.IP "Esc F" 2
.IX Item "Esc F"
Forward one word.
.IP "Esc B" 2
.IX Item "Esc B"
Backward one word.
.IP "Esc D" 2
.IX Item "Esc D"
Delete a word forward.
.IP "Esc T" 2
.IX Item "Esc T"
Transpose words.
.IP "\s-1KEY_IC\s0 'Insert'" 2
.IX Item "KEY_IC 'Insert'"
Toggle Insert mode.
.IP "\s-1KEY_SELECT\s0 'Home'" 2
.IX Item "KEY_SELECT 'Home'"
If window is scrolled up, page all the way down.
.IP "\s-1KEY_PPAGE\s0 'Page Down'" 2
.IX Item "KEY_PPAGE 'Page Down'"
Scroll down a page.
.IP "\s-1KEY_NPAGE\s0 'Page Up'" 2
.IX Item "KEY_NPAGE 'Page Up'"
Scroll up a page.
.IP "\s-1KEY_UP\s0" 2
.IX Item "KEY_UP"
Scroll up a line.
.IP "\s-1KEY_DOWN\s0" 2
.IX Item "KEY_DOWN"
Scroll down a line.
.SH "Author"
.IX Header "Author"
.IP "Charles Ayres" 2
.IX Item "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.
.Sp
Questions and Comments can be sent to lunartear@cpan.org
.Sp
Please send bug reports and wishlist items to:
 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Term\-Visual
.SH "Acknowledgments"
.IX Header "Acknowledgments"
.IP "Rocco Caputo" 2
.IX Item "Rocco Caputo"
A Big thanks to Rocco Caputo.
.Sp
Rocco has contributed to the development
of Term::Visual In many ways.
.Sp
Rocco Caputo <troc+visterm@pobox.com>
.PP
Thank you!