view release on metacpan or  search on metacpan

Cmenu.pm  view on Meta::CPAN

       0  (default) preceeds the text with a text label
          the label is returned if the item is selected
       1  use number instead of a text label; numbered in
          order of definition
       2  item is part of a radio list; radio lists allow
          only ONE item to be selected per menu
       3  item is part of a check list; check lists allow
          any number (inc. none) of items to be selected
       4  as for type 0 expect item label is rendered differently
          usually used to list data fields where the text is
          the contents of a field and the label is its meaning
       5  as for 4 except the item text is right-aligned
       6  as for 4 but if the item is selected, field contents
          can be edited
       7  as for 6 except field treated as a numeric value
       8  displayed as for 4 except an alternative reference
          (not the text label) is returned when selected
       9  spacer; leaves a space in the menu

   $item_data    Some item styles need extra information
       2  which item in a radio list is already active
       3  item in a check list already selected
       6  specifies the return value for the field
       7  as for 6
       8  as for 6

   $item pos     For edit fields only (6 + 7); specifies the
                 maximum length of a data field and decimal 
                 precision for numbers. Passed as a space
                 seperated list eg "30 2 0", length 30 with
                 2 decimal places

=head2 menu_display

Actually performs the menu display and navigation. Returns 
information relevant to the action selected. Accepts 2 parametrs;

  $menu_prompt   Displayed at the foot of the screen as advice
  $menu_start    Which item should be active from the start
                 This allows items other than the first declared
                 to be selected; useful when returning to a menu
                 after an earlier selection (optional)

This is the important call which returns the result of menu
navigation. Depending on the style of menu items defined, various results
will be returned. Generally all selections are a tokenised list seperated
by a standard character ($Cmenu::menu_sep - can be changed by user). For
simple menus, only the selected text label (0,1,4,5) or offset (8) will be
returned.

For radio and check lists (2 and 3) all the selected items will be returned
using each items text label

For edited data fields, more complex values are returned. All editable fields
on a menu will have a token (whether edited or not) returned. Each token has two
fields - the field label and the new field contents; these are seperated by
$Cmenu::menu_sepn.

Since any type of item can be included in a menu, return values may be
equally complex. For complex return values, tokens can be split out using
a command fragment such as

 chop($return_value=&menu_display("Menu Prompt",$start_on_menu_item));
 @selection=split(/$Cmenu::menu_sep/,$return_value);
 for($loop=1;$loop<=$#selection;$i++) {
   # deal with each token
   ($field_label,$field_content) = split(/$Cmenu::menu_sepn,$selection[$i]);
   # processing each field accordingly
   ...
   }

The first token returned ($selection[0]) is usually the key pressed to close the
menu was closed; this will rarely be a valid menu item - check it to make sure 
an "abort" was not requested.

=head2 menu_button_set

Each menu has up to 3 buttons which can be activated. Usually these give
options to either Accept a menu item or Abort the menu prematurely. A Help
facility may also be called.

This routine switches buttons on and off and, specifies the text label of the button
(button actions cannot be altered yielding "ACCEPT", "HELP" or "EXIT" although your 
scripts can interret these responses however you wish). The <TAB> key
traverses the buttons bar.

Parameters for this routine are;
  $button  a number 1, 2 or 3 specifying which button is to be set
  $label   the text label for the button; an empty string switches the button off

=head2 menu_popup

Allows a simple screen to pop-up if a lengthy process has been launched. The popup
has only one line of text to give an indication of what the system is doing; 
  To start a popup - call with $message
  To close a popup - call with NO message
Remember to close the popup or the menu display will get confused.

=head2 menu_show

Allows a variety of information to be shown on the screen; the display
generally replaces normal menu rendering until the user presses an approriate key.
The routines takes 3 parameters
  $title    the title of the display
  $message  the message to be displayed. If this is only one line it will be
            centred; if longer the external routine Text::wrap is used to
            manipulated the text to fit on the screen. Text formatting
            is quite primitive.
            The display cannot be scrolled if it exceeds the dimensions of
            the active window
  $colour   colour style to render the display chosen from HELP|WARN|ERROR
            HELP screens have an automatic button to continue; WARN and ERROR 
            can have multiple buttons (use menu_button_set to control these)

=head2 menu_terminate

Called as the script terminates to close down menu facilities and Curses.
The terminal should be left in a sane state. The $message parameter prints
to STDOUT as the script/routine finishes.

If a scripts aborts before calling this, the sanity of the tty will likely