
                                                       Wuerzburg, 03-Feb-93

                                ReqASK 1.0

                           English Documentation



Disclaimer
~~~~~~~~~~

  ReqASK  (and  all files related to it) are Copyright 1993 by Marc Heuler,
all rights reserved.  This program is Shareware.  If you like it and use it
a lot, please pay the Shareware fee of 10.- DM (or $7 US).

  You may freely distribute ReqASK by these conditions:

         Don't take *anything* for copying, except the cost of the media
          itself

         Do not change any of the files related to this program

         Distribute all related files at once, packed into one archive

         German PD-Serials are not allowed to distribute this program

         Fred Fish with his famous software library does *not* have to
          care about all these conditions.

  This  program  is  "AS  IS",  which  means you use it at your *own* risk.
There's  no warranty at all.  However, we've tested it a lot and think it's
reliable.

  Many  thanks  to  Michael  Herold,  who  helped  me both beta-testing the
program and creating the AmigaGuide documentation.



What is ReqASK?
~~~~~~~~~~~~~~~

  ReqASK  is a powerful mouse-driven replacement for the shell command ASK.
It's  supposed  to  prompt the user with several choices.  According to the
result,  a  certain  action  can be taken.  Unlike similar programs, ReqASK
gives you a large palette of features to customize to fit your needs.

  This  program  supports  and requires Kickstart 2.04 (v37) or higher.  It
also requires "reqtools.library" (by Nico Franois) v38 or higher, which is
available by FD (for example on Fish-Disk 794).



Usage
~~~~~

  ReqASK is a CLI/Shell tool, therefore it doesn't make real sense to start
