perlmenu.pm Perl Menus Version 4.0 Release Notes February 17, 1997 Steven L. Kunz Networked Applications Iowa State University Computation Center Iowa State University Ames, Iowa Copyright (C) 1992-97 Iowa State University Computation Center Ames, Iowa (USA) Changes between perlmenu.pm version 4.0 and menu.pl version 3.3: - Converted to Perl5-style "perlmenu.pm" module. A program (create_menu.pl) is included to convert this module to the old Perl4-style "menu.pl" module for legacy applications and Perl4+curseperl users. All old PerlMenu programs should run without changes using this new "menu.pl" module. Conversion to use "perlmenu.pm" under Perl5 should only require changing "require" to a "use". - Added multiple-column menu support (requested by many people). Single call to "menu_prefs" converts all menus to "multiple column" selections. No changes to existing menu construction routines in old code required. Automatically scales and computes proper number of columns based on length of longest selection text. - Added a "highlighted" selection cursor preference. Previous versions only displayed the selection cursor with a "->" in front of the item. A new preference setting removes the "->" and highlights the selection text (in reverse video on most systems). Single call to "menu_prefs" converts all menus to "highlighted" selections. - Expanded the main "demo" program to enable switching between single and multiple column menus, arrowed or highlighted selection cursor, numbered and unnumbered menus. - Split out (and rewrote) the installation instructions into a new file called "INSTALLATION". Included a new "install_hints.pl" program (for Perl5+Curses users) which tries to figure out what tweeks you may need to make it work on your system. - Made appropriate changes to all other documentation as appropriate for the new features. - Added a new "FAQ" document. - Fixed a bug in that relates to typing an item selection number that is greater than the last item in the menu. Previously it dropped the selection arrow to the last item but crashed when you pressed "return". Now it "beeps" (to indicate an invalid selection). Thanks to Jay Fowler (CSU-Fresno, USA) for pointing this out. - Fixed bug in demo scripts. Previous versions were missing some calls to "endwin" prior to every "exit", which meant the original terminal environment was not restored (leaving the terminal in "raw" mode, etc.). Thanks to Warren Jones (Fluke Corporation, Everett, WA, USA) for the bug report and patches. - Added comment for HP-UX 9.05 terminfo/tput users in perlmenu.pm ("tput kent" does not work on these systems, use "tput cr"). Thanks to Stuart Poulin (Applied Microsystems Corporation, Redmond, WA, USA) for supplying this info. Changes between menu.pl version 3.3 and version 3.2: - 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. Thanks to Trey Harris (University of North Carolina at Chapel Hill) for suggesting this idea. - 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). Changes between menu.pl version 3.2 and version 3.1: - Added support for required fields to the "template" facility. This new support greatly simplifies coding data-entry routines with required fields. New parameters to "menu_display_template" allow automatic insertion of required field markers at one end (or each end) of required fields. New parameter supplied to your "template exit" routine indicates how many required fields remain to be filled in by the user. The required field markers can be changed via a new "menu_template_prefs" call. - Rewrote the "ezreg" demo to take advantage of the new "required field" template support. - Added Control-L screen refresh control key for template input. - Added "current cursor location latch" to input fields in a template. Now when you tab between fields on a template it returns to the cursor location you left (from within each window) when you return to it. - Fixed a bug in the menu subtitle support. When a subtitle routine was returning "null" (no titles), the titles already in the title array were not cleared. The first line of the old menu subtitle would not go away. Changes between menu.pl version 3.1 and version 3.0: - Added ability to set additional exit-key sequences for templates (via a new "menu_template_setexit" routine). Thanks to Christopher Candreva (WestNet Internet Services of Westchester). - Added ability to specify a routine address (instead of a raw string) for top/bottom subtitles on the "menu_init" call. The called routine must return the string to be used as the subtitle(s). Thanks to Christopher Candreva (WestNet Internet Services of Westchester). - Added a new "menu_pref" item to disable the "quit" ("Q") hot-key. Suggested by a couple people - the latest being Karsten Thygesen (Aalborg University, Denmark, Institute for Electronic Systems). - Fixed a return-code bug in "menu_load_template" (was not returning zero upon success as advertised). Thanks to Karsten Thygesen (Aalborg University, Denmark, Institute for Electronic Systems). - Fixed a bug in "menu_getstr" which cleared the default if it was not specified with a "maximum length" value. Thanks to Karsten Thygesen (Aalborg University, Denmark, Institute for Electronic Systems). - Changed demos to not use poor curses programming practices (like using stdio calls such as "print" and ""). - Added patch for Perl 5.000 and Perl 5.001 compatibility using the Curses extension. Thanks to William Setzer (author of the Perl5 Curses extension). Changes between menu.pl version 3.0 and version 2.3: - Added full-screen data entry support. New calls of "menu_load_template" and "menu_display_template" are used to load an easy-to-define data entry template. Alpha-numeric, numeric, hidden fields are supported. Multiple fields allowed per screen (and per line). Preliminary work done by Christopher Candreva (WestNet Internet Services of Westchester) provided a base for this development (Chris provided the menu_setexit and menu_getexit code to which I added the template routines). Alan Cunningham (NASA Spacelink Project) provided most of the design requirements for the exit routine support. - Added support for bottom titles (augmenting the existing top "sub-titles"). You can now have text above and below the menu. - Added a new "menu_paint_file" routine to load top sub-title and bottom titles from a file. Provides the ability to place large blocks of text associated with a menu in an "off-board" file where it can be easily edited and changed. This technique is optional - titles can still be loaded in the "menu_init" call. - Added a new "menu_prefs" call to allow setting certain global prefs for all menus. Currently you can indicate that you want all menus centered on the screen (instead of left-justified), and you can indicate you want more "gopher-like" action for the arrow keys. Thanks (again) to Chris Candreva for the centering code and idea for the arrow-action. - Added new optional parm to the "menu_item" call to allow specifying an item as "pre-selected" (changeable or non-changeable). - Added lots of optional parameters to menu_getstr to allow default values, maximum lengths, "noshow" values (for passwords), and numeric-only entry. Thanks (again) to Chris Candreva. - Added a "menuutil.pl" module with some useful curseperl routines to be used in PerlMenu programs. Includes a User's Guide. - Fixed a bug in the menu page display that caused an extraneous "bump up" of the menu when a down-arrow was pressed on the last page of a multiple page menu (and the last item was on the last line). Whew! - Fixed a bug in the return value from "menu_init". It previously returned one too few for the number of items currently in the menu. Thanks to Ian Phillipps. - Fixed a bug causing tight loops when the calling process went away (i.e. a terminal user hung up). If a menu prompt was active the null return value was not detected. Should also be handled by user signal trapping (within their code) for complete control. - Fixed a bug that caused an unnecessary screen repaint when pressing "U" ("up") at the top menu. Thanks (again) to Chris Candreva. - Fixed problems relating to Perl5 (subroutine calls with no parms called as "&rtn;" instead of "&rtn();"). Also added commented code for systems that use "tigetstr" (terminfo data) instead of "getcap" (termcap). Thanks to Jim Sumrall (Intel Corporation) and William Setzer (author of the Curses extension for Perl5). - Made arrow-movement much more CPU efficient. - Spiffed up the "ezview" demo to show how multiple file selection in a directory would work. - Added an "ezpasswd" demo as an example of full-screen template display of a BSD-style "/etc/passwd" file. - Changed "menu_getstr" to default to "overstrike" mode on single character data entry fields. - Added "emacs-similar" cursor movement/cut-paste control sequences to menu_getstr and menu_display_template. Thanks to Charles F. Randall of Iowa State University. Compatibility Note: There is ONE old call that has a new required operand. The "menu_curses_application" routine previously had no operands. With this version, you must pass in the value of the base window you got from the "initscr" call. So, if you called "menu_curses_application" in the past after you called "initscr" yourself, you should make your code look like: $window = &initscr(); &menu_curses_application($window); Changes between menu.pl version 2.3 and version 2.2: - Fixed a bug in the order of calls to "menu_return_prep" and "menu_exit_routine" when "quit" was being processed. The "menu_return_prep" routine is now called FIRST, so that it's processing can be done before a possible call to "endwin" in the user's "menu_exit_routine". This change also means that the processing in "menu_exit_routine" is truly the last code executed prior to exit. Thanks to Tim Goodwin. - Fixed a bug in "normal" applications (ones that do not call "menu_curses_application"). The "initscr" routine was previously called on each "menu_init" (in direct violation of the curses documentation). This caused no obvious problems on some systems (such as DEC ULTRIX) but many problems on others (such as Sun and other System V systems). Thanks to Steve Mitchell at CSU/Fresno. Changes between menu.pl version 2.2 and version 2.1: - Add menu subtitle capability. Changes between menu.pl version 2.1 and version 2.0: - Several bugfixes provided by Greg Kresko (National Research Council Canada). Greg found some problems with "endwin" statement placement (or lack thereof). Also suggested some minor changes to the demo programs. Changes between menu.pl version 2.0 and version 1.4: - Added multiple selection capability (new "menu_display_mult" call). Includes new menu options "a" (select "all"), "m" (select based on a string "match") and "c" ("clear" all selections). - Added "radio button" selection capability (new "menu_display_radio" call). - Removed "f" and "b" ("forward" and "backward") as page movement. Replaced by existing (but unadvertised) "n" and "p" ("next" and "previous" page). - Added "b" and "e" ("begin" and "end") as fast page movement to the items at the beginning and end of a menu. - Added "h" to provide a help screen explaining all available menu actions. - Changed default menu prompt formats. - Added ability to let users spawn off a sub-shell (and get a command prompt) from any menu (using the "!" hot-key) and later continue (upon shell exit). This feature is normally disabled. - Added "menu_getstr" utility routine call (lets you get a string from std input with C-shell-like editing) - Documentation changes (new features, some typos) Changes between menu.pl version 1.4 and version 1.3: - Added "r=refresh" to bottom menu line (when it fits). - A few (minor) documentation changes Changes between menu.pl version 1.1 and version 1.3: - Fixed bug in the "numeric direct entry code". Once a number was entered it was not cleared if an arrow key was used to move the pointer off the selection. - Added the "top menu" feature. Allows for a "t" ("top") menu hot-key to move to the top (first displayed) menu. - Added the "latched" menu feature. Allows calls to "menu_display" to have two additional parameters that remember the screen/arrow location upon return from the call. When recalling "menu_display" (with the same parameters) the menu will be restored to the original location/selection. Changes between menu.pl version .9 (beta) and version 1.1: - Declaration of "curses_application" fixed ("main`" prepended). - Cleanup of "cbreak" and "echo" handling. Calls to "menu_display" always return with "echo" and "cbreak" set. - Return key now functions on systems that do not have termcap entries for either a "newline" or "return" key. - "menu_display" will return "%EMPTY%" if no calls to "menu_item" were done between a "menu_init" call and a "menu_display" call. - Hitting the "space bar" is now the same as "f" or "n" for forward movement within a multi-page selection menu. - The title strings in "menu_init" calls can now begin with a "-" to suppress the "standout" attribute (normally a bold or reverse-video rendition). - menu_display will no longer return "%QUIT%" - returns "%UP" instead. The menu routines process a "q" (for "quit") locally and will exit from there (after the user responds to a "Do you really want to quit?" prompt). - Direct number entry for selecting entries "pops" the arrow to the "best fit" selection on the screen, indicating what selection will be made when return is hit. - The "ezview" demo now displays the correct modification date on its file display. --- Steven L. Kunz Networked Applications Iowa State University Computation Center, Iowa State University, Ames IA INET: skunz@iastate.edu