From: skunz@iastate.edu (Steven L. Kunz) Newsgroups: comp.lang.perl.announce,comp.lang.perl.misc [1] ANNOUNCE: PerlMenu version 3.3 Followup-To: comp.lang.perl.misc Date: Wed Feb 21 13:39:24 PST 1996 Organization: Iowa State University, Ames, Iowa Lines: 242 X-Disclaimer: The "Approved" header verifies header information for article + transmission and does not imply approval of content. --------------------------------- Announcing PerlMenu Version 3.3 --------------------------------- This is the official announcement of the release of the latest PerlMenu package, version 3.3. Version 3.3 is a release that incorporates several new features and bug-fixes. This package has been tested with both Perl4/curseperl and Perl5/Curses. This software is available via "anonymous ftp" as a tar'd and compressed format library at the following URL: ftp://ftp.iastate.edu/pub/perl/perlmenu.v3.3.tar.Z As soon as I can get the current version up to the CPAN sites it will be there, also. In addition, PerlMenu now has its very own WWW home page (maintained by the author), at: http://www.cc.iastate.edu/perlmenu/ ----------------------------- Compatibility and New Features ----------------------------- For current "menu.pl version 3.x" users, this version of menu.pl is call-compatible with older versions. Changes between PerlMenu version 3.3 and version 3.2 are: - Added a new call ("menu_load_template_array") to allow loading templates from an array (loaded within your Perl program) in addition to loading it from a file (as with the current "menu_load_template"). This means you can build your template applications as "one file", as opposed to having to distribute template files as companion required pieces. Changes "demo_template" to actually use this feature (with comments indicating how to use the file method, too). Thanks to Bjarne Steinsbo for all the patches required to install this feature. - Added a new (optional) operand to the "menu_init" call to support help on specific items within a menu. With an appropriate routine supplied, pressing "?" on a selected item will call the routine with the selection- text and action-text for the items as calling parms, providing a means of providing textual help for the item. The "demo" sample program is modified to provide help on individual items on the main menu to demonstrate this feature. - Added a new call ("menu_help_routine") to allow overridding the default generic help screen (seen by pressing "h") so you can supply your own. - Added new operands to the "menu_prefs" call to allow overriding the "Do you really want to quit?" prompt and the default response. - Added additional "emacs-similar" field movement control sequences to menu_getstr and menu_display_template. Control-N and Control-P now move to next and previous fields. Thanks to Charles F. Randall of the Des Moines Area Community College. - Added new return code support to template exit routines to allow aborting data input when using "required fields" support. Thanks to Christopher Candreva (WestNet Internet Services of Westchester). - Updated "demo_template" and "ezreg" programs to reflect new "abort input using required fields" support. - Added a "clear_screen" call to "menuutil.pl" utility routines. The clears the screen and resets the $row and $col variables for you. - Added block of commented code to "menu.pl" for systems that do not have "getcap" but do have "terminfo" files and "tput" commands to get terminal sequences (such as SGI and other System V platforms). Expanded the installation instructions in the README file to better explain the "termcap" vs "terminfo" ramifications on various systems. - Improved documentation on use of the "menuutil.pl" utility routines. - Changed the demo scripts to favor working "out of the box" on Perl5 instead of Perl4 (package still works with both Perl4 and Perl5). - Changed GNU licensing to distribute under the "Library GNU Public License" (or the Artistic License) rather than the regular GPL (as in the past). ------------------- Perl4/Perl5 Aspects ------------------- This package uses an extension of "stock Perl" which incorporates curses library calls into the perl interpreter. How you build perl to include these calls depends on whether you are using Perl4 or Perl5. When using Perl4 you must use the pieces distributed in the "usub" directory of the Perl4 source distribution to link perl with a curses interface module which incorporates calls to the curses function library. When using Perl5 you must use William Setzer's "Curses" extension. Commented code is placed in "menu_init" for those systems with curses implementations that do not have a "getcap" call (or for those that have "tigetstr" instead of "getcap"). Read the "README" section for complete info. Feedback welcome. -------- Overview -------- For people who do not even know what "menu.pl" does for you, here is the "Overview" section from the MENU_DOC document included in the package. The "menu.pl" package is a perl package (built into your perl program with a "require menu.pl" command) that automates curses-based full screen menus and data entry. Using three simple calls, any number of items may be selected from a single or multiple-page menu by moving an arrow to the desired item (or directly entering the selection number displayed on the screen). In addition to simple "single one-shot selection menus", "radio button" style menus and "multiple-item-selection" menus are provided. Paging through multiple-page menus is handled automatically. Menu titles, sub-titles and prompts are supported. Using two simple calls a full-screen data entry template may be loaded and a fully-titled data entry input screen may be created. Defaults, maximum field lengths, and numeric-only data are supported. --- The "menu.pl" package uses curses interface routine calls supplied by the "curseperl" package (for Perl4) or the Curses extension (for Perl5). The "curseperl" package is distributed with the normal perl4 distribution in the "usub" directory. The "curseperl" binary is a complete perl interpreter with the addition of many "curses" routines dealing with screen manipulation (cursor positioning, display of text at the current cursor location, etc). Applications using "menu.pl" must be constructed to use "curseperl" instead of "perl". The "Curses" extension for Perl5 is maintained by William Setzer (of North Carolina State University). This package is available via anonymous FTP at: ftp://ftp.ncsu.edu/pub/math/wsetzer/Curses-a8.tar.gz When writing perl5/Curses programs make sure you include the following two lines at the start of your program (to initialize the Curses environment correctly): BEGIN { $Curses::OldCurses = 1; } use Curses; --- For menus, most applications using will use the following three calls (with the "menu_item" routine used multiple times to provide the menu selections) as follows: #!/usr/local/bin/perl5 BEGIN { $Curses::OldCurses = 1; } use Curses; ... &menu_init(1,"Select an Animal"); # Init menu &menu_item("Collie","dog"); # Add item &menu_item("Shetland","pony"); # Add item &menu_item("Persian","cat"); # Add last item $sel = &menu_display("Which animal?"); # Get user selection if ($sel eq "%UP%") { ... } if ($sel eq "dog") { ... } ... When this code is executed, only the call to "menu_display" will actually cause the constructed menu to be displayed to the user for selection. The title is centered and displayed at the top of the screen in reverse video. The selection items are automatically numbered and presented in the order they were added. The prompt is displayed at the bottom of the screen preceded by an indication of how many of the items in the menu are presented on the current screen ("All" or some percentage). In the above example, the menu would look like: Select an Animal -> 1) Collie 2) Shetland 3) Persian (All) Which animal? Only one menu may be active at a time. In applications with "layers" of menus, only the "current layer" menu is maintained in memory. As you use the "up" function to "pop up" to a previous menu, your application must return to a subroutine (or upper program layer) that reconstructs the menu for that layer of the application and displays it. Since the lower layer used a "menu_init" to construct that menu, the "upper layer" must reconstruct the entire menu appropriate at that level. Support is provided (with proper programming of the application) to go directly to the "top" (first) menu and to remember the selection position in a previous menu. --- For full-screen data entry, most applications using will use the following two calls: #!/usr/local/bin/perl5 BEGIN { $Curses::OldCurses = 1; } use Curses; ... @input_data = (); # Define a place to put the input data ... &menu_load_template("/path/to/template.file"); # Load template &menu_display_template(*input_data); When this code is executed, only the call to "menu_display_template" will actually cause the template to be displayed to the user for data entry. For example, assume the file containing the template looked like: Address Information Name: [_______________________________________________] Addr: [_______________________________________________] City: [______________________] State: [__] Zip:[_____] The call to "menu_load_template" would load and parse the template file for locations of text and data fields (data fields denoted by underscores). Optionally, the template can be loaded from a "template array", constructed within the Perl script itself. Templates stored in arrays (as opposed to files) are loaded with "&menu_load_template_array(...)". When "menu_display_template" is called, the user would see the following screen: Address Information Name: [ ] Addr: [ ] City: [ ] State: [ ] Zip:[ ] Field tabbing and insertion/deletion of text is handled by "menu_display_template" until the user hits "Return". Data values for each field are returned in $input_data[0] - $input_data[4]. Defaults, numeric-only, blanked, protected, and required fields are supported, along with the ability to parse and control user input while the "menu_display_template" is active via a user exit. -- Steven L. Kunz Networked Applications -- Microcomputer Networked Services Iowa State University Computation Center, Iowa State University, Ames, Iowa E-mail: skunz@iastate.edu