home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d9xx / d928 / mrchoice.lha / MRChoice / MultiRequestChoice.doc < prev    next >
Text File  |  1993-10-07  |  9KB  |  245 lines
  1.  
  2.                           MultiRequestChoice
  3.  
  4.                      Release 1.0 - 01 August 1993
  5.  
  6.                             Documentation
  7.  
  8.  
  9.  
  10.  
  11.                       Written by Rainer Scharnow
  12.                 Copyright (c) 1993 by Rainer Scharnow
  13.  
  14.  
  15.  
  16.  
  17.    0. Introduction
  18.    ~~~~~~~~~~~~~~~
  19.  
  20.       MultiRequestChoice is a requester utility for the C: directory.
  21.    It  has  been  designed  as a powerful and comfortable replacement
  22.    for  ASK  and other present requester utilities. It is very useful
  23.    for  both  batch  files and ARexx scripts. Here are the advantages
  24.    of MultiRequestChoice:
  25.  
  26.    -  It  is  very simple to build requesters from one up to
  27.       your personally wished number of response gadgets
  28.  
  29.    -  It  uses  the  fabulous  reqtools.library  (c) by Nico
  30.        François,  therefore  all  features has been very easy
  31.        to realize and are contained in relative small code
  32.  
  33.    -  The  body  text  of  the requester may consist of more
  34.       than one line by using a newline character
  35.  
  36.    -  The  body  text  of  the  requester  may be optionally
  37.       left oriented or centred
  38.  
  39.    -  The  requester  may  appear on every public screen via
  40.       PUBSCREEN option
  41.  
  42.    -  The  position  of  the requester on the desired screen
  43.       may be controlled optionally
  44.  
  45.  
  46.    1. Requirements
  47.    ~~~~~~~~~~~~~~~
  48.  
  49.       MultiRequestChoice  doesn't  run under OS 1.x; all people using
  50.    these  old  versions should think the system upgrade over. Besides
  51.    there must be the reqtools.library V38+ in the libs: directory.
  52.  
  53.       It  should  run  on all Amigas with all 680x0 processors (I did
  54.    not need special hardware-near tricks to pop up a requester :-)).
  55.  
  56.  
  57.    2. Usage
  58.    ~~~~~~~~
  59.  
  60.       MultiRequestChoice  is a CLI-only program. Developed as a batch
  61.    and ARexx supporting utility it's a little bit senseless to run it
  62.    from  the  Workbench.  I think, you've already guessed it ;-). Ok,
  63.    here is the usage of MultiRequestChoice:
  64.  
  65.    MultiRequestChoice <Reqtitle> <Bodytext> <Gad1|Gad2|...|Gadx>
  66.                       [PUB|PUBSCREEN <Pubscreenname>]
  67.                       [CENTRETEXT]
  68.                       [SCREENTOPLEFT|SCREENCENTRE|MOUSECENTRE]
  69.  
  70.       MultiRequestChoice  won't  become  active if you pass less than
  71.    three  parameters.  In  that case it will print out the usage once
  72.    again. The three necessary parameters will be:
  73.  
  74.    -  Reqtitle  -
  75.        the title of the requester
  76.  
  77.    -  Bodytext  -
  78.        the  text  contained in the requester body in order to
  79.       inform the user about the situation. A special feature
  80.       is  the  possibility  to  use the C like format string
  81.       '\n'  in  the  text. This allows you to split the text
  82.       into  several lines  -  it is a newline option. If you
  83.       want  to  print  out a single '\' in your bodytext you
  84.       must simply pass '\\'. But see the examples...
  85.  
  86.    -  Gad1|Gad2|...|Gadx  -
  87.        the  gadget(s)  parameter. In the requester may appear
  88.       from  one  up to ... gadgets as already mentioned. The
  89.       gadget  names  are  separated by a '|'. That tells the
  90.       requester  simultaneously  how  many  gadgets the user
  91.       wishes.   Besides  a  keyboard  shortcut  response  is
  92.       supported.  A  '_' inserted before the provided hotkey
  93.       character in the gadget string will allow you keyboard
  94.       action. But see the examples...
  95.  
  96.       In  99%  of all cases some space characters are situated in the
  97.    strings.  You  can  solve  the problem if you quote the parameters
  98.    with the '"' character. But this is clear, I think...
  99.  
  100.       Finally,  there  are some useful options making the user's life
  101.    easier:
  102.  
  103.    -  It  doesn't  matter  if  you  write  PUB or PUBSCREEN;
  104.       the  meaning  is  the  same.  This  option requires an
  105.       argument  -  of  course  the  name of the PublicScreen
  106.       the  requester  should  appear  on.  If  there isn't a
  107.       PublicScreen  of  this  name  the  requester  pops  up
  108.       on  the  Workbench  so  if  you  would not handle this
  109.       option
  110.  
  111.    -  It  is  CENTRETEXT's  turn  to  centre the text in the
  112.       requester   body.  It  is  only  useful  if  there  is
  113.       multi-line-text   to   process  because  one-line-text
  114.       will  always  be  centred  in  the  body.  Default is:
  115.       left oriented text
  116.  
  117.    -  The    SCREENTOPLEFT|SCREENCENTRE|MOUSECENTRE   option
  118.       decides   where  on  the  screen  the  requester  will
  119.       appear.  Default  is:  MOUSECENTRE.  I think each part
  120.       of  the  option  will  explain  itself by its name. If
  121.       not clear - see the examples...
  122.  
  123.  
  124.    3. Return codes
  125.    ~~~~~~~~~~~~~~~
  126.  
  127.       All the work would be for nothing if there weren't return codes
  128.    produced  by  clicking the response gadgets. Well, the result will
  129.    go to the system's $RC environment variable or if you use ARexx to
  130.    the ARexx RC variable. Following rules exist:
  131.  
  132.       In the case of more than one gadget the rightmost is (according
  133.    to  Commodore's  specification)  the  one  of  the  most  negative
  134.    response  and clicking this will always give back '0'. In the case
  135.    of  an  one and only gadget the requester has only the function of
  136.    informing  the user about something, and a return value has got no
  137.    meaning.
  138.  
  139.       The  leftmost gadget will always give back '1', the next (which
  140.    should not be the last in this example) will return '2', the third
  141.    '3' and so on. Simple, isn't it?
  142.  
  143.       Finally,  if MultiRequestChoice couldn't find a system resource
  144.    (such as the reqtools.library) it will give back '200'.
  145.  
  146.  
  147.    4. Examples
  148.    ~~~~~~~~~~~
  149.  
  150.       Why should I do the work twice? There are in this directory two
  151.    demos:  MRCDemo.bat  and  MRCDemo.rexx.  Almost  all  the possible
  152.    effects  of  the  requester  are offered you in these demos. Demos
  153.    explain   more   than   words!   First   you  have  to  change  to
  154.    MultiRequestChoice's  directory.  If  you  want to run MRCDemo.bat
  155.    type  'execute MRCDemo.bat'  or type 'rx MRCDemo.rexx' if you want
  156.    to start the ARexx demo.
  157.  
  158.       See the "code" ;-) of the demos. Both are not commented because
  159.    they are really simple and self-explaining.
  160.  
  161.  
  162.    5. Copyright
  163.    ~~~~~~~~~~~~
  164.  
  165.       Copyright (c) 1993 by Rainer Scharnow
  166.  
  167.       I,  Rainer  Scharnow, give my permission to make and distribute
  168.    verbatim copies of this manual. All the copyright notices and this
  169.    permission must be part of these copies.
  170.  
  171.       There  is  no  guarantee  that the program(s) described here in
  172.    this  manual  works 100% ok. You will use this/these program(s) at
  173.    your  own risk. If any damages occur in connection with this/these
  174.    program(s) the author can't be made responsible or liable for it.
  175.  
  176.       This  package  is freely distributable, but copyright by Rainer
  177.    Scharnow.  You  may  copy and use this package as long and much as
  178.    you  want  if  a  copy  fee  including  disk  price  of  DM 5,- or
  179.    (referring   to  mail-order  abroad)  US$  6,-  is  not  exceeded.
  180.    Exception: laser disks, CD ROM.
  181.  
  182.       It  is permissed explicitly to include this package into public
  183.    domain  series, f.i. Fish-Library, and to upload it to BBS and FTP
  184.    servers.  All  the  files counted out in the Contents section must
  185.    be contained.
  186.  
  187.       No  program  of  this  package  may  be  part  of  a commercial
  188.    software  without the permission of Rainer Scharnow. Further it is
  189.    absolutely  disallowed to use the program for military purposes of
  190.    any kind.
  191.  
  192.  
  193.    6. Contents
  194.    ~~~~~~~~~~~
  195.  
  196.       In a directory the following files must be situated:
  197.  
  198.       MRCDemo.bat
  199.       MRCDemo.rexx
  200.       MultiRequestChoice
  201.       MultiRequestChoice.doc
  202.       MultiRequestChoice.doc.info
  203.       MultiRequestChoice.dok
  204.       MultiRequestChoice.dok.info
  205.  
  206.  
  207.    7. Thanks and Greetings
  208.    ~~~~~~~~~~~~~~~~~~~~~~~
  209.  
  210.       Special thanks must go to:
  211.  
  212.    -  Matthew  Dillon, the author of the great DICE compiler
  213.       which the program was compiled by
  214.  
  215.    -  Stefan  Becker,  the german distributor of DICE. I got
  216.       DICE  one  week  after  sending  an EMail to order the
  217.       compiler.  Besides:  I use  the  ToolManager - nothing
  218.       to say, only to click :-)
  219.  
  220.    -  Nico  François,  the  author  of  the  PowerPacker and
  221.       the wonderful ReqTools collection. With ReqTools it is
  222.       a child's play to write such a program :-)
  223.  
  224.    -  Martin  Taillefer/Oxxi  for  writing TurboText, one of
  225.       the  best  editors  I've ever seen (I hope the friends
  226.       of vi or stevie don't become indignant ;-))
  227.  
  228.  
  229.    8.    Bugs
  230.    ~~~~~~~
  231.  
  232.        I  hope  there aren't any bugs in the program. But if you found
  233.    any  send  me  a message. Informations about improvements I should
  234.    make are welcome, too.
  235.  
  236.        Rainer Scharnow
  237.        Linderhofstr. 70
  238.        12623 Berlin
  239.        Germany
  240.  
  241.        EMail: scharnow@informatik.tfh-berlin.d400.de
  242.  
  243.  
  244.    EOF
  245.