--- name: "Term::Visual" section: "3pm" platform: "linux" package: "libterm-visual-perl" version: "0.08-2.1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Term::Visual" --- # Term::Visual(3pm) split-terminal user interface ## 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 \ Thank you!