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 ( HASH )

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