                             RequestList v1.1
                                Adam Dawes
                            16th November, 1995



What is RequestList?
======================

RequestList is a little utility designed to complement the Commodore
utilities, 'RequestChoice' and 'RequestFile', primarily of use in AmigaDos
and AREXX shell scripts.

The program displays a requester containing a list of text items, taken
from a file you specify when you run it. When the user selects one of the
text items by clicking on it, either the line number for that entry, or the
actual text of that entry, will be printed to stdout (so it's very
convenient to redirect the output of RequestList to an environment
variable).

If the user closes the window instead of clicking on a list item, the value
'-1' (or an empty string if you have requested the item text) is returned.



Using RequestList
=================

The parameter template for RequestList is as follows:


      TITLE/A,LISTFILE/A,PUBSCREEN/K,FULL/S,WIDTH/N,HEIGHT/N,LINES/N


         Title: The name that will be given to the window that opens
                containing the list requester. (Required)

      ListFile: The name of a file containing carriage-return seperated
                items to be included within the list. (Required)

     PubScreen: Allows you to specify a public screen for the requester to
                open upon.
     
          Full: If this switch is specified, RequestList will print the
                actual text string that is selected, rather than its line
                number.

         Width: Specifies a requested width for RequestList's window. If
                the width specified is too large to fit on the screen,
                the window will open at the maximum screen width.

        Height: Specifies a requested height for RequestList's window. The
                window may not open at exactly the requested height, as the
                window fits itself around the ListView gadget inside it,
                which in turn must exactly fit the font of the text
                displayed. If the height specified is too large to fit on
                the screen, the window will open at the maximum screen
                height.

         Lines: Specifies the desired number of text lines to be displayed
                in the ListView gadget. The window height will size itself
                to fit around the list automatically. If both the HEIGHT
                and LINES paramaters are used when RequestList is called,
                the LINES parameter overrides the HEIGHT.


If you wish to make RequestList's window open completely full-screen,
regardless of the actual screen size and resolution, specify very large
values for the width and height. RequestList will scale them down to fit
the screen the window is opening on.



Requirements
============

RequestList requires Kickstart 2 or greater.



Legal stuff
===========

RequestList is freeware. It may be distributed however and wherever you
like.

I accept no responsibility for any damage done to your system, directly or
indirectly, as a result of using RequestList. You use the program entirely
at your own risk.



History
=======

  v1.0 (39.0) 15/9/95

        Initial release.

  v1.1 (39.1) 15/11/95

        RequestList now only makes a single pass through the specified
        file to make its text list. This means that it can be used with
        devices that do not support file seeking (for example, the PIPE
        device, and the FTPMount utility).

        RequestList is now fully font sensitive.

        Added new parameters: FULL, WIDTH, HEIGHT and LINES.



Bugs
====

None known -- please contact me if you find any.



Contacting the author
=====================

Please do write to me if you like RequestList or if you have any problems
with it or suggestions for a new version. I can't promise to reply quickly
if you write via snail-mail, but I will always reply to email messages. I
can be contacted at:

  InterNet
     ad32@brighton.ac.uk

  FidoNet
     Adam Dawes@2:441/93.5

  SnailMail
     Adam Dawes
     47 Friar Road
     Brighton
     BN1 6NH
     England



See Also
========

I have also written another utility that complements this and the Commodore
'Request' commands. 'RequestString' is available from Aminet as
'util/batch/requeststring.lha', and provides a simple and easy way to
prompt the user to enter some text from within a script. Amongst other
things, the requester can have a default string already entered, and may
have text entered invisibly (for passwords, etc.).

