/ 
TUI-Vision-v2.0.1
/ TUI::App::DeskTop

NAME

TUI::App::DeskTop - manages the application desktop area and owned views

HIERARCHY

TObject
  TView
    TGroup
      TDeskTop

SYNOPSIS

use TUI::App;
use TUI::Objects;

# Usually created by TProgram/TApplication during startup:
my $deskTop = TDeskTop->new(
  bounds => $bounds
);

# Non-modal views are inserted directly into the desktop.
$deskTop->insert($window);

# Modal views are executed and return a command/result.
my $result = $deskTop->execView($dialog);

# Rearrange tileable windows in the desktop area.
my $workArea = TRect->new(ax => 0, ay => 1, bx => 80, by => 24);
$deskTop->tile($workArea);
$deskTop->cascade($workArea);

DESCRIPTION

TDeskTop represents the desktop area of a TUI::Vision application. It manages the screen region between the menu bar and the status line and owns the background view as well as all top-level windows and dialogs.

Each application has exactly one desktop object, referenced by the global variable $deskTop. Windows and non-modal dialogs are inserted into the desktop, while modal dialogs are executed via execView inherited from TGroup.

TDeskTop also provides functionality to rearrange its child windows using cascading or tiling layouts.

Commonly Used Features

In normal application code, the desktop is primarily used as the owner for top-level views. Non-modal windows and dialogs are inserted with insert(), while modal dialogs are run with execView() so the caller can react to the returned command.

Window management operations are typically tile() and cascade() to rearrange visible tileable windows, plus keyboard focus cycling handled through desktop event processing. Most projects use the desktop created by TProgram::initDeskTop; custom desktop subclasses are mainly needed when you want alternative background behavior via initBackground() or custom layout error handling via tileError().

VARIABLES

The following global variable defines the default background appearance used by TDeskTop.

$defaultBkgrnd

Defines the default background character used to fill the desktop area.

ATTRIBUTES

The following attributes are managed internally and exposed as read-only accessors.

background

The TBackground object forming the visual backdrop of the desktop.

tileColumnsFirst

Boolean flag controlling whether tiling prefers columns before rows.

CONSTRUCTOR

new

my $deskTop = TDeskTop->new(
  bounds => $bounds
);

Creates a new desktop object.

bounds

Bounding rectangle defining the usable screen area of the desktop (TRect).

METHODS

cascade

$deskTop->cascade($rect);

Arranges all tileable windows owned by the desktop in a cascading layout.

handleEvent

$deskTop->handleEvent($event);

Processes desktop-level events.

This method primarily intercepts navigation keys used to cycle through the windows owned by the desktop. Other events are passed to inherited handlers.

initBackground

my $background = $deskTop->initBackground($bounds);

Creates and initializes the background view.

Subclasses may override this method to provide a custom background implementation.

shutDown

$deskTop->shutDown();

Shuts down the desktop and releases owned views.

tile

$deskTop->tile($rect);

Arranges all tileable windows owned by the desktop in a tiled layout.

tileError

$deskTop->tileError();

Called when the desktop cannot arrange its windows using cascade or tile.

Subclasses may override this method to report layout errors.

SEE ALSO

TUI::App::Background, TUI::App::Program, TUI::Views::Window, TUI::Views::Group

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) 2021-2026 the "AUTHORS" as listed above.

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