Search

Documents

Cmenu - Perl extension for menuing and data entry in perl scripts

• NAME
• SYNOPSIS
• DESCRIPTION
• menu_initialise
• menu_init
• menu_item
• menu_display
• menu_button_set
• menu_popup
• menu_show
• menu_terminate
• AUTHOR
• FILES
• BUGS

NAME

Cmenu - Perl extension for menuing and data entry in perl scripts

SYNOPSIS

  use Cmenu;
  use Curses;
  use Text::Wrap;

  &menu_initialise($main_title,$advice);
  &menu_init($title,$sub-title,$topest,$menu_help);
   &menu_item($item_text,$item_label,$item_style,$item_data,$item_pos)
   &menu_item($item_text,$item_label,$item_style,$item_data,$item_pos)
    ...
   &menu_item($item_text,$item_label,$item_style,$item_data,$item_pos)

  $sel=&menu_display($advice,$start_item);

  &menu_button_set($button,$button_text);

  &menu_popup($title,$text);
   ...
  &menu_popup();

  &menu_show($title,$text,$colour);

  &menu_terminate($message);

DESCRIPTION

CMENU is a Perl Module designed to provide functions for the creation of menus in perl scripts.

It follows on from perlmenu but uses a Curses interface for screen manipulation. It also uses the Text::Wrap module to process large chunks of text for display. These two modules should be loaded by user scripts.

The sequence of menu processing is as follows; 1. Initialise the module loop 2. Define a menu structure 3. Define several menu options 4. Call the menu 5. Deal with the menu selections loop 6. Terminate the module

The module also provide some extra functions.

menu_initialise

This routine initialises Curses and creates necessary structures for the menu module. It accepts two parameters which may be empty; $main_title A script-wide title displayed on all pages $advice A short text advisory displayed at the foot of every screen (unless over-ridden by the module). The routine returns nothing.

menu_init

The routine creates a graphic backdrop in the style of the command-line utility ``dialog''. It accepts 3 parameters $title a menu title displayed at the top $sub_title sub-title text used to give more description $menu_help a help-file to be displayed when the Help key is pressed. The help file is located in a standard location as defined in the configuration file. (optional)

menu_item

Each line of a menu is created using this call. $item_text The text to be displayed as the menu option $item_label A text label which may be displayed beside the text $item_style How the menu option should be drawn or behave Should be a number from 0 to 9 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

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.

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

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.

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)

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 get lost; use the command ``reset'' to restore sanity.

AUTHOR

Andy Ferguson andy@moil.demon.co.uk

FILES

cmenurc configuration file to set terminal and screen defaults this file may be System Wide - in /etc/Cmenu/.cmenurc User specific - ~/.cmenurc Run Specific - ./cmenurc See the distributed file for contents.

vt100-wy60 A tic (terminfo) file for VT100 emulation on a Wyse 60 terminal; this sets the functions keys appropriately

demo A sample script showing how menus can be rendered with the module.

BUGS

* No continuation pages or checks for text displays overflowing the windows. * Resize and Refresh functions can misbehave in spawned shells * BACKTAB definition from Curses is lost so can only TAB forwards thru buttons

perl(1).

Information