*/
                           Utility.m Module
                           ================

                         ©1996 Michael Sparks

Very Useful module this. Only one function, code included here. It is particularly
useful in debugging.

VAGUE OUTLINE DESCRIPTION
      text_request('Current Program State\n'+
                   'x: \d   y: \d  z: \d\n' +
                   'File Name: \s', 'Next Step|Abort|Skip Step',
                   [x,y,x,filename])

      In this example, clicking on...
            "Next Step" would cause the function to return 1
            "Abort"     would cause the function to return 2
            "Skip Step" would cause the function to return 0

      The buttons are numbered from left to right ascending from 1, except the
      rightmost, which is always numbered zero.

SIGNATURE
    result:=text_request(bodytext=0,buttons=0,arguments=0)

PARAMETERS
   bodytext : This is a standard string that will be used to fill the main
      contents of the requester. Can be spread over several lines and contain
      standard WriteF style argument/formatting codes.

   buttons : This is a string with several sub strings within it delimited by
      vertical bars - '|' - next to the backspace key on a UK keyboard. These
      should *NOT* contain any formatting information. The sub-strings when
      read from left to right will produce buttons in the same order on screen
      from left to right. The return code that this procedure returns depends
      on these buttons (see below).

   arguments : This is a list containing the information required by any of
      the formatting codes in the bodytext. eg if bodytext is 'x= \d' then
      this forms a bodytext that requires an integer value to fill it. If we
      were using this for debugging, the most likely contents of arguments
      would be [x] but [5] or [10] etc would be equally OK. If we were doing
      something strange, then ['wierd'] would be equally OK.

RETURN CODE(S)
   result : This is an integer value which, as mentioned briefly above, is
      based on the buttons argument. If the buttons argument contains more
      than one argument, then the result returned becomes useful. If there
      are n buttons, then the buttons (if numbered from left to right) 1 to
      n-1 return the value relating to their position in that sequence. The
      button on the far right (button n) always returns 0 however. This is
      because you often associate the far right option with a negative
      response, and this allows a simple control construct. eg
         IF text_request('bla','yes|cancel') THEN
               do_it()
         ENDIF   -> doesn't if you select cancel

EXAMPLE DEBUGGING USAGE
      If for instance you often write in your programs, for debugging purposes
      etc, the following:
          WriteF('x:\d y:\d xtrans:\d ytrans:\d\n',oldx,oldy,x,y)

      The you can write
         text_request('x:\d y:\d xtrans:\d ytrans:\d\n',0,[oldx,oldy,x,y])

 To get the same effect, but with a little more control, AND user friendliness.

EXAMPLE NORMAL USAGE
   Example1 - Program branch control
        result:=-1
        WHILE Not(result=0)
           result:=text_request('Select option!',
                                'Add|Amend|Delete|Search|Quit')
           SELECT result
              CASE 1; add_record()
              CASE 2; amend_record()
              CASE 3; delete_record()
              CASE 4; search()
           ENDSELECT
        ENDWHILE

   Example2 - Dangerous Act control
      IF text_request('Delete this person???\n\n' +
                      'Name: \s, \s\n' +
                      'Telephone: \s\n' +
                      'Address:\n\s\n\s\n\s\n\s\n\s\n',
                      'YES, Kill em!|NO! I like them!',
                      [p.name,p.tel,p.add1,p.add2, p.add3,p.add4,p.add5])
         delete_person(p)
      ENDIF

   Example3 - Error Notification
      PROC error(library_name)
         text_request('Sorry, the program has died, and is destroying\n'+
                      'your hard disk due to the fact that I can''t find\n'+
                      'the following file:\n \s\n\n in your LIBS: directory',
                      'ARRRRGGGGGHHHHH!!!!!!',
                      [library_name])
         Raise("dead")
      ENDPROC

BUGS
    >>  Does not fall back to a recoverable alert if the requester cannot
    >>  cannot be created.

    >>  Does not handle case when gadgets don't fit or window title
    >>  is too long, although it does trim trailing spaces from the
    >>  title for calculating dimensions.

      This text above is from the autodocs for the library function used...

Again, as with all modules documented in this directory, this is all subject
to change! I personally find this function quite useful!