                                 menuutil.pl
                         Perl Menu Support Utilities
                                 Version 1.0
                              January 17, 1995

                               Steven L. Kunz
                           Networked Applications
                  Iowa State University Computation Center
                            Iowa State University
                                 Ames,  Iowa
                  
--------
Overview
--------

  After writing several curseperl programs which used menu.pl I learned there
  was often a set of utility routines that I used in each program.  I
  eventually collected these in a module ("menuutil.pl") which I included in
  each source.  These routines provide titles, text display, and prompting -
  all the while maintaining global row and column positions. 

  These routines are probably best understood by studying the "demo_util"
  program supplied in this distribution.  In any case, some routines rely on
  standard "menu.pl" routines (menu_getstr, specifically) so you add 'require
  "menuutil.pl";' to existing Perlmenu programs. 


-------------------------
Solicitation for Comments
-------------------------

  If you have found a bug, documentation problem, or would really like to
  see a new utility routine (or have one you think could be added), feel free
  to let me know.  Send your e-mail cheers/jeers to "skunz@iastate.edu".  


---------------------
Text Display Routines
---------------------

  ----------
  Routine:      top_title

  Syntax:       &top_title("Title string");

  Input args:   String for the title

  Returns:      Nothing

  The "top_title" routine clears the main window and centers the title
  string on the top line.  The title is normally presented in "standout"
  rendition.  Normal rendition may be forced by placing a dash ("-") as
  the first character.

  Titles longer than the screen width will be truncated.

  ----------
  Routine:      print_nl

  Syntax:       &print_nl("Text string",new_line_count);

  Input args:   - Text string to put at cursor location
                - Number of new-lines to add afterwards

  Returns:      Nothing

  The "print_nl" routine adds text to the screen, maintaining row and col
  locations.  If the text rolls past the bottom of the screen, the screen
  is cleared and text starts again at the top.  Automatic line-wrap is
  handled.

  ----------
  Routine:      new_line

  Syntax:       &new_line(new_line_count);

  Input args:   Number of new-lines to add

  Returns:      Nothing

  The "new_linel" routine adds blank lines to the screen, maintaining row and
  col locations.  If the action rolls past the bottom of the screen, the
  screen is cleared and action starts again at the top.  This routine is
  useful if you use "menu_getstr" to input data and want to bump the cursor
  down to the next line after the user hits "Return". 

 
------------------
Prompting Routines
------------------

  ----------
  Routine:      query

  Syntax:       &query("Prompt text","allowed_values");

  Input args:   - Prompt text string
                - Allowed values string

  Returns:      Single character from "allowed_values"

  The "query" routine takes the prompt text and appends the list of values
  allowed (reformatted in "user-friendly format").  For example, if the
  following were supplied:

    $val = &query("Delete file?","yn?");

  what the user would see would be:

     Delete file? (y|n|?)

  If a value other than "y" or "n" or "?" was supplied the routine will
  automatically indicate the error and re-prompt until a proper value is
  supplied.  When the routine returns you are assured that the value
  returned is one of those in the "allowed_values" string.

  ----------
  Routine:      pause

  Syntax:       &pause("Prompt text");

  Input args:   Prompt text string
                Optional.  Defaults to "[Press any key to continue]"

  Returns:      Nothing

  The "pause" routine moves to a new line, supplies the prompt, and pauses
  until any key is pressed.

  ----------
  Routine:      popup_ask

  Syntax:       &popup_ask("Prompt text",max_len,"Default string",
                           hidden_flag,numeric_flag);

  Input args:   Note: All parms are optional
                - Prompt string
                - Maximum data input length
                - Default value string
                - Boolean flag (0=show, 1=hidden)
                - Boolean flag (0=alpha-numeric, 1=numeric)

  Returns:      Nothing

  The "popup_ask" routine builds a popup dialog box in the center of the
  screen.  Calculation of the box size and position is automatic (based on
  the length of prompt and maximum data length).  If no parameters are
  supplied a box the width of the screen (with the maximum size data area)
  is built.

  A default value (pre-loaded in the data area) can be supplied.  The 
  "hidden_flag" allows for password-style prompting.  The "numeric_flag"
  indicates that only numeric digits (0-9) are allowed.


--------------
For the record
--------------

Copyright (C) 1992-95  Iowa State University Computation Center
                       Ames, Iowa (USA)

menu.pl is free software; you can redistribute it and/or modify it under the
terms of the GNU General Public License as published by the Free Software
Foundation; either version 1, or (at your option) any later version.

menu.pl is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public License along with
menu.pl.  If not, write to:

  The Free Software Foundation
  675 Mass Ave
  Cambridge, MA 02139, USA

