/ 
TUI-Vision-v2.0.1
/ TUI::Views::ListViewer

NAME

TUI::Views::ListViewer - base class for list viewers

HIERARCHY

TObject
  TView
    TListViewer
      TListBox

SYNOPSIS

use TUI::Views;

# Subclass TListViewer and override getText to supply your own data
package MyListViewer;
use Moo;
use TUI::Views;
extends TListViewer;

sub getText {
  my ( $self, $dest, $item, $maxChars ) = @_;
  my @data = ( 'alpha', 'beta', 'gamma' );
  $$dest = substr( $data[$item] // '', 0, $maxChars );
}

package main;

my $hbar = TScrollBar->new(
  bounds => TRect->new( ax => 0, ay => 10, bx => 20, by => 11 ) );
my $vbar = TScrollBar->new(
  bounds => TRect->new( ax => 20, ay => 0, bx => 21, by => 10 ) );

my $lv = MyListViewer->new(
  bounds     => TRect->new( ax => 0, ay => 0, bx => 20, by => 10 ),
  numCols    => 1,
  hScrollBar => $hbar,
  vScrollBar => $vbar,
);
$lv->setRange( 3 );

DESCRIPTION

TListViewer is the TUI::Vision base class for list viewer controls. It implements the generic behavior required to display a list of items arranged in one or more columns, including keyboard navigation, mouse interaction, and scroll bar synchronization.

TListViewer does not store the actual data being displayed. Subclasses are expected to provide the data by overriding getText() and typically also selectItem().

List viewers may be equipped with horizontal and/or vertical scroll bars. When attached, the list viewer keeps the scroll bars synchronized with the current focus and range.

Commonly Used Features

Because TListViewer does not manage any data itself, the primary task when using it is to subclass it and override getText, which is called once per visible row to retrieve the display string for a given item index. After construction, call setRange to tell the viewer how many items exist. When the list viewer is placed in a group other than a dialog, getPalette will almost certainly need to be overridden as well so that the color mapping works correctly.

VARIABLES

The following global variable defines the placeholder text used by TListViewer.

$emptyText

Text displayed when the list contains no items.

ATTRIBUTES

The following attributes are implemented as read/write accessors and are also used internally by the list viewer.

hScrollBar

Horizontal scroll bar associated with the list viewer.

vScrollBar

Vertical scroll bar associated with the list viewer.

numCols

Number of columns used to display items.

topItem

Index of the first visible item.

focused

Index of the currently focused item.

range

Total number of items in the list.

CONSTRUCTOR

new

my $lv = TListViewer->new(
  bounds     => $bounds,
  numCols    => $numCols,
  hScrollBar => $hScrollBar,
  vScrollBar => $vScrollBar
);

Creates a new list viewer.

bounds

Bounding rectangle of the list viewer (TRect).

numCols

Number of columns used to display items (PositiveOrZeroInt).

hScrollBar

Optional horizontal scroll bar (TScrollBar).

vScrollBar

Optional vertical scroll bar (TScrollBar).

new_TListViewer

my $lv = new_TListViewer($bounds, $numCols, $hScrollBar, $vScrollBar);

Factory-style constructor using positional arguments.

METHODS

changeBounds

$lv->changeBounds($bounds);

Adjusts the list viewer to a new bounding rectangle and recalculates scroll bar parameters.

draw

$lv->draw();

Draws the list viewer contents using getText().

focusItem

$lv->focusItem($index);

Moves the focus to the specified item index.

focusItemNum

$lv->focusItemNum($index);

Like focusItem, but clamps the index to the valid range.

getPalette

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

Returns the color palette used to draw the list viewer.

getText

$lv->getText(\$dest, $item, $maxChars);

Returns the text representation of an item.

Subclasses are expected to override this method to provide the actual data to be displayed by the list viewer.

handleEvent

$lv->handleEvent($event);

Handles keyboard, mouse, and broadcast events.

isSelected

my $bool = $lv->isSelected($index);

Returns true if the specified item is selected.

Subclasses may override this method to implement multi-selection or alternative selection policies.

selectItem

$lv->selectItem($index);

Called when an item is activated.

Subclasses typically override this method to implement application-specific activation behavior.

setRange

$lv->setRange($count);

Sets the number of items in the list and updates scroll bar state.

setState

$lv->setState($state, $enable);

Updates the view state and shows or hides scroll bars accordingly.

shutDown

$lv->shutDown();

Releases scroll bar references and shuts down the view.

SEE ALSO

TUI::Dialogs::ListBox, TUI::Views::ScrollBar, TUI::Views::View

AUTHORS

  • Borland International (original Turbo Vision design)

  • J. Schneider <brickpool@cpan.org> (Perl implementation and maintenance)

CONTRIBUTORS

  • Eric Woodruff

COPYRIGHT AND LICENSE

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

Copyright (c) 1995, 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).