Subject: ANNOUNCE: PerlMenu version 3.3
From: [email-masked] (Steven L. Kunz)
Date: 21 Feb 1996 21:39:24 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.misc

---------------------------------
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: [email-masked]