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

NAME

TUI::Dialogs::Cluster - base class for clustered dialog controls

HIERARCHY

TObject
  TView
    TCluster
      TRadioButtons
      TCheckBoxes

SYNOPSIS

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

# TCluster is a base class; typically use its subclasses instead:
my $items = TSItem->new( value => '~F~irst',
    next => TSItem->new( value => '~S~econd',
    next => TSItem->new( value => '~T~hird',
    next => undef
)));

# Usually instantiated as TRadioButtons (single select) or
# TCheckBoxes (multi-select):
my $buttons = TRadioButtons->new(
  bounds => TRect->new(ax => 2, ay => 5, bx => 20, by => 8),
  strings => $items
);

$dialog->insert($buttons);

DESCRIPTION

TCluster provides the common base implementation for all cluster-style dialog controls. It manages selection state, navigation, enable masks, and the visual layout of clustered items.

The class handles keyboard and mouse input for navigating and activating individual entries. Subclasses specialize the marking and activation behavior to implement specific cluster types such as radio buttons or checkboxes.

TCluster itself is not intended to be instantiated directly.

Commonly Used Features

Most application code uses one of TCluster's concrete subclasses: TUI::Dialogs::RadioButtons for single-select clusters and TUI::Dialogs::CheckBoxes for multi-select clusters. These subclasses inherit all navigation and state management from TCluster while providing their own mark() and press() implementations for distinct user interactions.

TCluster provides a common interface for cluster-type controls: manage selection via keyboard and mouse, track enabled/disabled items via an enable mask, and exchange selection state with dialogs using getData() and setData(). Typical workflow is to build a TSItem linked-list, pass it to a subclass constructor, insert the resulting control into a TUI::Dialogs::Dialog, then retrieve the final selection via getData() after the dialog is closed.

ATTRIBUTES

The following attributes represent the internal state of the cluster.

value

Numeric value representing the current selection state.

For TRadioButtons, this value contains the index of the selected item. For TCheckBoxes, this value is a bit mask where each bit represents the state of one checkbox.

enableMask

Bitmask indicating which items are enabled and selectable (PositiveOrZeroInt).

sel

Index of the currently selected item (PositiveOrZeroInt).

strings

Collection containing the text labels of all cluster items (TSItem).

CONSTRUCTOR

new

my $cluster = TCluster->new(
  bounds  => $bounds,
  strings => $items
);

Creates a new cluster control.

bounds

Bounding rectangle defining the position and size of the cluster control (TRect).

strings

Linked list of item descriptors consumed and converted into an internal string collection (TSItem).

new_TCluster

my $cluster = new_TCluster($bounds, $items | undef);

Factory-style constructor using positional arguments.

METHODS

buttonState

my $bool = $cluster->buttonState($item);

Returns true if the specified item is enabled according to the enable mask.

dataSize

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

Returns the number of scalar values transferred via getData and setData.

For cluster controls, this value is always 1.

drawBox

$cluster->drawBox($icon, $marker);

Draws a single selection box using the given icon and marker.

drawMultiBox

$cluster->drawMultiBox($icon, $marker);

Renders the full multi-column cluster layout.

getData

$cluster->getData(\@record);

Stores the cluster's current value into the supplied record.

getHelpCtx

my $ctx = $cluster->getHelpCtx();

Returns the help context associated with the current item.

The returned value is computed by adding the current selection index to the base help context.

getPalette

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

Returns a cloned palette used for rendering cluster elements.

handleEvent

$cluster->handleEvent($event);

Processes keyboard and mouse events for navigation and activation.

mark

my $bool = $cluster->mark($item);

Indicates whether the given item is marked.

This method is always overridden by subclasses to implement their specific selection behavior.

movedTo

$cluster->movedTo($item);

Called whenever the selection cursor moves to a different item.

multiMark

my $marker = $cluster->multiMark($item);

Returns the marker index used for drawing based on mark().

press

$cluster->press($item);

Invoked when an item is activated.

This method is always overridden by subclasses to implement their selection or toggle behavior.

setButtonState

$cluster->setButtonState($mask, $enable);

Enables or disables items using a bitmask and updates cluster selectability.

setData

$cluster->setData(\@record);

Applies the stored value from an external record.

setState

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

Handles view state changes and moves the selection if required.

SEE ALSO

TUI::Dialogs::RadioButtons, TUI::Dialogs::CheckBoxes, TUI::Dialogs::Dialog, 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) 1994, 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).