/ 
TUI-Vision-v2.0.1
/ TUI::Dialogs::MultiCheckBoxes

NAME

TUI::Dialogs::MultiCheckBoxes - multi-state checkbox cluster control

HIERARCHY

TObject
  TView
    TCluster
      TMultiCheckBoxes

SYNOPSIS

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

my $bounds = TRect->new(
  ax => 0, ay => 0,
  bx => 30, by => 5
);

my $items = {
  value => 'Low', next => {
  value => 'Med', next => {
  value => 'High', next => undef
}}};

my $mcb = new_TMultiCheckBoxes(
  $bounds,
  $items,
  3,        # selRange   (number of states per item)
  0x0201,   # flags      (low byte = mask, high byte = shift per item)
  ' -+'     # states     (characters representing each possible state)
);

DESCRIPTION

TMultiCheckBoxes implements a multi-state checkbox cluster where each item cycles through a configurable number of states instead of a simple on/off selection.

The control stores its state in a packed bitfield. Each item occupies a fixed number of bits, determined by the supplied mask and shift values. This allows multiple stateful items to be encoded efficiently in a single scalar value.

TMultiCheckBoxes inherits navigation, layout, and focus handling from TCluster, while extending the marking and activation logic to support multi-state cycling.

CONSTRUCTOR

new

my $mcb = TMultiCheckBoxes->new(
  bounds   => $bounds,
  strings  => $items,
  selRange => $range,
  flags    => $flags,
  states   => $states
);

Creates a new multi-state checkbox cluster.

bounds

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

strings

Linked list of item descriptors providing the labels (TSItem).

selRange

Number of distinct states each item cycles through (Int).

flags

Packed integer describing the bit mask and bit shift used for encoding item states.

The low byte defines the state mask, the high byte defines the bit shift per item.

states

String containing one character per possible state, used for visual representation (Str).

new_TMultiCheckBoxes

my $mcb = new_TMultiCheckBoxes(
  $bounds,
  $items,
  $range,
  $flags,
  $states
);

Factory-style constructor using positional arguments.

METHODS

dataSize

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

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

For multi-state clusters, this value is always 1.

draw

$mcb->draw();

Renders the multi-state checkbox cluster using the supplied state marker table.

getData

$mcb->getData(\@record);

Writes the packed state bitfield into the output record.

multiMark

my $state = $mcb->multiMark($item);

Returns the current state index for the specified item, extracted from the packed bitfield.

press

$mcb->press($item);

Advances the state of the specified item and wraps around according to selRange.

setData

$mcb->setData(\@record);

Updates the internal packed state bitfield from external input.

USAGE NOTES

TMultiCheckBoxes is particularly useful for representing configuration options with more than two possible values while maintaining a compact visual and data representation.

The packed bitfield design allows seamless integration with dialog data exchange mechanisms.

IMPLEMENTATION NOTES

TMultiCheckBoxes stores its internal state using a packed bitfield representation.

The following values are provided at construction time and used internally by the control:

  • The number of states per item (selection range)

  • A packed flags value defining the bit mask and bit shift used for encoding item states

  • A string defining the visual marker for each possible state

These values are considered internal implementation details and are not exposed as public attributes. Application code should not rely on direct access to these values after construction.

SEE ALSO

TUI::Dialogs::CheckBoxes, TUI::Dialogs::RadioButtons, TUI::Dialogs::Cluster, TUI::Dialogs::Dialog

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