/ 
TUI-Vision-2.000_002
/ TUI::Dialogs::ListBox

NAME

TUI::Dialogs::ListBox - list box control for displaying collections in dialogs

HIERARCHY

TObject
  TView
    TListViewer
      TListBox

SYNOPSIS

use TUI::Dialogs;
use TUI::Objects;
use TUI::Views;

my $bounds = TRect->new( ax => 1, ay => 1, bx => 41, by => 12 );
my $vbar = TScrollBar->new(
  bounds => TRect->new( ax => 41, ay => 1, bx => 42, by => 12 ),
);

my $items = TStringCollection->new( limit => 10, delta => 5 );
$items->atInsert( 0, 'README.pod' );
$items->atInsert( 1, 'lib/' );
$items->atInsert( 2, 't/' );

my $listBox = TListBox->new(
  bounds     => $bounds,
  numCols    => 1,
  vScrollBar => $vbar,
);
$listBox->newList( $items );

my $text;
$listBox->getText( \$text, 0, 20 );   # 'README.pod'

DESCRIPTION

TListBox implements a list box control for displaying and selecting items from a collection. It is typically used in dialog boxes to present lists of strings, such as filenames or other selectable entries.

The list box manages the data collection internally and displays its contents using the inherited drawing logic from TListViewer. While it is designed primarily for string data, subclasses may override getText to display other data types.

Unlike TListViewer, TListBox does not support a horizontal scroll bar. Scrolling is performed vertically using an optional vertical scroll bar.

Commonly Used Features

In normal dialog code, you construct the control and then immediately attach a collection through newList. That call sets the visible range from the collection size and refreshes the view, so replacing the collection is the usual way to repopulate the box. If your rows are not plain strings, override getText to format each row for display.

STRUCTURES

TListBoxRec

Represents the state record used for transferring list box data.

This structure is used by list box views to exchange the current item list and selection state, typically via getData and setData.

The structure contains the following fields:

items

Reference to the collection backing the list box (TNSCollection).

selection

Index of the currently selected item (Int).

ATTRIBUTES

The following attributes are exposed as read-only accessors and are managed internally by the list box implementation.

items

Reference to the collection of items displayed by the list box (TCollection, e.g. TStringCollection). The collection typically contains string objects.

CONSTRUCTOR

new

my $listBox = TListBox->new(
  bounds     => $bounds,
  numCols    => $numCols,
  vScrollBar => $vScrollBar
);

Creates a new list box control.

bounds

Bounding rectangle of the list box (TRect).

numCols

Number of columns used to display the list items (PositiveOrZeroInt).

vScrollBar

Optional vertical scroll bar associated with the list box (TScrollBar). This parameter may be omitted.

new_TListBox

my $listBox = new_TListBox($bounds, $numCols, | $vScrollBar);

Factory-style constructor using positional arguments.

This constructor is equivalent to calling new with named parameters and is provided for compatibility with traditional Turbo Vision construction patterns.

METHODS

dataSize

my $size = $listBox->dataSize();

Returns the number of data elements required to transfer the state of the list box using getData and setData.

getData

$listBox->getData(\@record);

Copies the list box state into the supplied record.

getText

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

Retrieves the text representation of the item at index $item and writes it into $dest, truncated to at most $maxChars characters.

list

my $collection = $listBox->list();

Returns the collection currently associated with the list box.

newList

$listBox->newList($collection);

Associates a new collection with the list box.

If a collection was already present, it is released before the new collection is installed.

setData

$listBox->setData(\@record);

Restores the list box state from the supplied record.

SEE ALSO

TUI::Dialogs::ListViewer, TUI::Dialogs::Dialog, TUI::Views::View

AUTHORS

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

COPYRIGHT AND LICENSE

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

Copyright (c) 2026 the "AUTHORS" as listed above.

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