/ 
TUI-Vision-v2.0.2
/ TUI::Menus::MenuItem

NAME

TUI::Menus::MenuItem - represents a single menu item or submenu entry

SYNOPSIS

use TUI::Menus;

# command item (generates a command)
my $item =
  new_TMenuItem('~O~pen...', cmFileOpen, kbF3, hcNoContext, 'F3');

# submenu item (opens a submenu)
my $sub =
  new_TMenuItem('~F~ile', kbNoKey, $subMenu, hcNoContext);

# chaining menu items
my $menu =
    new_TMenuItem('~O~pen...', cmFileOpen, kbF3, hcNoContext, 'F3')
  + new_TMenuItem('E~x~it', cmQuit, kbAltX, hcNoContext, 'Alt-X');

DESCRIPTION

TMenuItem represents a single entry in a menu structure. Menu items are linked together to form a list and are used by menu views such as TMenuBar and TMenuBox to display selectable commands.

Each menu item may represent either a command entry or a submenu entry. This is determined by whether the item contains a command or a submenu reference.

Menu items are typically created using factory constructors and combined using the overloaded + operator to form complete menu structures.

ATTRIBUTES

The following attributes describe the state of a menu item.

name

Text displayed for the menu item (Str). Marked characters may be used to define a hotkey.

command

Command identifier generated when the item is selected (PositiveOrZeroInt).

keyCode

Scan code of the hot key associated with the menu item (PositiveOrZeroInt).

disabled

Boolean flag indicating whether the item is disabled (Bool).

helpCtx

Help context identifier associated with the menu item (PositiveOrZeroInt).

param

Optional parameter string displayed next to the menu item, such as a shortcut label (Str).

Optional submenu associated with this item (TMenu).

next

Reference to the next menu item in the list (TMenuItem).

CONSTRUCTOR

new

# Command item form
my $item = TMenuItem->new(
  name    => $name,
  keyCode => $keyCode,
  command => $command,
  # optional ..
  (
    helpCtx => $helpCtx,
    param   => $param,
    next    => $next,
  )
);

# Submenu item form
my $item = TMenuItem->new(
  name    => $name,
  command => $command,
  subMenu => $subMenu,
  # optional ..
  (
    helpCtx => $helpCtx,
    next    => $next,
  )
);

Creates a new menu item.

name

Text displayed for the menu item (Str).

keyCode

Hot key scan code (PositiveOrZeroInt).

command

Command identifier (PositiveOrZeroInt). This parameter is optional for submenu entries.

Optional submenu associated with this item (Object).

helpCtx

Optional help context identifier (PositiveOrZeroInt).

param

Optional parameter string displayed next to the item (Str).

next

Optional reference to the next menu item (Object).

new_TMenuItem

# Command item form
my $item = new_TMenuItem(
  $name,
  $command,
  $keyCode,
  $helpCtx = hcNoContext,
  $param   = '',
  $next    = undef,
);

# Submenu item form
my $item = new_TMenuItem(
  $name,
  $keyCode,
  $subMenu | undef,
  $helpCtx = hcNoContext,
  $next    = undef,
);

Factory-style constructor for menu items.

This constructor supports two distinct forms, corresponding directly to the original Turbo Vision constructors:

  • Command item form: creates a selectable menu entry that generates a command when activated.

  • Submenu item form: creates a menu entry that opens a submenu instead of generating a command.

The constructor automatically determines which form is used based on the supplied arguments.

Menu items are typically combined using the overloaded + operator to form linked lists representing complete menu structures.

newLine

my $item = newLine();

Creates a separator line entry for use in menus.

METHODS

append

$item->append($next);

Appends another menu item to the end of the menu item chain.

EXAMPLE

The following example shows how command items and submenu items are combined to build a menu structure.

my $menu =
    new_TSubMenu('~F~ile', hcNoContext)
      + new_TMenuItem('~O~pen...', cmFileOpen, kbF3, hcNoContext, 'F3')
      + new_TMenuItem('~S~ave as...', cmFileSave, hcNoContext)
      + newLine
      + new_TMenuItem('E~x~it', cmQuit, kbAltX, hcNoContext, 'Alt-X')
    + new_TSubMenu('~H~elp', hcNoContext)
      + new_TMenuItem('~A~bout', cmAbout, hcNoContext);

SEE ALSO

TMenu, TMenuBar, TMenuBox

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