NAME

TUI::Views::Group - base class for grouping views in TUI::Vision

HIERARCHY

TObject
  TView
    TGroup
      TWindow
        TDialog
      TDeskTop
      TProgram

SYNOPSIS

use TUI::Views;

my $group = TGroup->new(bounds => $bounds);
$group->insert($view);
$group->remove($view);

DESCRIPTION

TGroup is the structural backbone of TUI::Vision's view hierarchy. It manages collections of subviews and coordinates drawing, event dispatch, and modal execution.

A group itself is an invisible view. Its visual representation is defined entirely by its subviews. Dialogs, windows, and the desktop are all implemented as specialized groups.

TGroup is responsible for maintaining Z-order, dispatching events according to focus and position, and coordinating modal execution via execView and execute. During event processing, the phase attribute allows subviews to determine in which processing stage their handlers are invoked.

To improve drawing performance, groups may use an internal buffer. In this case, screen updates should be bracketed by lock and unlock calls to avoid flicker.

Commonly Used Features

In typical application code, only a small subset of the API is used directly: subviews are added with insert, modal views are executed with execView, and dialog-style state transfer is handled through getData and setData.

Most remaining methods are primarily infrastructure for descendants such as TWindow, TDialog, and TDeskTop. Direct instantiation of TGroup itself is therefore uncommon outside framework-level or advanced custom view implementations.

VARIABLES

The following global variables are used internally by TGroup to track view hierarchy state.

$TheTopView

Holds a reference to the currently active top-level view. This variable is used during focus and event handling.

$ownerGroup

Holds a reference to the group currently owning a view. It is used internally to manage parent-child relationships between views.

ATTRIBUTES

The following attributes represent the internal state of the group and its relationship to contained subviews. Attributes marked as read-only are managed internally and should not be modified directly.

current: Pointer to the currently selected subview (TView). This attribute is managed internally.
last: Read-only pointer to the last subview in the Z-ordered view list.
clip: Clipping rectangle of the group (TRect). Defines the drawable region for subviews.
phase: Read-only event processing phase indicator (Int). Used by subviews to determine the context in which their handleEvent method is invoked.
buffer: Read-only reference to the internal screen cache buffer. Used to speed up redraw operations when buffering is enabled.
lockFlag: Lock counter used to suppress screen updates while batch operations are performed.
endState: Command value used to terminate modal execution.

CONSTRUCTOR

new

my $group = TGroup->new(bounds => $bounds);

Creates and initializes a new group with the specified bounds.

bounds: Bounding rectangle of the group (TRect).

new_TGroup

my $group = new_TGroup($bounds);

Factory-style constructor using positional arguments.

This constructor is equivalent to calling new with the bounds parameter and is provided for compatibility with traditional Turbo Vision construction patterns.

DESTRUCTOR

METHODS

The following methods implement group-specific behavior for managing subviews, event dispatch, drawing, and modal execution.

at

my $view | undef = $group->at($index);

Returns the subview at the specified index.

insert

$group->insert($view);

Inserts a view into the group. The view becomes part of the group's Z-ordered subview list.

insertBefore

$group->insertBefore($view, $target | undef);

Inserts a view before the specified target view. If $target is omitted, the view is inserted at the back of the Z-order.

insertView

$group->insertView($view, $target | undef);

Internal insertion helper used by group management routines.

remove

$group->remove($view | undef);

Removes a view from the group.

removeView

$group->removeView($view);

Removes a view from the group and updates internal bookkeeping.

indexOf

my $index = $group->indexOf($view);

Returns the index of the specified view within the group.

first

my $view | undef = $group->first();

Returns the topmost subview in the group.

last

my $view | undef = $group->last();

Returns the bottommost subview in the group.

firstMatch

my $view | undef = $group->firstMatch($state, $options);

Returns the first subview matching the specified state and options.

firstThat

my $view | undef = $group->firstThat(\&test, @args);

Returns the first subview for which the supplied test function returns true.

forEach

$group->forEach(\&action, @args);

Applies the given action to each subview in Z-order.

current

my $view | undef = $group->current();
$group->current($view);

Returns or sets the currently selected subview.

setCurrent

$group->setCurrent($view, $mode);

Sets the currently focused subview using the specified selection mode.

selectNext

$group->selectNext($forwards);

Selects the next or previous subview in Z-order.

draw

$group->draw();

Draws the group. If buffering is enabled, cached contents are copied to the screen.

drawSubViews

$group->drawSubViews($from | undef, $bottom | undef);

Draws subviews within the specified Z-order range.

redraw

$group->redraw();

Forces a redraw of the group, bypassing cached output.

lock

$group->lock();

Locks the group to suppress screen updates during batch operations.

unlock

$group->unlock();

Unlocks the group and flushes buffered screen updates.

freeBuffer

$group->freeBuffer();

Releases the internal cache buffer.

getBuffer

my $buffer = $group->getBuffer();

Returns the internal buffer used for cached drawing.

handleEvent

$group->handleEvent($event);

Dispatches events to the appropriate subview based on focus and event type.

eventError

$group->eventError($event);

Handles events that could not be processed by any subview.

matches

my $bool = $group->matches($view);

Returns true if the specified view belongs to this group.

execView

my $command = $group->execView($view);

Executes a modal view and returns the command that terminated the modal state.

execute

my $command = $group->execute();

Runs the group's event loop until modal execution ends.

endModal

$group->endModal($command);

Terminates modal execution and causes execute or execView to return.

dataSize

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

Returns the combined data size of all subviews.

getData

$group->getData(\$record);

Copies subview data into the supplied record.

setData

$group->setData(\$record);

Restores subview data from the supplied record.

valid

my $bool = $group->valid($command);

Checks whether the group and all subviews are in a valid state.

shutDown

$group->shutDown();

Shuts down the group and releases associated resources.

AUTHORS

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

CONTRIBUTORS

magiblot <magiblot@hotmail.com>

COPYRIGHT AND LICENSE

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

To install TUI::Vision, copy and paste the appropriate command in to your terminal.

cpanm

cpanm TUI::Vision

CPAN shell

perl -MCPAN -e shell
install TUI::Vision

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)