/ 
TUI-Vision-v2.0.1
/ TUI::Drivers::Event

NAME

TUI::Drivers::Event - unified event structure for input handling

HIERARCHY

TEvent (value type, tied hash)
  used throughout the event system

SYNOPSIS

use TUI::Drivers::Event;

my $event = TEvent->new;

if ($event->{what} & evMouse) {
  my $x = $event->{mouse}{where}{x};
  my $y = $event->{mouse}{where}{y};
}

if ($event->{what} & evKeyboard) {
  my $key = $event->{keyDown}{keyCode};
}

DESCRIPTION

TEvent represents the central event structure used throughout TUI::Vision. It models all input and message events such as keyboard input, mouse activity, and broadcast messages.

This type is implemented as a tied hash and is not derived from TObject. Its structure mirrors the Turbo Vision event union, with the active event variant selected by the what field.

Depending on the event type, one of the variant substructures is active and accessible via the corresponding hash key.

Commonly Used Features

In practice, TEvent is most often used in two ways:

  • As the mutable event object passed through handleEvent() chains, where handlers inspect what and then read/write the active variant (mouse/keyDown/message).

  • As a synthetic event in tests and higher-level components, e.g. creating keyboard, mouse, broadcast, or command events with TEvent-new(...)> and injecting them into controls/dialogs.

Typical checks branch on what and then access only the matching variant fields. For example, evKeyDown events commonly use $event->{keyDown}{charScan}{charCode} for incremental search, while evCommand/evBroadcast paths read $event->{message}{command} and optionally infoPtr/infoWord payload fields.

EVENT STRUCTURE

A TEvent object exposes the following top-level fields:

what

Event type bitmask indicating the active event variant.

mouse

Mouse event data, present when what includes evMouse.

keyDown

Keyboard event data, present when what includes evKeyboard.

message

Message event data, present when what includes evMessage.

Only one variant field is active at a time, determined by the value of what.

INTERNAL REPRESENTATION

Internally, TEvent is implemented as a tied hash that models the original Turbo Vision C++ event union. The active event variant is selected by the value of the what field.

Conceptually, the structure can be viewed as follows:

  • The what field stores the event type bitmask.

  • Exactly one variant structure is active at a time and stored internally.

  • Access to variant data is provided through the keys mouse, keyDown, or message, depending on the event type.

The following conceptual layout illustrates the Perl representation:

TEvent (tied hash)
  what    => Int
  mouse   => MouseEventType
    where           => TPoint
    eventFlags      => Bool
    buttons         => Int
    controlKeyState => Int

  keyDown => KeyDownEvent
    keyCode          => Int
    charScan         => CharScanType
      charCode       => Int
      scanCode       => Int
    controlKeyState  => Int

  message => MessageEvent
    command  => Int
    infoPtr  => Any
    infoLong => Int
    infoWord => Int
    infoInt  => Int
    infoByte => Int
    infoChar => Str

This representation is an implementation detail. Application code should rely solely on the documented TEvent fields and must not depend on the internal tie or storage mechanics.

CONSTRUCTOR

new

my $event = TEvent->new();

Creates a new event object initialized to evNothing.

new_TEvent

my $event = new_TEvent();

Factory-style constructor equivalent to new.

METHODS

assign

$event->assign($other);

Copies the contents of another event into this event.

The active event variant is copied as well. Variant data is cloned to avoid unexpected aliasing when events are reused.

clone

my $copy = $event->clone();

Creates a deep copy of the event, including its active variant data.

This method is useful when an event must be preserved beyond the lifetime of the current event loop iteration.

dump

my $string = $event->dump();

Returns a string representation of the event for debugging purposes.

getKeyEvent

$event->getKeyEvent();

Retrieves the next keyboard event from the hardware layer and populates the event structure accordingly.

getMouseEvent

$event->getMouseEvent();

Retrieves the next mouse event from the event queue and populates the event structure accordingly.

HASH INTERFACE

TEvent implements the Tie::Hash interface. Fields are accessed via normal hash operations.

Direct deletion or clearing of fields is not supported.

EVENT VARIANTS

Mouse events

When what contains evMouse, the mouse field is active and provides:

where

Mouse position as a TPoint.

buttons

Bitmask of pressed mouse buttons.

eventFlags

Additional mouse event flags.

controlKeyState

Modifier key state during the mouse event.

Keyboard events

When what contains evKeyboard, the keyDown field is active and provides:

keyCode

Combined key code representing the pressed key.

charScan

Character and scan code pair.

controlKeyState

Modifier key state during the key press.

Message events

When what contains evMessage, the message field is active and provides:

command

Command identifier.

infoPtr

Optional associated object or reference.

infoLong

32-bit integer message data.

infoWord

16-bit integer message data.

infoInt

Native integer message data.

infoByte

8-bit integer message data.

infoChar

Single character message data.

USAGE NOTES

TEvent objects are typically allocated once and reused by the event loop. Event handlers inspect the what field to determine the active variant and process the corresponding data.

SEE ALSO

TUI::Drivers::EventQueue, TUI::Drivers::Const, TUI::Views::View

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