/ 
Curses-UI-0.61
River stage two • 20 direct dependents • 20 total dependents
/ Curses::UI::MenuListBox

NAME

Curses::UI::MenuListBox - Create and manipulate menulistbox widgets

SYNOPSIS

use Curses::UI;
my $cui = new Curses::UI;

my $menulistbox = $cui->add(
    'mymenulistbox', 'MenuListBox',
    -values    => [1, 2, 3],
    -labels    => { 1 => 'One', 
                    2 => 'Two', 
                    3 => 'Three' },
);

$menulistbox->focus();

DESCRIPTION

This class is a descendant of both the Curses::UI::Window and the Curses::UI::ListBox class. This means that it implements a listbox which can be added as a separate window to the Curses::UI root window. It has special bindings for behaving nicely within a menu system.

This class is internally used by the Curses::UI::MenuBar class. Normally you would not want to use this class directly.

STANDARD OPTIONS

-x and -y. These are the only standard options that Curses::UI::MenuBar uses. For an explanation of these standard options, see Curses::UI::Widget.

WIDGET-SPECIFIC OPTIONS

  • -is_topmenu < BOOLEAN >

    This option determines if the widget should act as a topmenu or not. The bindings for a topmenu are a bit different from those of a submenu. The default for BOOLEAN is false.

  • -menu < ARRAYREF >

    The menu items are defined by the ARRAYREF. Each item of the ARRAYREF contains the definition for a menu item. Each item is a reference to a hash. This hash always contains the key -label. The value of this key determines the label of the menu item. Next to this key, the hash should also contain one of the following keys:

    * -callback

    The value should be a CODE reference. If this menu
item is selected, the CODE reference will be returned.

    * -return

    The value should be a SCALAR value. If this menu
item is selected, the SCALAR value will be returned.

    * -submenu

    The value should be an array reference. This array
reference has the same structure as the array reference
for the B<-menu> option.

    Example data structure:

    my $submenu = [
    { -label => 'option 1',
      -callback => \&callback1 },

    { -label => 'option 2',
      -callback => \&callback2 },

    { -label => 'option 3',
      -return => 'whatever' },
];

my $menu = [
    { -label => 'Do callback', 
      -callback => \&first_callback },

    { -label => 'Another callback',
      -callback => \&second_callback },

    { -label => 'Simple returnvalue',
      -return => 'some returnvalue' },

    { -label => 'Open submenu',
      -submenu => $submenu },

    { -label => 'Exit',
      -return => sub { exit(0) }}
];

METHODS

  • new ( OPTIONS )

  • layout ( )

  • draw ( BOOLEAN )

  • focus ( )

    These are standard methods. See Curses::UI::Widget for an explanation of these.

DEFAULT BINDINGS

The bindings for for this class are the same as those for the Curses::UI::ListBox, except for the following points:

  • <escape>

    Call the 'escape' routine. The widget will loose its focus and return the value 'ESCAPE' to the calling routine.

  • <tab>

    This key is in this class not bound to any routine.

  • <cursor-left>, <h>

    Call the 'cursor-left' routine. This routine will return the value 'CURSOR_LEFT'. This will make the widget loose its focus and return 'CURSOR_LEFT' to the calling routine.

  • <cursor-right>, <l>

    Call the 'cursor-right' routine. The exact action for this routine depends upon the fact if the current menuitem has a submenu or not:

    The current menuitem has no submenu ===================================

    If the current menuitem has no submenu and this widget is not a submenu (so -is_topmenu is set to a true value), this widget will loose focus and return the value 'CURSOR_RIGHT' to the calling routine. This value can be caught by the Curses::UI::MenuBar to select the next menu.

    The current menuitem has a submenu ==================================

    If the current menuitem points to a submenu, a new menulistbox instance will be created for this submenu. After that, this menulistbox will get the focus. The created menulistbox will return a value if it looses focus. After that the created menulistbox will be deleted.

    This widget will act differently upon the value that was returned by the created menulistbox:

    * The value 'CURSOR_LEFT'

    This means that in the menulistbox that was created,
the last called routine was 'cursor-left'. So all
that is needed is this menulistbox instance to get
focus (and since it already has focus, actually
nothing is done at all).

    * Any other SCALAR or CODEREF value

    If a scalar or a coderef is returned by B<focus>,
this widget will loose its focus and return
the value to the calling routine.

  • <cursor-right, <l>, <enter>, <space>

    Call the 'option-select' routine.

    If the current menuitem has a submenu, this routine will invoke the 'cursor-right' routine.

    If it has a -callback or a -return value, the widget will loose its focus and the value will be returned to the calling routine.

SEE ALSO

Curses::UI, Curses::UI::MenuBar, Curses::UI::ListBox

AUTHOR

Copyright (c) 2001-2002 Maurice Makaay. All rights reserved.

This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the same terms as perl itself.