it from Workbench.

   BODY/K

          This  is  the body text of your requester.  If you leave out this
        option,  all  others will be ignored and an About requester will be
        shown.

          You  may use all common control sequences in this string, such as
        *N  for a new line, or *" for quotes.  Look up your AmigaDOS manual
        for more detailed information.

   GADGET/K

          This  option  is  used  to  define  the gadgets' texts.  Separate
        several  choices  by  the  "|"  sign.   Examples  are  "Yes|No", or
        possibly "Yes|Maybe|No".  Maximum number of choices is 100.

          If you like your requester keyboard-controllable, use underscores
        to indicate the corresponding keys to press ("_Yes|_Maybe|_No").

          Please  note  that  the  requester  cannot be put up, if you don't
        specify  minimum one of the options GADGET, IDCMP, and TIMEOUT.  You
        won't  be  able to answer such a requester, therefore it doesn't pop
        up.

   TITLE/K

          This is the requester's title.  If you don't specify this option,
        the title will be either "Information" (if less than 2 gadgets), or
        "Request" (two or more choices).

   VAR=VARIABLE/K

          Specify   an  environment  variable  here.   The  result  of  the
        requester  will  be  stored  in  the  variable.  The default result
        variable is called "REQASK".

   GLOBAL/S

          If  you  specify this keyword, the result variable will be global
        (not limited to the current process).

   TIME=TIMEOUT/N/K

          This  is  one  of the main features of ReqASK.  You may specify a
        timelimit  after  which  the requester will automatically close (if
        the user didn't select any choice already).  The unit is seconds.

          Please  note  that  the  requester  cannot be put up, if you don't
        specify  minimum one of the options GADGET, IDCMP, and TIMEOUT.  You
        won't  be  able to answer such a requester, therefore it doesn't pop
        up.

   SCREEN=PUBSCREENNAME/K

          Name  of  a public screen to open the requester on.  If you don't
        specify this option, the requester will open on your Default Public
        Screen.  Usually this is the Workbench screen.

   FRONT=SCREENTOFRONT/K

          If  you set this option to "YES" or "ON", the screen on which the
        requester  opens  will  pop  to front.  After the user made his/her
        selection, the screen will go back saftely to where it was before.

          To disable this option, select "NO" or "OFF".

          If  you  don't  use  this  keyword  at all, the default behaviour
        configured in reqtools' preferences editor will take place.

   CENTER=NOCENTERTEXT/S

          ReqASK automatically centers the body text of your requester.  If
        you don't like this, disable it by mentioning this keyword.

   DEFRES=DEFAULTRESPONSE/N/K

          If  you  have  several gadgets in your requester, the leftmost is
        handled  as  'positive'  -  as default response.  It is selected by
        simply  pressing  the  Return  key.  To have another (not leftmost)
        gadget be the default response, specify the gadget's number here.

          The default response will be rendered in bold letters.

   FONT/K

          Your  requester  normally  uses the screen font for rendering all
        texts.   To  use  another  font,  simply state the fontname and the
        desired  size.   For  example FONT="courier.font 13" will result in
        using  the  courier  font, size 13.  Note to surround font name and
        size with quotes.

   POS=POSITION/K

          Like  the  SCREENTOFRONT  option  before, leaving out this option
        will  lead  to  behave  like  configured  in  reqtools' preferences
        editor.   Use  this  option to change the default behaviour of your
        requester.  You may specify one of the following possibilities:

                POINTER         The requester will pop up at the
                                current mouse position

                CENTERSCREEN    The requester will be centered in
                                the visible part of your screen

                TOPLEFTSCREEN   The requester will appear at the
                                top left edge of the visible part
                                of your screen

   LEFT=POS_LEFTOFFSET/N/K

          If  you  specified  a  certain  requester  position  (other  than
        POINTER),  you  may  set a horizontal offset  to that position.  If
        you  don't specify it, the default out of the reqtools' preferences
        editor will be used.

   TOP=POS_TOPOFFSET/N/K

          If  you  specified  a  certain  requester  position  (other  than
        POINTER),  you  may set a vertical offset to that position.  If you
        don't  specify  it,  the  default  out of the reqtools' preferences
        editor will be used.

   RETURN=NORETURNKEY/S

          If you don't want your requester to be answerable with the Return
        key, specify this option.

   LAMG=LAMIGAONLY/S

          For  functions  which may cause serious damages you might wish to
        disable  the abbreviated selection of choices.  Set this keyword to
        disable  these.   You  then  have to press the left Amiga key along
        with "B" or "V" for positive or negative selection.

   IDCMP/K

          This  is  another  wonderful  feature of ReqASK.  You may specify
        certain IDCMP flags which cause the requester to end automatically.
        You can choose one or more of these IDCMP flags:

                DISKINSERTED    A disk was inserted into any drive

                DISKREMOVED     A disk was taken out of any drive

                INACTIVEWINDOW  The requester window got deactivated

          Please  note  that  the  requester  cannot be put up, if you don't
        specify  minimum one of the options GADGET, IDCMP, and TIMEOUT.  You
        won't  be  able to answer such a requester, therefore it doesn't pop
        up.

   BEEP=DISPLAYBEEP/S

          If you start requesters from background processes, you might wish
        be  to  notified  about  a  requester.   To  DisplayBeep() when the
        requester pops up, specify this option.



ReqASK Result
~~~~~~~~~~~~~

  The  result of ReqASK is split into two parts.  One is the CLI Returncode
which  indicates  success or failure of ReqASK.  A Returncode of 0 means no
errors occured, while a Returncode of 20 states errors (normally along with
a more detailed error description to StdOut).

  The second and more important part of the result (in case of no failures)
is  the Result Variable holding information about which gadget the user did
choose.   A  value of 0 always indicates the right-most (FALSE) gadget, the
others are numbered from 1 to N, heading from left to right.

  There  are  two  special  values.  A result of 100 means, the user didn't
react on the requester until the timelimit expired, the value 101 indicates
the requester was closed by an IDCMP event.

NOTE:   In  case of an error (Returncode = 20) the result variable will not
        be touched by the program.



Examples
~~~~~~~~

  Simply type these examples into your shell to see what happens:

ReqASK

ReqASK BODY="This requester reminds you*Nabout your Grandma's birthday" GADGET="_Okay" TITLE="Don't forget"

ReqASK BODY="Current system time is*N`Date`" TIME=10

ReqASK BODY="Remove ALF2-Bootdisk now!" IDCMP=DISKREMOVED POS=CENTERSCREEN



History
~~~~~~~

ReqASK 1.0  03-Feb-93  First public release



Future enhancements
~~~~~~~~~~~~~~~~~~~

  Only  thing  I  plan  to  add to ReqASK so far is ARexx support.  This is
useful  when  for example playing samples in conjunction with UPD while the
requester pops up.

  On the other hand I think about expanding the series of ASK commands, for
example  a  very  powerful  FileASK,  which  asks  you  for files (via file
requester).   Or  ViewASK,  which gives you a large amount of choices via a
listview gadget.

  There  are many small things to be done.  If you like to see them, please
support my work by paying the Shareware fee.



Contacting the author
~~~~~~~~~~~~~~~~~~~~~

  To  send  bug-reports,  ideas,  complaints,  and of course your Shareware
registration fee of 10.- DM (or $7 US), contact me at:

        UUCP eMail: marc@aargh.adsp.sub.org

        ZNet eMail: marc%aargh.incubus@aworld.zer

        Snail Mail: Marc Heuler
                    Stephan Str. 6
                    8700 Wuerzburg
                    GERMANY

  Don't forget to pay the Shareware fee if you use ReqASK a lot!


                                                                       Marc

