MultiRequestChoice Release 1.0 - 01 August 1993 Documentation Written by Rainer Scharnow Copyright (c) 1993 by Rainer Scharnow 0. Introduction ~~~~~~~~~~~~~~~ MultiRequestChoice is a requester utility for the C: directory. It has been designed as a powerful and comfortable replacement for ASK and other present requester utilities. It is very useful for both batch files and ARexx scripts. Here are the advantages of MultiRequestChoice: - It is very simple to build requesters from one up to your personally wished number of response gadgets - It uses the fabulous reqtools.library (c) by Nico François, therefore all features has been very easy to realize and are contained in relative small code - The body text of the requester may consist of more than one line by using a newline character - The body text of the requester may be optionally left oriented or centred - The requester may appear on every public screen via PUBSCREEN option - The position of the requester on the desired screen may be controlled optionally 1. Requirements ~~~~~~~~~~~~~~~ MultiRequestChoice doesn't run under OS 1.x; all people using these old versions should think the system upgrade over. Besides there must be the reqtools.library V38+ in the libs: directory. It should run on all Amigas with all 680x0 processors (I did not need special hardware-near tricks to pop up a requester :-)). 2. Usage ~~~~~~~~ MultiRequestChoice is a CLI-only program. Developed as a batch and ARexx supporting utility it's a little bit senseless to run it from the Workbench. I think, you've already guessed it ;-). Ok, here is the usage of MultiRequestChoice: MultiRequestChoice [PUB|PUBSCREEN ] [CENTRETEXT] [SCREENTOPLEFT|SCREENCENTRE|MOUSECENTRE] MultiRequestChoice won't become active if you pass less than three parameters. In that case it will print out the usage once again. The three necessary parameters will be: - Reqtitle - the title of the requester - Bodytext - the text contained in the requester body in order to inform the user about the situation. A special feature is the possibility to use the C like format string '\n' in the text. This allows you to split the text into several lines - it is a newline option. If you want to print out a single '\' in your bodytext you must simply pass '\\'. But see the examples... - Gad1|Gad2|...|Gadx - the gadget(s) parameter. In the requester may appear from one up to ... gadgets as already mentioned. The gadget names are separated by a '|'. That tells the requester simultaneously how many gadgets the user wishes. Besides a keyboard shortcut response is supported. A '_' inserted before the provided hotkey character in the gadget string will allow you keyboard action. But see the examples... In 99% of all cases some space characters are situated in the strings. You can solve the problem if you quote the parameters with the '"' character. But this is clear, I think... Finally, there are some useful options making the user's life easier: - It doesn't matter if you write PUB or PUBSCREEN; the meaning is the same. This option requires an argument - of course the name of the PublicScreen the requester should appear on. If there isn't a PublicScreen of this name the requester pops up on the Workbench so if you would not handle this option - It is CENTRETEXT's turn to centre the text in the requester body. It is only useful if there is multi-line-text to process because one-line-text will always be centred in the body. Default is: left oriented text - The SCREENTOPLEFT|SCREENCENTRE|MOUSECENTRE option decides where on the screen the requester will appear. Default is: MOUSECENTRE. I think each part of the option will explain itself by its name. If not clear - see the examples... 3. Return codes ~~~~~~~~~~~~~~~ All the work would be for nothing if there weren't return codes produced by clicking the response gadgets. Well, the result will go to the system's $RC environment variable or if you use ARexx to the ARexx RC variable. Following rules exist: In the case of more than one gadget the rightmost is (according to Commodore's specification) the one of the most negative response and clicking this will always give back '0'. In the case of an one and only gadget the requester has only the function of informing the user about something, and a return value has got no meaning. The leftmost gadget will always give back '1', the next (which should not be the last in this example) will return '2', the third '3' and so on. Simple, isn't it? Finally, if MultiRequestChoice couldn't find a system resource (such as the reqtools.library) it will give back '200'. 4. Examples ~~~~~~~~~~~ Why should I do the work twice? There are in this directory two demos: MRCDemo.bat and MRCDemo.rexx. Almost all the possible effects of the requester are offered you in these demos. Demos explain more than words! First you have to change to MultiRequestChoice's directory. If you want to run MRCDemo.bat type 'execute MRCDemo.bat' or type 'rx MRCDemo.rexx' if you want to start the ARexx demo. See the "code" ;-) of the demos. Both are not commented because they are really simple and self-explaining. 5. Copyright ~~~~~~~~~~~~ Copyright (c) 1993 by Rainer Scharnow I, Rainer Scharnow, give my permission to make and distribute verbatim copies of this manual. All the copyright notices and this permission must be part of these copies. There is no guarantee that the program(s) described here in this manual works 100% ok. You will use this/these program(s) at your own risk. If any damages occur in connection with this/these program(s) the author can't be made responsible or liable for it. This package is freely distributable, but copyright by Rainer Scharnow. You may copy and use this package as long and much as you want if a copy fee including disk price of DM 5,- or (referring to mail-order abroad) US$ 6,- is not exceeded. Exception: laser disks, CD ROM. It is permissed explicitly to include this package into public domain series, f.i. Fish-Library, and to upload it to BBS and FTP servers. All the files counted out in the Contents section must be contained. No program of this package may be part of a commercial software without the permission of Rainer Scharnow. Further it is absolutely disallowed to use the program for military purposes of any kind. 6. Contents ~~~~~~~~~~~ In a directory the following files must be situated: MRCDemo.bat MRCDemo.rexx MultiRequestChoice MultiRequestChoice.doc MultiRequestChoice.doc.info MultiRequestChoice.dok MultiRequestChoice.dok.info 7. Thanks and Greetings ~~~~~~~~~~~~~~~~~~~~~~~ Special thanks must go to: - Matthew Dillon, the author of the great DICE compiler which the program was compiled by - Stefan Becker, the german distributor of DICE. I got DICE one week after sending an EMail to order the compiler. Besides: I use the ToolManager - nothing to say, only to click :-) - Nico François, the author of the PowerPacker and the wonderful ReqTools collection. With ReqTools it is a child's play to write such a program :-) - Martin Taillefer/Oxxi for writing TurboText, one of the best editors I've ever seen (I hope the friends of vi or stevie don't become indignant ;-)) 8. Bugs ~~~~~~~ I hope there aren't any bugs in the program. But if you found any send me a message. Informations about improvements I should make are welcome, too. Rainer Scharnow Linderhofstr. 70 12623 Berlin Germany EMail: scharnow@informatik.tfh-berlin.d400.de EOF