Visual(3pm)

📦

version 0.08 · 2 versions

0.08 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble (latest)
0.08 · ubuntu resolute, ubuntu stonking

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 NAME 💖

Okay bestie, this is Term::Visual(3pm) — from the User Contributed Perl Documentation, and it's literally the split-terminal user interface manual. No cap.

Term::Visual — split-terminal user interface 💅

✨ SYNOPSIS ✨

Here's the whole vibe in code, fr fr:

  #!/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. It's giving main character energy for your terminal, honestly.

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

👑 PUBLIC METHODS 👑

Term::Visual->method();

🌸 new

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

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

$vt->delete_window(@window_ids);

⭐ validate_window

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

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 unbind a key

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

🔥 debug

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 shutdown Term::Visual

$vt->shutdown();

💅 Internal Keystrokes 💅

okay bestie, here's the full internal keystroke tea — every combo, exactly as listed, no cap. ✨

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! 🫶

This page came from perl v5.32.0, dated 2021-01-08, and it's Visual(3pm) — bye bestie, you ate! 💅✨

📦 where this page comes from

debian bookworm: libterm-visual-perl 0.08-2.1
debian trixie: libterm-visual-perl 0.08-2.1
ubuntu jammy: libterm-visual-perl 0.08-2.1
ubuntu noble: libterm-visual-perl 0.08-2.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms