| Store | Cart

ActiveState Docs

ActivePerl 5.10 Documentation

Loading...

ActiveState::Menu - Present a menu


NAME

ActiveState::Menu - Present a menu


SYNOPSIS

 use ActiveState::Menu qw(menu prompt yes);
 my $sel = menu([qw(Foo Bar Baz)]);
 menu(intro  => "M E N U",
      menu   => [["&Foo", \&do_foo],
                 ["S&ub", {
                     intro      => "S U B  M E N U",
                     menu       => [qw(Apples Oranges Exit)],
                     loop_until => 2,
                 }],
                 ["Ba&r", \&do_bar],
                 "-----",
                 ["&h", \&do_help],
                 ["(Ba&z)", \&do_baz]],
      prompt => "What (type 'h' for help)?",
      force  => 1,
     );
  my $ans = (prompt("What is your favourite colour?", "blue"));
  if (yes("Do you really want to quit?")) {
      print "Bye\n";
      exit;
  }


DESCRIPTION

This module provide the following functions:

menu( %opts )

This function will present a menu on the terminal. The return value is the index of menu item selected (or undef if no item was selected).

The following options are recognised:

   menu:    something to select from (array ref)
   intro:   heading text
   prompt:  prompt text
   force:   force something to be selected (bool)
   disabled_selectable: allow disabled items to be selected
   loop_until: show menu in a loop until a particular item is selected

The items of the menu array can either be plain text strings or an array reference containing a string and a function reference.

If a function is provided, it will be invoked if the item is selected. The value of $_ is set to the menu text before the function is called, so the same function can serve multiple entries and change it behaviour based on what it finds in $_.

If the menu text contains the letter "&" then the next letter is taken as a selector. The menu item can be selected by typing this selector. The "&" character itself is not rendered.

If the menu text is enclosed in parenthesis, then that selection is shown as disabled. Any action associated with the item is not triggered if it is selected.

If the menu text only consist of the letter "&" followed by a selector char, then the given menu item is invisible, but the associated action could still be triggered. This can be used for hidden commands or help behaviour as demonstrated in the synopsis above.

If the menu text consist of a line of at least 3 dashes, then it is taken as a separator. An action is associated with a separator line is always ignored.

If only a single argument is given to the menu() function, it is taken to be the same as the menu option.

The intro text is presented as a heading above the menu. Simple markup like *bold*and _underline_ can be used for visual effect. If not provided, no heading is used.

The prompt option replace the default "Please select an item?" text.

If the force option has a TRUE value then it prevents the menu() function from returning undef (if the user did not select any item). It also prevents the index of any disabled items from being returned. The option disabled_selectable can be used to counter that behaviour.

The loop_until option, if specified, makes the menu run in a loop until one of the indices specified by the option is selected. The value of the option should be either a single index, or a reference to an array of indices.

prompt( $question, $default )

This function will ask a question on the terminal and return the answer given. If the program is not running on a terminal then the $default is returned.

This function comes from the ActiveState::Prompt module. Refer to the documentation of that module for the complete story.

yes( $question, $default )

Will use the prompt function to ask a question and then return a TRUE value if the answer was "yes". If no $default is given it defaults to "no".

This function also comes from the ActiveState::Prompt module.


SEE ALSO

the ActiveState::Prompt manpage.