/ 
TUI-Vision-2.000_002
/ TUI::TextView::Terminal

NAME

TUI::TextView::Terminal - scrollable terminal-style text output view

HIERARCHY

TObject
  TView
    TScroller
      TTextDevice
        TTerminal

SYNOPSIS

use TUI::Objects;
use TUI::Views;
use TUI::TextView;

my $bounds = TRect->new( ax => 0, ay => 0, bx => 60, by => 20 );
my $hBar   = TScrollBar->new(
  bounds => TRect->new( ax => 0, ay => 19, bx => 59, by => 20 )
);
my $vBar   = TScrollBar->new(
  bounds => TRect->new( ax => 59, ay => 0, bx => 60, by => 19 )
);

my $term = TTerminal->new(
  bounds     => $bounds,
  hScrollBar => $hBar,
  vScrollBar => $vBar,
  bufSize    => 4096,
);

tie *TERM, TTerminal => (
  bounds     => $bounds,
  hScrollBar => $hBar,
  vScrollBar => $vBar,
  bufSize    => 4096,
);

print TERM "connected to remote host\n";
syswrite TERM, "login successful\n";
close TERM;

DESCRIPTION

TTerminal implements a simple, scrollable, write-only text view that behaves like a terminal output window. Text written to the terminal is stored in an internal circular buffer and displayed in a scrollable view with optional horizontal and vertical scroll bars.

The terminal buffer automatically wraps around when it reaches its configured size, allowing older data to be discarded as new output is appended. Line boundaries are detected using line feed characters, which makes the terminal suitable for log output, console-style views, and similar streaming text use cases.

TTerminal extends TTextDevice and is commonly used as a rendering target for redirected text output. Reading from the buffer is not supported by default and must be implemented explicitly by subclasses if required.

Commonly Used Features

In application code, TTerminal is usually initialized once and then written through the text-device interface (print, printf, say, syswrite). When explicit capacity checks are needed before larger writes, canInsert provides the primary guard.

ATTRIBUTES

The following attributes are exposed as read-only accessors and are intended for internal use by the terminal implementation. They reflect the current state of the circular buffer and should not be modified directly.

bufSize

Read-only size of the internal circular buffer in bytes (Int). This value is defined at construction time and does not change.

buffer

Read-only reference to the internal buffer storage. The buffer is allocated and managed internally by the terminal.

queFront

Read-only index pointing to the first byte currently stored in the buffer.

queBack

Read-only index pointing to the most recently written byte in the buffer.

METHODS

new

my $term = TTerminal->new(
  bounds     => $bounds,
  hScrollBar => $hBar,
  vScrollBar => $vBar,
  bufSize    => $bufSize
);

Creates and initializes a new terminal view.

bounds

Bounding rectangle of the terminal view (TRect). This parameter is required.

hScrollBar

Horizontal scroll bar associated with the terminal (TScrollBar).

This parameter must be provided, but its value may be undef if no horizontal scroll bar is required.

vScrollBar

Vertical scroll bar associated with the terminal (TScrollBar).

This parameter must be provided, but its value may be undef if no vertical scroll bar is required.

bufSize

Size of the internal circular buffer in bytes (PositiveOrZeroInt). This parameter is required and determines how much text can be retained before older data is discarded.

new_TTerminal

my $term = new_TTerminal($bounds, $aHScrollBar, $aVScrollBar, $aBufSize);

Factory constructor for creating a terminal instance using positional parameters.

bufInc

$self->bufInc(\$val);

Advances a buffer index by one position, wrapping around to the beginning of the buffer if the end is reached.

bufDec

$self->bufDec(\$val);

Moves a buffer index one position backwards, wrapping around to the end of the buffer if necessary.

canInsert

my $bool = $self->canInsert($amount);

Checks whether $amount bytes can be inserted into the buffer without discarding existing data.

Returns true if sufficient space is available, or false if insertion would require overwriting older content.

do_sputn

my $num = $self->do_sputn($s, $count);

Low-level output routine that writes $count bytes from $s into the terminal buffer and updates the view. Line feed characters mark the start of new lines in the scroll buffer.

This method is primarily an internal override point used by the text-device write path. Application code should normally write through print, printf, say, or syswrite.

nextLine

my $pos = $self->nextLine($pos);

Scans forward from the given buffer position and returns the position of the next line start.

prevLines

my $pos = $self->prevLines($pos, $lines);

Moves backwards from the given buffer position by the specified number of lines and returns the resulting position.

queEmpty

my $bool = $self->queEmpty();

Returns true if the buffer queue is empty, false otherwise.

draw

$self->draw();

Renders the contents of the terminal buffer into the view, taking the current scroll position into account.

getPalette

my $palette = $self->getPalette();

Returns the color palette used to draw the terminal view.

DEMOLISH

DEMOLISH($in_global_destruction);

Cleans up the terminal instance and releases the internal buffer. This method corresponds to the Turbo Vision destructor and is normally invoked automatically.

SEE ALSO

TUI::TextView::TextDevice, TUI::Views::Scroller

AUTHORS

Borland International (original Turbo Vision design)
J. Schneider <brickpool@cpan.org> (Perl implementation and maintenance)

CONTRIBUTORS

magiblot <magiblot@hotmail.com>

COPYRIGHT AND LICENSE

Copyright (c) 1990-1994, 1997 by Borland International

Copyright (c) 2019-2026 the "AUTHORS" and "CONTRIBUTORS" as listed above.

This software is licensed under the MIT license (see the LICENSE file, which is part of the distribution).