17 Bit Software 2: Collection B

home *** CD-ROM | disk | FTP | other *** search

/ 17 Bit Software 2: Collection B / 17Bit_Collection_B.iso / files / 2254.dms / in.adf / docs / ReqChange.doc.pp / ReqChange.doc

Wrap

Text File | 1990-09-13 | 34.6 KB | 842 lines

ReqChange V1.08 User manual ReqChange V1.08 ReqChange V1.08 © Copyright 1992 Magnus Holmgren ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Replace some common requesters. Release date: 16 Apr 92 Legal stuff ~~~~~~~~~~~ This program is FREEWARE, which means you may spread and use this program freely, as long as the following restrictions are followed: 1) All files are copied in an unmodified state. If additional information is needed, place it in a separate file. Preferably redistribute in the original archive form (*.run). 2) The copying is done on a non-commercial and non-profit basis only. A copy fee to replace media costs, postage etc. may be charged, and mustn't exceed the fee to obtain an AmigaLibDisk from Fred Fish. 3) The copier/spreader is not claiming the Copyright © of this program. Any exceptions from these restrictions requires written permission from the author, Magnus Holmgren. DISCLAIMER: ~~~~~~~~~~~ This program is supplied 'as is'. No warranty is given that the program will work exactly as documented. I assume no responsibility for the consequences of using this program. That is: Any loss of data, malfunction etc. caused by this program can't be blamed on me. If you use this program it's on your own risk. Page 1 ReqChange V1.08 User manual ReqChange V1.08 What is ReqChange? ~~~~~~~~~~~~~~~~~~ Every now and then, the programs you use needs to inform you of some important thing, or perhaps it needs the name of a file to operate on. When that happens, the programs often shows a requester of some kind, allowing you to easily select between a few options, or enter a filename. Before OS 2.0 (OS = Operating System), every program had to fix such things itself - except for information requesters with one or two answers - perhaps by using some shared library which contained the code (req.library is a good old one). With OS 2.0, such requesters was included. How nice! Now all programs will use the same requester, because everyone who has OS 2.0, will also have these requesters, and there is no need for the user to install some special library in the LIBS: directory. There was just a few small problems with these requesters: They weren't that good. For one thing, the information requesters where glued to the upper left corner of the screen, you had to use the mouse to confirm them - or some more or less cryptic key combination - and they didn't look *that* nice. The file requester was generally ugly, and it was unbelievably slow, at least on a standard Amiga 500. Arq came around. That program did something about the information requesters, but nothing about the file requester. It was also very big, ~40 Kb, and it was a bit slow on a standard Amiga 500 (that's the price of all those nice animations :). There seemed to be no good solution to this problem. But I wasn't the only one who thought like this! Nico François was one who though a bit like me here. So he made this new library: ReqTools, which is © Copyright Nico François. And yes, I know; Yet another library. But this is a good one! It contains a bunch of requesters which are powerful to the user, yet very easy to use. They looked good, and were generally fast and efficient. First time I saw them I thought: "Why can't all programs use these instead???". So I decided to do the best I could to allow all programs use this great library, and ReqChange is the program which fixes this as far as possible. I had some experience in writing patches (e.g. NewRequest, which modified the OS 1.3 AutoRequest to be much easier to use), so I knew what had to be done to get a safe program. The earlier versions of ReqChange only worked on OS 2.04. This version of ReqChange works on 1.3 systems too (when I say 1.3, I really mean 1.2/1.3). You need arp.library, and a Page 2 ReqChange V1.08 User manual ReqChange V1.08 1.3 version of reqtools.library (included) for this though. What ReqChange will do is to change (i.e. patch) the system requesters, and some other requesters in common libraries to use the ones found in ReqTools. The requesters that are changed are currently these: AutoRequest & EasyRequest These are two very similar requesters, which the OS uses a lot (to the user, they are identical; to the programmer, they only differ in the way they are called). "About" in the Workbench menu uses EasyRequest, and the requesters which asks you to insert a disk ("Please insert...") are of this kind too. AutoRequest is mostly used by programs written for OS 1.3. EasyRequest is a new function in OS 2.04, so it's only if you have OS 2.04 this function will be patched. The requester in ReqTools supports a few more keyboard alternatives, so you won't need to use the mouse to confirm it. These keys are: RETURN, Y, V which yields a positive response. It really means that it will be equivalent with pressing the leftmost gadget. All programs should have a positive response on the leftmost gadget, but this isn't always case (curse those programs! :). This gadget has boldface text. ESC, N, R, B which yields a negative response. It really means that it will be equivalent with pressing the rightmost gadget. And again, this isn't necessarily the negative response, but it "should" be. If the requester only has one gadget, you can use any of the keys to reply to it. FileRequest The filerequester in arp.library (ARP for short). Once, this was more or less "the" standard filerequester, but it is a bit old, and doesn't look good at all under OS 2.04. It's only ARP V1.3 (arp.library V39+) that is supported! ReqChange will refuse to open arp.library with a version number lower than 39. RequestFile & AslRequest Page 3 ReqChange V1.08 User manual ReqChange V1.08 These are the new file and font requesters in OS 2.04. The code for these is located in asl.library (ASL for short). TextRequest This REQ function is similar to AutoRequest and EasyRequest, but it is a bit more powerful. The features of REQ V2 are fully supported (timeout and abortmask). GetString & NewGetString These routines are in req.library (REQ for short), and provides a string requester (only difference between the two is the way they are called). GetLong Another REQ function. This is a requester very similar to the GetString requester, but you can only enter numbers in this one. It also shows the max and min values you can enter (at least REQ V2 has this feature). ColorRequester & ExtendedColorRequester These are the color requesters in REQ (these two only differs in the way they are called). The type of centering used for this requester is the same as the one used for all file requesters. FileRequester This is the file and font requester in REQ. Compatibility ~~~~~~~~~~~~~ Some of the features that exists in ARP and ASL does mostly exists in ReqTools too, but often in a more or less incompatible way. Thus, some features are not supported (at least not yet). This "ignorance" will at most cause a bit of inconvenience to you; a missing gadget which "should" be there, a few files are shown that really shouldn't be shown etc. But as far as I know, there aren't many programs that uses these features, so who cares?? :) ReqTools lacks some minor features in ASL, but I guess you'll never notice that. Page 4 ReqChange V1.08 User manual ReqChange V1.08 REQ's filerequester has a limit on the number of files the user may multiselect. As ReqTools doesn't have such a thing, it means that some of the files you multiselect might not be returned to the program (this also might happen if you're very low on memory). This is not a real problem, but you should be aware of it. Also note that you cannot select a directory if you also have a filename gadget with ReqTools - even if you select Ok - as you can with ASL. This is the only "real" problem with ReqChange that I know of at the moment. :( This causes AssignX to have some troubles with the "Assign..." function. You will not be able to select a directory to assign to, only files. Because of this, ReqChange has a similar feature builtin. If you use this feature, it will seem as AssignX isn't installed, so you might as well remove it from your startup. Please refer to the NOASSIGN parameter below for more information. Installation ~~~~~~~~~~~~ ReqChange is very easy to install. Simply run it. But remember that the file reqtools.library (of appropriate version) must be in your LIBS: drawer. The Install script places this file there for you. ReqChange autodetaches nicely, which means you do not need to "Run" it, if you start it from a CLI. If anything goes wrong, a requester will pop up, informing you about it, possibly allowing you to take different actions. If you have started the program from a CLI, some of the messages will appear in that CLI-window. In the case that the C-startup part (which I can do nothing about) fails, you will not see that! But that doesn't happen *that* often. What can go wrong here is that the startup code fails to open dos.library, or ReqChange simply didn't load, because you're very low on memory. If intuition.library didn't open ReqChange will terminate with the return code 300. If no message appears ReqChange should have installed ok. Note that if you are using WShell 2.0, you will see a message saying "***Hanging forbid!" when ReqChange has detached ok (ReqChange does some more intializations after this, and these might fail). This is not a bug (neither in WShell nor in ReqChange). It must be done this way because of the way the autodetaching currently is implemented. MFR users who wants to use ReqChange for everything but the filerequesters (for which they use MFR :), should do this: First run ReqChange, and after that, MFR (if both MFR Page 5 ReqChange V1.08 User manual ReqChange V1.08 and ReqChange are in WBStartup, set the STARTPRI in ReqChange's tooltypes to at least 1 higher than the same value in MFR (if no such value can be found, it will default to zero)). I've tried this, and it works fine. NOTE: Although you have installed ReqChange, there might be programs active, which allocated some ASL buffers before ReqChange got active. If this is the case, ReqChange will not change that particular request (i.e. you'll see the old Asl-requester). Also note that you cannot exit while there are programs around that are using a requester, or have some buffers that was allocated after ReqChange was activated. Quitting these programs will enable you to terminate ReqChange. Options ~~~~~~~ There are a few options you can use, to make ReqChange behave the way you want. These options can be used either in the CLI or via the ToolTypes fields in the icon. Here follows a list over all options. If the option in question ends with "/K", it means that it should be followed by additional information, here in numeric form. If the option ends with "/S", it means that the presence of this string is enough to activate it. Note that the "/K" and "/S" extensions shouldn't be entered! If an option is preceeded by an equal sign ("="), it means that the text in front of it can be used as a shortcut to the option (e.g. using IH means the same as IGNOREHEIGHT). A "(OS 2.04)" comment means that the option in question is used on OS 2.04 systems only. The options are: MIH=MINHEIGHT/K This option specifies the minimum height of the filerequester window. Any height requests lower than this will be ignored (and the requester will be MINHEIGHT pixels high). To disable this feature, use the height 0. Default value is 0. MAH=MAXHEIGHT/S This option specifies the maximum height of the filerequester window. Any height requestes higher that this will be ignored (and the requester will be MAXHEIGHT pixels high). To disable this feature, use the height -1 (which in fact will turn into 4 294 967 295...). Default height is -1. Note that this and the previous parameter should be entered as you would like it to be on a non-interlaced screen. If the Page 6 ReqChange V1.08 User manual ReqChange V1.08 requester is about to appear on a screen, which visible height is more than 400 pixels, these parameter values will be doubled. CS=CENTERSCR/S This switch will make all information requesters to be centered on the screen, instead of centering them beneath the mouse-pointer. CW=CENTERWIN/S This switch is similar to CENTERSCR, but it will make all information requesters centered within their parent window, if the task provided such a window. If not, the requester will be centered on the screen. This switch will override the CENTERSCR switch if both are used at the same time. FCS=FRCENTERSCR/S This switch is similar to CENTERSCR, but this one will affect all filerequesters. FCW=FRCENTERWIN/S This switch is similar to FRCENTERSCR, but this one will affect all filerequesters. CT=CENTERTEXT/S Although the name is similar to some other switches above, the difference in action is large. This switch makes all information requesters' text centered. That is, each line of the text in the requester is centered. This will definitively look bad if the text was centered "by hand" by the programmer, but it is not common. NOARP/S This switch tells ReqChange to not change the file requester in ARP. This means that the ARP filerequester will behave as normal. If this is specified, ReqChange will make no attempt to open ARP. Thus, you don't need arp.library to be able to run ReqChange. NOTE: If you are running OS 1.3, you need ARP! The NOARP switch is still useable though (to disable the filerequester patch). Page 7 ReqChange V1.08 User manual ReqChange V1.08 NOASL/S (OS 2.04) Same as NOARP, but now it's the filerequesters in ASL that won't be changed. This could be useful if it comes a new version of ASL which is much better (or it's inner workings have changed in such way that ReqChange fails to simulate the file requester. See below on the topic "Problems"). NOREQ/S Same as NOARP and NOASL, but now its the functions in req.library that won't be changed (and req.library won't be opened). NOKEYS/S Disable most of the keyboard shortcuts in the text requesters, except for a few. If used, only Left Amiga 'V', Left Amiga 'B' and ESC can be used. Left Amiga 'V' is equivalent with the leftmost gadgets. Left Amiga 'B' is equivalent with the rightmost gadget, as is the ESC key. NOCX/S (OS 2.04) This option stops ReqChange from making its presence known to the Exchange program. I don't really know if this option is needed, but I added it anyway. ReqChange won't open commodities.library if you use this switch. NOASSIGN/S This switch will disable the code that checks for "Please insert volume..." requesters. When such a requester pops up, and this switch NOT is used, three gadgets will show up instead of the normal two. The extra one is called "Assign..." and lets you do just that, enter an assignment to use. Now you don't need any Shell/CLI to do this. Unfortunately, you cannot select any files with this requester (not so oftenly used), due to how ReqTools works, but it can be very handy anyway. This feature will always use ReqTools for requesters. Thanks to Steve Tibbet for his program AssignX which made me implement this feature - which is more or less a simplified AssignX - since his program didn't work that well if ReqChange was installed, I had to write one of my own instead. :) Page 8 ReqChange V1.08 User manual ReqChange V1.08 If arp.library, asl.library or req.library couldn't be opened for some reason, you will be presented with a requester informing you about the fact. It also has three gadgets, namely: "Retry" - Try to open the library again. Now you have a chance to install the library in question before proceeding. "Ignore" - Don't care about it. This also means that the requesters in the library in question won't be changed. "Quit" - Simply quits ReqChange. You will also see this requester if commodities.library didn't open (commodities.library is an OS 2.04 thingy). If you select the "Ignore" gadget, the result will be the same as it would be if you had used the "NOCX" switch. If reqtools.library won't open, you will be presented with a similar requester, but that one lacks the "Ignore" gadget. Removing ReqChange ~~~~~~~~~~~~~~~~~~ You can remove ReqChange in tree ways: 1) Use the Exchange program. Select ReqChange in the list, and click on "Kill". This feature required OS 2.04. 2) Run ReqChange again. The screen will flash to indicate that a termination message was sent to the installed ReqChange. 3) Send ReqChange a break signal (to do this you can e.g. use Xoper). ReqChange will quit on any of the break signals C, D, E or F. Although you tell ReqChange to quit, this doesn't necessarily mean that the program will terminate. If some other program have changed any requester after ReqChange installed itself (e.g. AssignX), there are some allocated buffers around, or a requester is active, then ReqChange can't be removed. If this is the case, a requester will pop up, telling you about the specific problem. Page 9 ReqChange V1.08 User manual ReqChange V1.08 Problems ~~~~~~~~ If a program uses the pattern matching feature in ASL, there is a small problem, because ReqTools handles .info files (i.e. icons) differently. Now, e.g. IconEdit's "Project/Open..." menu selection open up a file requester for the user to choose an icon to load. Since the user obviously only should choose an icon file, the pattern used here is "#?.info", which would show all files ending with .info. But ReqTools doesn't count the .info file as a "real" file. Each .info file is attached to its "parent" (e.g. ReqChange.info is attached to ReqChange), if such is available. If the pattern says that a parent shouldn't be shown, then the corresponding .info file will not be shown either, regardless of the state of the "Show/Hide *.info" gadget. If the gadget says "Show *.info", all ".info" files which has a visible parent is shown (if there is no parent, the ".info" file will be shown anyway), otherwise not. Since all parents fail because of the #?.info pattern, no files will be visible. To solve this problem, ReqChange checks to see if the pattern contains the string ".info", and if this is the case, ReqChange will not use any pattern in the requester (the pattern is still placed in the FileRequester structure anyway, if an ASL_Pattern tag is used). Since there are problems like this, ReqChange will force ReqTools to show a pattern gadget, if a pattern of any kind is used. There can be other problems with this program. Of what type I do not really know. To some extent, ARP can cause problems, but such problems shouldn't be serious in any way. At most, your life at the computer may be slightly harder :). The REQ patches are as compatible as possible. There should be no problems with req.library V2 or lower, but newer versions *might* cause some problems. This is because ReqChange uses some fields in the filerequester structure that are reserved for future use to get directory-buffering. As long as these are not used by any application, it should work ok. The ASL patches should work ok too. These patches might cause problems with newer versions of ASL than V37.27. Although I don't see this as likely, there is still a potential danger (and since I can't predict the future, I don't know what to do to eliminate this :). Page 10 ReqChange V1.08 User manual ReqChange V1.08 If you should experience problems with the ASL changes, use the NOASL switch to disable the changes, or reinstall the older version of asl.library, all depending on your taste (and why not send me a note about the problem?). There were other problems during the development. The Autodocs are incomplete about the file/font requester. E.g. there is a ASL_ModeList tag which is only mentioned in the asl.h file, but not a word about what it does. Since there seems to be no similar thing in ReqTools, I guess it doesn't matter that much. About the code ~~~~~~~~~~~~~~ ReqChange is written almost completely in C, with some small assembler stubs. Yet the program is only about 14 Kb big (source is ~90 Kb). I compiled it with DICE (assembler part was assembled with the Devpac assembler), which can generate quite small code (especially if you're using the _main entry point! This way you get rid of a *lot* of "unneeded" code that the compiler otherwise would drag in). The assembler part takes care of pushing the register arguments (if so needed) on the stack and then call the C code (some of the patches are written entierly i asm though), stack switching - if that is needed, other kinds of glue, and the code that handles the auto-detaching. Technical information ~~~~~~~~~~~~~~~~~~~~~ Those of you who knows a bit about programming might be interested about this. No hooks are supported in the ARP requester patch. This is because ARP guarantees that a4 will be left untouched. Some work is needed to fix this, and since I have no program that uses this feature, I haven't bothered to fix it.. Please let me know if you would like support for the DoWild hook (as this is the only thing ReqTools has). Each patch checks the stack, and if the free space left is less than 4 Kb, a new stack on 4 Kb will be allocated and switched in (there is a function in exec that might do this, but there is no Autodocs on it, so I have used my own version instead, which seems to work just fine), to ensure enough space for the requester functions. If no memory is available for a new stack, or the patch runs out of memory, the Page 11 ReqChange V1.08 User manual ReqChange V1.08 function in question will return failure. Upon returning, the stack (if a new one was allocated) will be freed, and the original will be restored. Future improvements ~~~~~~~~~~~~~~~~~~~ In the future I might add some of the special features in the ARP filerequester. But is it worth the trouble? I doubt that, since the only code I know about that uses any of them, is code I've written myself... :) Some of the features AssignX has (Deny, Mount) might get implemented too, but since I've *never* used them yet (I've had AssignX installed a while), I didn't bother to implement these features in this version. I'm also thinking on adding directory caching to the ASL patches (this *will* be optional if I decide to implement it). This could waste quite a bit of memory, but if you think you can efford the memory, why not? If you would like to see some of these improvements, please let me know! That would increase the chance of them getting implemented a *lot*. And ofcourse, any bugs will be removed. Author contact ~~~~~~~~~~~~~~ If you have some comments about this program, regarding problems, ideas of improvements etc., feel free to send me a note (and I will certainly not refuse donations of any kind, since I'm a poor student! :) to this address: Magnus Holmgren Rydsvägen 254 A:14 S-582 51 Linköping SWEDEN If you don't like snail mail, you can send me e-mail via Internet or FidoNet. Via Internet, use any of these addresses: cmh@augs.se magnus_holmgren@augs.se cmh@lysator.liu.se d91magho@und.ida.liu.se Page 12 ReqChange V1.08 User manual ReqChange V1.08 FidoNet mail should go to AUGS BBS in Linköping, Sweden: "Magnus Holmgren" @ 2:204/404 The latest version of ReqChange is also available for anonymous ftp at lysator.liu.se. Check the pub/amiga/ReqChange directory. Acknowledgments ~~~~~~~~~~~~~~~ There are a few persons I feel I must thank, because they have in some ways made this program possible (or at least better) : Matt Dillon - For his great DICE compiler (and for answering all my (more or less silly) questions about C and DICE). Nico François - For reqtools.library. This library started this little program. Stefan Boberg - For helping me when ReqChanged crashed occasionally. (He discovered that the problem probably was stack overflow. After adding stack switching code, the problem have never been seen since). Stefan Becker - For providing an example (the source to ToolManager) on how to add a broker to Commodities. Eddy Carrol - For his Res function (and to Olaf `Olsen' Barthel, because this function was included in term, and the source to that program was included :), which enabled me to make ReqChange autodetach. I did some changes in the function though, so now it should be 100% safe and reliable (I hope). Revision history ~~~~~~~~~~~~~~~~ Please read the History.Doc file for a revision history! May the Amiga be with you! Page 13 ReqChange V1.08 User manual ReqChange V1.08 Table of contents ~~~~~~~~~~~~~~~~~ Legal stuff............................................. 1 Disclaimer.............................................. 1 What is ReqChange?...................................... 1 AutoRequest & EasyRequest............................ 3 FileRequest.......................................... 3 RequestFile & AslRequest............................. 3 TextRequest.......................................... 4 GetString & NewGetString............................. 4 GetLong.............................................. 4 ColorRequester & ExtendedColorRequester.............. 4 FileRequester........................................ 4 Compatibility........................................... 4 Installation............................................ 5 Options................................................. 6 MINHEIGHT............................................ 6 MAXHEIGHT............................................ 6 CENTERSCR............................................ 7 CENTERWIN............................................ 7 FRCENTERSCR.......................................... 7 FRCENTERWIN.......................................... 7 CENTERTEXT........................................... 7 NOARP................................................ 7 NOASL................................................ 8 NOREQ................................................ 8 NOKEYS............................................... 8 NOCX................................................. 8 NOASSIGN............................................. 8 Removing ReqChange...................................... 9 Problems................................................ 9 About the code.......................................... 11 Technical information................................... 11 Future improvements..................................... 12 Author contact.......................................... 12 Snail mail address................................... 12 E-mail addresses..................................... 12 Acknowledgements........................................ 13 Revision history........................................ 13 Table of contents....................................... 14 Page 14