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

NAME

TUI::App::Program - central program object managing application execution

HIERARCHY

TObject
  TView
    TGroup
      TProgram
        TApplication

SYNOPSIS

use TUI::App;
use TUI::Drivers;
use TUI::Menus;

package MyProgram;
extends TProgram;

sub initMenuBar {
  my ( $class, $r ) = @_;
  $r->{b}{y} = $r->{a}{y} + 1;
  return new_TMenuBar(
    $r,
    new_TSubMenu( '~F~ile', 0, 0 ) +
    new_TMenuItem( 'E~x~it', cmQuit, kbAltX, 0, 'Alt-X' )
  );
}

sub initStatusLine {
  my ( $class, $r ) = @_;
  $r->{a}{y} = $r->{b}{y} - 1;
  return new_TStatusLine(
    $r,
    new_TStatusDef( 0, 0xFFFF ) +
    new_TStatusItem( '~Alt-X~ Exit', kbAltX, cmQuit )
  );
}

package main;

my $program = MyProgram->new();
$program->run();

DESCRIPTION

TProgram implements the core functionality of a TUI::Vision application. It manages the event loop, screen initialization, desktop, menu bar, and status line.

Most applications derive from TApplication, which extends TProgram with additional behavior. However, it is also possible to derive an application directly from TProgram.

TProgram owns all top-level views of the application and coordinates event dispatch, idle processing, and shutdown.

Commonly Used Features

In normal applications you instantiate a TProgram-derived class and call run; most day-to-day customization happens by overriding initMenuBar, initStatusLine, handleEvent, and sometimes idle. TProgram wires the desktop, menu bar, and status line during construction, then drives the main event loop for you. While many projects derive from TApplication, the same workflow applies because TApplication builds directly on this class.

VARIABLES

The following global variables are used by TProgram and its subclasses to access application state and top-level views.

$exitText

Label text for the standard application exit command, including optional accelerator markers.

$application

Reference to the running application object (usually TApplication).

$statusLine

Reference to the application's TStatusLine instance.

$menuBar

Reference to the application's TMenuBar instance.

$deskTop

Reference to the application's TDeskTop container.

$appPalette

Index of the active application color palette.

$pending

Pending TEvent object queued for later processing.

CONSTRUCTOR

new

my $program = TProgram->new();

Creates a new program object and initializes TUI::Vision support.

This constructor corresponds to the Turbo Vision 2.0 constructor and calls initScreen, initDeskTop, initMenuBar, and initStatusLine.

new_TProgram

my $program = new_TProgram();

Factory-style constructor using positional arguments.

This constructor is provided for compatibility with traditional Turbo Vision construction patterns.

DESTRUCTOR

DEMOLISH

$self->DEMOLISH($in_global_destruction);

Releases application-level resources during object destruction.

This method is part of the Perl object lifecycle and ensures that internal references to the desktop, menu bar, and status line are released when the program object is destroyed.

METHODS

canMoveFocus

my $bool = $program->canMoveFocus();

Returns true if the focus can be moved between views.

executeDialog

my $command = $program->executeDialog($dialog, \@data | undef);

Executes a dialog modally and returns the resulting command.

getEvent

$program->getEvent($event);

Retrieves the next input event and dispatches it to the appropriate view.

getPalette

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

Returns the current application-level color palette.

handleEvent

$program->handleEvent($event);

Handles application-level events.

Applications typically override this method and call the inherited implementation first.

idle

$program->idle();

Performs background processing during idle periods.

initDeskTop

my $desktop = $program->initDeskTop($rect);

Initializes the desktop view.

initMenuBar

my $menuBar = $program->initMenuBar($rect);

Initializes the menu bar.

initScreen

$program->initScreen();

Initializes screen mode dependent settings.

initStatusLine

my $statusLine = $program->initStatusLine($rect);

Initializes the status line.

insertWindow

my $window = $program->insertWindow($window);

Inserts a window into the desktop.

outOfMemory

$program->outOfMemory();

Handles low-memory conditions.

putEvent

$program->putEvent($event);

Places an event back into the event queue.

resume

$program->resume();

Resumes execution after suspension.

run

$program->run();

Starts the main application event loop.

setScreenMode

$program->setScreenMode($mode);

Changes the application screen mode.

shutDown

$program->shutDown();

Shuts down the application and releases resources.

suspend

$program->suspend();

Suspends application execution.

validView

my $view = $program->validView($view | undef);

Validates a newly created view and handles low-memory conditions.

SEE ALSO

TUI::App::Application, TUI::Views::View, 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) 2025-2026 the "AUTHORS" as listed above.

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