Cmenu 1.1

Cmenu is a 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); 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..

Requirements:	No special requirements
Platforms:	Linux
Keyword:	Cmenu,  Data Entry,  Item,  Label,  Libraries,  Menu,  Programming,  Text,  Text Label,  Will Be
Users rating:	0/10