Otherware

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

/ Otherware / Otherware_1_SB_Development.iso / amiga / utility / misc / reqchang.run / ReqChange / ReqChange.Man < prev next >

Wrap

Text File | 1992-09-04 | 62.9 KB | 1,562 lines

ReqChange V1.14 User manual ReqChange V1.14 ReqChange V1.14 ⌐ Copyright 1992 Magnus Holmgren ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Replace some common requesters. Release date: 04 Sep 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.14 User manual ReqChange V1.14 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, 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. The file requester was generally ugly, and it was unbelievably slow, at least on a standard Amiga 500. 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 a program which fixes this as far as possible, and on the way, adds some extra features. 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. What ReqChange will do is to change the system requesters, and some other requesters in common libraries to use the ones found in ReqTools. The earlier versions of ReqChange only worked on OS 2.04. As of version 1.06 ReqChange works on 1.3 systems too (when I say 1.3, I really mean 1.2 and 1.3). You need arp.library (v39), and a 1.3 version of reqtools.library (included) for this though. As of ReqChange 1.14, the libraries will only be changed if they are actually open. This has the benefit of allowing the unused libraries to be flushed out of memory, if this is needed. Also, if you don't have one of the libraries, it will never be opened, and Page 2 ReqChange V1.14 User manual ReqChange V1.14 thus never changed (thanks to Nico Franτois for this great idea, which he first implemented in his similar program, called RTPatch). This is fixed by changing the routines that open and close the libraries (OpenLibrary() and CloseLibrary() in exec.library). These changes should be completely transparent, so you shouldn't need to worry about it. There is also a program called RTPatch (included in the ReqTools distribution archive), that does similar things as ReqChange. To make it easier for you to decide which program you prefer, I will here make a quick rundown on the most important differences in the two programs (see below for more information about the features ReqChange has). Things in favour for RTPatch: o It uses much less memory (~20-25 Kb), and thus, offers less extra features. o It has a patch that makes all/some screens have a 3D look. o Understands some of the new ASL V38 options. Things in favour for ReqChange: o The REQ patches are more complete (timeout and abourtmask fully supported). o Has a builtin "AssignX" clone, that works on OS 1.3/2.0, and understands translated requesters. o Many options, all controllable from a nice window interface (on OS 2.0). Changes take place immediately. o Sound effects in "information" requesters (ala ARQ), via UPD. o Pathces the ASL font requester. Sice ReqTools lacks some of the features in this requester, some (especially those who have Workbench 2.1) may regard this as a drawback. o Buffers the ASL file and font requester. o Doesn't require all libraries to be un-used at the time of installation. o Can be temporarily disabled (via the Exchange program, available on OS 2.0). Also, you can remove/add the patches to any of the libraries from the window interface. The requesters that are currently changed by ReqChange are these: AutoRequest & EasyRequest These are two very similar requesters, which the OS uses a lot (to the user, they are very similar; The difference is the way they are called and what features they have). They are used for information, and simple questions/confirmations. Page 3 ReqChange V1.14 User manual ReqChange V1.14 EasyRequest is a new function in OS 2.04, so it's only if you have OS 2.04 this function will be changed. 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. RequestFile & AslRequest 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 (REQ V2 has this feature). ColorRequester & ExtendedColorRequester These are the palette requesters in REQ (they only differ in the way they are called). FileRequester This is the file and font requester in REQ. Page 4 ReqChange V1.14 User manual ReqChange V1.14 Compatibility ~~~~~~~~~~~~~ Some of the features that exists in ARP are not supported. Currently, no "callback hooks" are supported. I could add the "file callback hook", but very few programs use this feature. The other features cannot be supported, due to "limitations" in ReqTools (nope, I'm not complaining. I don't need those features (and it seems like no programs uses them)! :). 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. This will probably not happen very often. ReqTools lacks some features in ASL, but I guess you only rarely will notice that. The one you may notice is the lack of possibility to choose colors and drawmodes in the font requester. 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 calling program (this could also happen if you're very low on memory). This is not a real problem, but you should be aware of it. 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 ".info" gadget. If the gadget is highlighted, .icon 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). Also, when any pattern is used, ReqChange will always tell ReqTools to show a pattern gadget. Page 5 ReqChange V1.14 User manual ReqChange V1.14 If you have a multiselect requester, the requester will be "canceled" if you left the filename gadget empty and clicked ok (if the requester isn't in multiselect mode then it will not be canceled), and didn't select any files. Apart from these problems, the ASL patches should work ok. But these patches might cause problems with programs that requires 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 :). 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 put into use, it should work ok. The number-requester in REQ (GetLong) patch doesn't quite behave like the original. Sometimes, there will be no default value, when it normally should be. I do not know how REQ determines how to do it, but it seems to involve some sort of magic. ;) I've followed the manual, that's all I can say. There is one more slight problem: ReqChange will try to lock its home directory. Thus, you may have problems in deleting the directory in which ReqChange is/was located. Quit ReqChange to fix this problem. It does not show up if you started ReqChange from CLI on OS 1.3. 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. For a more permanent installation, simply drag ReqChange to the WBStartup drawer (if you have OS 2.0 that is), or enter a suitable line in your S:User-Startup, S:Startup-Sequence or similar. If no message appears ReqChange should have installed ok. MFR (⌐ 1992 by Stefan Stuntz) users who wants to use ReqChange for everything but the filerequesters (for which they use MFR), Page 6 ReqChange V1.14 User manual ReqChange V1.14 should do this: First run ReqChange, and after that, MFR (if both MFR and ReqChange are in WBStartup, set the STARTPRI in ReqChange's tooltypes to at least 1 higher than the corresponding value in MFR (if no such value can be found, it will default to zero)). I've tried this, and it works fine, as long as you make sure that the tooltype DONOTWAIT doesn't exist in ReqChange's icon (by default it doesn't). Although you have installed ReqChange, there might be programs running, 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). If you did specify an idfile (see below), and ARexx (i.e. rexxsyslib.library) wasn't available, you will be presented with a requester informing you about the fact. It also has three gadgets: "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 idfile will be ignored. "Quit" - Simply quits ReqChange. If reqtools.library, icon.library or commodities.library won't open, you will be presented with a similar requester, but that one lacks the "Ignore" gadget. ReqChange will not try to open commodities.library if you have OS 1.3. Removing ReqChange ~~~~~~~~~~~~~~~~~~ You can remove ReqChange in four ways: 1) Use the Exchange program. Select ReqChange in the list, and click on "Kill". This feature requires OS 2.04. 2) Run ReqChange again. The screen will flash to indicate that a termination message was sent to the installed ReqChange. This only works on 1.3 systems. If you do this on OS 2.0 systems, the settings window will pop up. 3) Send ReqChange a break signal (to do this you can use SignalRC or e.g. Xoper). ReqChange will quit on the break signal C. If you send it an F, the window will pop up (on OS 2.0). See the "Break signals" below for further information about break signals, and how they affect ReqChange. 4) In the settings window (which only is available on OS 2.0)), Page 7 ReqChange V1.14 User manual ReqChange V1.14 use either the "Quit" menu or gadget. 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. MFR), 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. I've done what's possible (to my knowledge :) to make this removing as safe as possible, but I can't make it 100% safe. But the chance that ReqChange will cause a guru (sooner or later) when it removes itself is *very* small. The following explanation needs some knowledge about the Amiga and programming to understood fully: There might be a call to a function - that ReqChange have changed - that didn't have time to be noticed in a global variable, before a task switch occurred that switched in ReqChange, which was just about to remove itself from the system. Since the global variable says that no requesters are active, ReqChange starts to remove itself from the system. What about that pending call you ask?? Well, that will continue to execute as nothing had happened... Guess what happens... I don't know if this ever can happen in practice (the critical time-interval is very small, it's about 200-300 clock-cycles or so on a 68000 CPU), but in theory, this may happen! 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. All options should be followed by additional information, separated by a "=" (when running from the CLI, whitespace is also possible if you have OS 2.04, and mandatory (i.e. "=" doesn't work) if you have OS 1.3). If you invoke ReqChange from the CLI, some options have a shortcut. They are the one in front of the "=" char in the keyword in question (e.g. to set the minheight to 200, use either "MIH 200" or "MINHEIGHT 200"). If you enter an invalid option somewhere, ReqChange will normally inform you about it, and fall back to the default value. The options are: MIH=MINHEIGHT This option should be followed by a numeric argument. Page 8 ReqChange V1.14 User manual ReqChange V1.14 This option specifies the minimum height (in pixels) 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. If the requester is about to appear on a screen which visible height is more than 400 pixels, this value will be doubled. MAH=MAXHEIGHT This option should be followed by a numeric argument. This option specifies the maximum height (in pixels) of the filerequester window. Any height requests 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. If the requester is about to appear on a screen which visible height is more than 400 pixels, this value will be doubled (oh, if you use -1, it will turn into 4 294 967 294... ;). TO=TOPOFFSET This option should be followed by a numeric argument. This option specifies the vertical offset (in pixels) from the center of the window/screen or the top-left position of the window/screen that the requester should show up at. This offset has no effect on the POINTER centering. Default is 0. LO=LEFTOFFSET This option should be followed by a numeric argument. This option specifies the horizontal offset (in pixels) from the center of the window/screen or the top-left position of the window/screen that the requester should show up at. This offset has no effect on the POINTER centering. Default is 0. C=CENTER This option specifies the centering to be used for information requesters. Can be any of WINDOW, SCREEN, TOPLEFTWIN, TOPLEFTSCR or POINTER. Default value is POINTER (actually, anything that isn't WINDOW, SCREEN, TOPLEFTWIN or TOPLEFTSCR is considered to be POINTER). Page 9 ReqChange V1.14 User manual ReqChange V1.14 See below on the "Centering" section for further information. FRC=FRCENTER This option specifies the centering to be used for the file, font and palette requesters, as well as ReqChange's window interface. Can be any of WINDOW, SCREEN, TOPLEFTWIN, TOPLEFTSCR or POINTER. Default value is POINTER (actually, anything that isn't WINDOW, SCREEN, TOPLEFTWIN or TOPLEFTSCR is considered to be POINTER). See below on the "Centering" section for further information. CT=CENTERTEXT This option should be followed by either YES or NO. NO turns the option off, while YES (or anything that isn't NO or OFF) says the option should be on. Although the name is similar to some other switches above, the difference in action is large. If this switch is on, all information requesters' text will be centered. That is, each line of the text in the requester is centered within the requester. This will definitively look bad if the text was centered "by hand" by the programmer, but on the other hand, this is not common. Default is YES. PS=POPSCR This option should be followed by either YES or NO. NO turns the option off, while YES (or anything that isn't NO or OFF) says the option should be on. If this switch is on, ReqTools will pull the screen a requester appears on to the front, just after the requester is opened. The screen that was in front when the requester opened will be brought back (if it still exists) when the requester closes later on. I wouldn't be surprised if some users finds this a bit annoying, so here you can disable this feature in ReqTools. Default is YES. BF=BACKFILL This option should be followed by either YES or NO. NO turns the option off, while YES (or anything that isn't NO or OFF) says the option should be on. If this switch is on, ReqTools have a backfill pattern in the GetLong() and GetString() changes in REQ. At the moment, these two Page 10 ReqChange V1.14 User manual ReqChange V1.14 requesters are the only two in ReqTools which supports this. Default is YES. A=ASSIGN This option should be followed by either YES or NO. NO turns the option off, while YES (or anything that isn't NO or OFF) says the option should be on. When this switch is on, ReqChange will check for "Please insert volume..." requesters. When such a requester pops up, you will be presented with a requester that allows you to make an assign for this volume on the fly, or maybe try to mount it, or you could disable this volume name. Default is YES. See below in the "Make assigns" sections below for further information. KEYS This option should be followed by either YES or NO. NO turns the option off, while YES (or anything that isn't NO or OFF) says the option should be on. If this switch is off, it will disable most of the keyboard shortcuts in the information requesters, except for a few. These are: Left Amiga 'V', Left Amiga 'B' and ESC. Left Amiga 'V' is equivalent with the leftmost gadget. Left Amiga 'B' is equivalent with the rightmost gadget, as is the ESC key. Default is YES. ASL This option should be followed by either YES or NO. NO turns the option off, while YES (or anything that isn't NO or OFF) says the option should be on. If the option is on, ReqChange will change the file requester in ASL, otherwise not. If this switch is off, ReqChange will make no attempt to open ASL. Default is YES. This option is always NO on OS 1.3. ARP This option should be followed by either YES or NO. NO turns the option off, while YES (or anything that isn't NO or OFF) says the option should be on. Page 11 ReqChange V1.14 User manual ReqChange V1.14 If the option is on, ReqChange will change the file requester in ARP, otherwise not. If this switch is off, 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 ARP switch is still useable though, to control the filerequester change. Default is YES. REQ This option should be followed by either YES or NO. NO turns the option off, while YES (or anything that isn't NO or OFF) says the option should be on. If the option is on, ReqChange will change the file requester in REQ, otherwise not. If this switch is off, ReqChange will make no attempt to open REQ. Thus, you don't need REQ to be able to run ReqChange. Default is YES. FIB=FILEBUFFER This option should be followed by either YES or NO. NO turns the option off, while YES (or anything that isn't NO or OFF) says the option should be on. This switch lets you (de)active the filename buffering on the filerequesters. The ARP filerequester is never buffered. Some REQ filerequesters may not be buffered even if you specify YES, but if you say NO, no REQ filerequesters will be buffered. Default is YES. FOB=FONTBUFFER This option should be followed by either YES or NO. NO turns the option off, while YES (or anything that isn't NO or OFF) says the option should be on. This switch lets you (de)active the filename buffering on the fontrequesters. If you have e.g. FontCacheX (by Steve Tibbet) running, there is no need to buffer the fontrequester (double buffering wastes memory), since FontCacheX makes the reading of FONTS: so fast anyway (apart from first the read). Some REQ fontrequesters may not be buffered even if you specify YES, but if you say NO, no fontrequesters will be buffered. Default is YES. Page 12 ReqChange V1.14 User manual ReqChange V1.14 ID=IDFILE This option should be followed by the name of a plain ASCII file. No typechecking is done. This option allows you to get information requesters with sound effects. See below in the "Idfile format" section below for further information. This feature needs ARexx. Default is no name at all (which means you get no sound effects). CX_POPKEY This option should be followed by an input description string. This option lets you specify which (hot)key combination to pop up the settings window. If you enter an empty string (""), you can disable this feature. You can always open the window by either starting ReqChange again, or by using the Exchange program. The string will automatically be truncated if its length exceeds 100 chars. For more information about input description strings, please see below (section "Input description strings"), or have a look in the manual for OS 2.0. This option is always disabled on OS 1.3. Default is "control lalt r" CX_POPUP This option should be followed by either YES or NO. If you enter NO, it means that the settings window will not open upon startup. If you enter YES (or anything that isn't NO or OFF), the settings window will pop up when you start ReqChange. This option has no effect on OS 1.3. Default is YES. CX_PRIORITY This option should be followed by a number, in the range of -128 to 127. It specifies the priority for the CX_POPKEY argument. If you have other programs that uses the very same (hot)key, this priority number decides which program that actually gets the keypress-report (the one with the highest number gets the report). This option has no effect on OS 1.3. Default is 0. Page 13 ReqChange V1.14 User manual ReqChange V1.14 Centering ~~~~~~~~~ ReqTools supports a number of different centering types for all requesters. ReqChange allows you to select which centering method to be used on all requesters ReqChange changes. You may have one centering types for information requesters, and one for all the other requesters (file, font, palette etc.). The following list contains all centering types, and these are the possible keywords that the CENTER and FRCENTER keywords accept: WINDOW - makes the requesters centered in the "parent" window, if the caller supplied such a window. Otherwise the requester will be centered in the screen. SCREEN - makes the requesters centered on the screen. TOPLEFTWIN - makes the requesters centered in the upper left corner of the "parent" window, if the caller supplied such a window. Otherwise the requester will be placed in the upper left corner of the screen. TOPLEFTSCR - makes the requesters placed in the upper left corner of the screen. POINTER - makes the requesters (or rather the rightmost gadget in the requester) centered under the mouse. If ReqTools couldn't place the requester exactly where requested, it will be placed as close as possible. If you want, you could add offsets to these centering types, with the TOPOFFSET and LEFTOFFSET keywords (see above). They do not affect the POINTER centering mode. Make assigns ~~~~~~~~~~~~ Quite often, an Amiga user sees a requester asking for a certain volume ("Please insert volume..."). Often, it is an assign that is missing, so you have to find a CLI, and make that assign there. Steve Tibbet found this a bit cumbersome. So he made a program - AssignX - that allowed the user to make the assign on the fly, directly from the requester. No CLI needed. This was fine, but AssignX didn't work that well with earlier versions (1.0-1.12) of ReqChange, since earlier versions of ReqTools (before V2.0 (or V38)) didn't allow the filename field to be empty, while ASL did that. AssignX used this so you could assign both files and drawers. This made it impossible to make assigns. Because of this, I wrote my own AssignX version, and built that Page 14 ReqChange V1.14 User manual ReqChange V1.14 one into ReqChange. This version couldn't make assigns to files, but that was a minor problem (at least for me). Later on I added all the features AssignX had (mount and deny), and as of ReqChange 1.13, you can also make assign to files. It should also be noted that the "ReqChange version" of AssignX is better coded that the original. Or that is at least what I think! :) E.g. the Deny feature (see below) uses somewhat less memory, and doesn't fragment the memory that much either. The deny part is safer too (some potential problems removed). And my AssignX version works on OS 1.3! So there is no need to use AssignX, even if that would work. During startup, ReqChange will try to find out what the "Please insert volume" string is translated to (by locale.library or SRT). This is done by trying to Lock() (i.e. get a simple reference for it. Can also be used to check if a certain name refers to an existing volume/drawer/file) a volume named "__▀⌐«⌐«▀__:" (This might fail, if you have a volume/assign with that name. But I don't take that as likely... :) Even if you do have a volume/assign with that name, ReqChange will still be able to find the default string ("Please insert volume")). The "assign" code will then copy the first line in the requester that is generated (but not seen), and it will use that text to search for. As this translation might change, you have the possibility to update this. This can be done in two ways: 1) Send ReqChange a break e signal (via SignalRC or e.g. Xoper). 2) Use the menu-entry named "Update assign" (you have a better name?? Then send me a letter! :). When a "Please insert..." requester is detected, five gadgets will show up instead of the normal two. The three extra gadgets are these: "Mount" - This gadget will try to mount the volume in question. This function requires Mount to be available in C:, and a suitable entry in the DEVS:MountList file to succeed. "Assign..." - This gadget lets you enter an assignment, with a ReqTools file requester. You can enter a file or a directory here. To select a directory, simply leave the filename gadget empty. "Deny" - This gadget will cancel the requester, and any requesters in the future (until you reboot or quit ReqChange) which requests for the current volume name. Currently you cannot translate these gadgets. Page 15 ReqChange V1.14 User manual ReqChange V1.14 Idfile format ~~~~~~~~~~~~~ This feature needs ARexx to work. This means that ReqChange needs rexxsyslib.library. If you didn't enter any IDFILE, ReqChange will still try to open ARexx, but in case that failed, you will not be informed about it (which you ofcourse will, if you did enter an id file). If the "Read" gadget in the window interface (see below) is disabled, it means that ARexx wasn't available at the time ReqChange was started. There is a program called Arq (Copyright ⌐ 1990,91 by Martin Laubach and Peter Wlcek), that changes EasyRequest and AutoRequest to use real fancy requesters, with different animations and sound effects, based on the text in the requester. Those sound effects were achieved by having a "player deamon", i.e. a program that waits in the background for someone to send it a request to play a sample. This player deamon is called Upd (⌐ 1991 Jonas Petersson & Absolut Software (aka Sirius Soft)). Some persons really liked this feature, and they would like to see it in ReqChange too. So I implemented it (unfortunately, I've forgot who asked for this... :). The basic idea is simple. Whenever an information requester contains some certain text, an id is sent to Upd (or rather, to an ARexx port named "PLAY"). Based on this id, Upd then plays a (user-definable) sample. The idfile contains information about what text to search for, and which id to send for each text. For more information about these ids and Upd in general, please read the documentation to Upd, found in the Upd drawer of this distribution. The format of the idfile is very free. Anywhere in this file, you can have a comment. They are denoted by first having some whitespace (i.e. spaces, tabs or linefeeds), followed by a '#'-char (what is that char called?? :). You can also have a comment in the very beginning of the file. These comments are ignored by ReqChange, and they are terminated by a linefeed. But now over to the actual file format. First of all, you specify an id. After that, you specify the text to search for in the requester. Every id must have one matching text. These ids and texts can be arranged any way you like them to be, as long as they are all separated from each other by whitespace. If an id or a text contains whitespace, quote the string (you may quote it even if it doesn't contain whitespace). It is advised that you avoid spaces and other "strange" characters in the id though. If you need to have linefeeds or quotes within a string, do like this: To get a quote, enter '\"'. A linefeed can either be entered by Page 16 ReqChange V1.14 User manual ReqChange V1.14 having a linefeed right within the quoted text (it must be quoted, or else it will be treated as whitespace), or by entering '\n'. To enter a '\' char, enter '\\'. NOTE: It's strictly speaking not an error to not terminate a quote, as a quote can span several lines. But this generally indicates an error in the file, so you will get a warning about this if it should happen. There is one special text string, and that is '*', which always will match. Useful to get a default sound. Currently, you can't search for a single '*' char in a requester (it may very well be a part of a search string), but I don't see this as a problem (if you do, tell me!). When an information requester then shows up, ReqChange will search through all texts in the order as they were found in the idfile, and as soon a text is found within the requester, the corresponding id is sent to Upd. Thus, you should have specific texts to match in the beginning, and more general ones later on. This search is case insensitive. The process needs some memory, so it might fail if you are very low on memory. It may also take a little while (not long though, but you may notice a small delay), especially if the requester contains a large amount of text, and/or you have a lot of ids in your file. The search isn't the fastest one around... :) I've included an example file, called 'IdFile.Example', which (hopefully) mimics the behaviour of Arq (at least when it comes to sound effects). There is also an example file for Upd, suitable for use with IdFile.Example, called Upd.IDs. Just change the sample-names to what you have and find suitable. If you run out of memory during the read of the id file, parts of it might not have been read. Note that the entire file is read into one allocated buffer, which is as large as the file. After that, the content is analyzed. This buffer is freed when the neccessary information have been copied. As it is quite likely that one id is used for several texts (as in the example file mentioned above), ReqChange will only store an ID string once, to save memory. All other references to the same string simply points to this single copy. The case is not significant when checking for id duplicates. Also, this process isn't that fast either. If you have a real *huge* file, it may take a few minutes to read the file (I tested once with this manual! No complaints from ReqChange, but it took quite a long time... :). Make sure you don't place any null-bytes in the file, as this will cause ReqChange to believe that the file is shorter than it really is. Page 17 ReqChange V1.14 User manual ReqChange V1.14 The name of this file may not be more than 100 characters. It will automatically be truncated if it is longer than this. You should avoid using names relative to the current directory. Input description strings ~~~~~~~~~~~~~~~~~~~~~~~~~ The template for an input description string is (thanks to Stefan Sticht for this explanation. It is a slightly modified part from the docs to one of his commodities): [class] (([-]qual)|syn)* [[-]upstroke] [high|ansi] (* means zero or more occurances of the of the expression in brackets) 'class' is one of the strings: RAWKEY, RAWMOUSE, EVENT, POINTERPOS, TIMER, NEWPREFS, DISKREMOVED, DISKINSERTED. If not specified, the class is taken to be "RAWKEY". 'qual' is one of the strings: LSHIFT, RSHIFT, CAPSLOCK, CONTROL, LALT, RALT, LCOMMAND, RCOMMAND, NUMERICPAD, REPEAT, MIDBUTTON, RBUTTON, LEFTBUTTON, RELATIVEMOUSE. A preceding '-' means that the value of the corresponding qualifier is to be considered irrelevant. 'syn' (synonym) is one of the strings: SHIFT (means "left or right shift"), CAPS (means "shift or capslock"), ALT (means "either alt key"). 'upstroke' (literally "upstroke"). If this token is absent, only downstrokes are considered for RAWMOUSE (mousebuttons) and RAWKEY events. If it is present alone, only upstrokes count. If it is preceded by a '-', it means that both up and down strokes are included. 'high' is one of the strings: COMMA, SPACE, BACKSPACE, TAB, ENTER, RETURN, ESC, DEL, UP, DOWN, RIGHT, LEFT, HELP, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, (, ), /, *, -, +. 'ansi' a single character token is interpreted as a character code, which is looked up in the system default keymap. Except for the ansi character, the case is not considered to be important in all these strings. Page 18 ReqChange V1.14 User manual ReqChange V1.14 Window interface ~~~~~~~~~~~~~~~~ This interface is only available on OS 2.0 systems! To open this window, use either the hotkey (CX_POPKEY), the Exchange program, start ReqChange a second time, or send a break F signal to ReqChange (e.g by using SignalRC). It will use the screen font, if that one isn't proportional, in which case the system default font will be used. If either the font is too large for the window to fit, Topaz 80 will be used. These routines aren't perfect, but work quite well (consider they only added 500 bytes to the program!). The major problem is that some gadgets in GadTools have a fixed dimension, and ReqChange doesn't take that in account... :) Also, sometimes the scaling routines (I'm scaling all coordinates, which are based on Topaz 80, according to the new font size) might be a pixel wrong sometimes... Note that if you have a *very* large screen font or a small (?) Workbench screen, all gadgets might not be visible (even if Topaz 80 is used). From here, you can modify most of the parameters in ReqChange at run time (the CX_#? parameters cannot be changed from here). You can save the settings (to the icon, if there is any), or quit reqchange. Really, there isn't that much to say about it. It is quite straight-forward. But ok, a few words: There are 7 sections in the window. The centering section lets you change the centering method used for the information requesters, and the other requesters. Simply click in the gadgets until the desired centering type shows up. If you shift-click, the previous alternative will show up. All the small, square boxes are for the keywords that take YES or NO as argument. If the box is checked, it means the same as if the corresponding keyword was YES. There should be no problems to understand which gadget that corresponds to which keyword. In the 'Changes' section, you select which libraries that should be changed. If you turn off the changes for a certain library, ReqChange will try to remove these changes immediately. If this wasn't possible, ReqChange will try to make the changes behave like they were the original. This will work just fine, except for ASL, if you have ASL V38+, in which case some features won't be there. Each time you click a gadget in this section, ReqChange will try to remove/add the changes that need to be removed/added. In the 'Id file' section there are three gadgets. The one named "Name" allows you to select an idfile with a filerequester. Note that if the full path name is longer than 100 chars, it will Page 19 ReqChange V1.14 User manual ReqChange V1.14 automatically be truncated. The string gadget allows you to read and/or edit the name. The "Read" gadget will read that particular idfile, replacing any old one in memory. This gadget might be disabled. If so, it means that ARexx (i.e. rexxsyslib.library) wasn't available during startup. If you want to delete the idfile in memory, clear the name field, and select "Read". This is because ReqChange will remove the old id file from memory, before trying to read the new file - which might fail. An empty filename means that no file should be read. The "Save" gadget might be disabled. If this is the case, it means that ReqChange couldn't get its name and/or home directory during startup. When you select this gadget, ReqChange will try to access its icon. If there is no icon, nothing will happen. If found, the settings will be saved here. Note that any tooltypes that isn't mentioned in the "Options" section above will be erased! There is one exception though. ReqChange will remember the STARTPRI tooltype. If no one was found during startup, STARTPRI=1 will be written. All gadgets and menues have keyboard equivalents. The key you should press have a litte 'underscore' line. "What about the three gadgets at the bottom??" you ask. Well, as these are equivalents to the menues, you simply use the shortcut for the menu instead! This way, it's also a bit harder to select e.g. quit by mistake. In the centering section, you can still the shift key in combination with the appropriate key to scroll backwards in the list (as with the mouse). To activate the string gadget next to the "Name" gadget, use the "g" key (sorry, no better key available (g as in gadget... :)). In order to make sure that ReqChange gets to know about all changes in string gadgets, make sure that you always terminate an input with a RETURN or TAB keypress. Well, I guess this is about all there is to say about the window. Oh, one more thing. The close gadget does the same thing as the "Hide" gadget (or menu. "Hide" simply closes the window, ReqChange will still be in memory). Break signals ~~~~~~~~~~~~~ In this document, I mention break signals now and then. These are the signals that are sent to a normal CLI-based program if you press CTRL-C, CTRL-D, CTRL-E or CTRL-F. Usually CTRL-C breaks the program (hence the name "Break signals"), while the other ones can do other things, depending on the program. Although ReqChange Page 20 ReqChange V1.14 User manual ReqChange V1.14 detaches from the CLI (and thus is no CLI-based program), you can still send these kind of signals to ReqChange. But this can be a bit cumbersome. A programmer (or similar) could surely do this, provided he had the right software (e.g. Xoper), but the normal user might find this difficult. To solve this problem, I've made a program called SignalRC, which is able to send these break signals to ReqChange. Please refer to the Extra/SignalRC.Man file for further information on how to use this program. Anyway, ReqChange listens to the following signals: C - Tell ReqChange to quit. On OS 1.3, ReqChange will do this, if ReqChange already was running when you started it. E - Update the text to search for to identify a "Please insert volume" requester. F - Open the settings window. Since this only works on OS 2.0, nothing will happen if you do this on OS 1.3. On OS 2.0, ReqChange will do this, if ReqChange already was running when you started it. ReqChange.NF ~~~~~~~~~~~~ Since ReqChange lately has started to grow quite a bit, I've also included a stripped down version, called ReqChange.NF (NF = NoFancy), which excludes the following features (see above for more information about them): o Window interface. Break F signals are ignored. o Sound requesters (IDFILE argument). o Commodities interface. You cannot use the Exchange program to terminate ReqChange. As of this, these keywords have been removed from the stripped down version: o IDFILE o CX_PRIORITY o CX_POPKEY o CX_POPUP o STARTPRI (only needed because of the window interface). All these changes removed about 8 Kb of code from the program. About the code ~~~~~~~~~~~~~~ ReqChange is written mostly in C, with some small assembler Page 21 ReqChange V1.14 User manual ReqChange V1.14 routines and stubs. The program is about 25 Kb big (source is ~230 Kb, including all assembler routines). I compiled it with DICE (assembler part was assembled with the Devpac assembler), which can generate quite small code. 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 entirely i asm though), stack switching, other kinds of glue, and handles the auto-detaching. Each patch allocates and switches in a new stack on 4 Kb, if so needed, to ensure enough space for the requester functions. If no memory was available for a new stack, or the patch runs out of memory, the function in question will return failure. Upon returning, the stack will be freed (if allocated), and the original will be restored. Future improvements ~~~~~~~~~~~~~~~~~~~ I have some ideas of future improvements. These might not be more than ideas, but who knows? :) Anyway, here is a list over them: Rexx interface to access different requesters (this could be really useful. It would be better with a .library though (e.g. similar to rexxarp.library), or a Rexx hook built into ReqTools directly). Localize ReqChange for other languages. It would be quite easy to fix (only problem could be the size of the settings window and the place/size of the gadgets therein). If anyone feels like doing such a translation, feel free to contact me. We could probably work something out. If there is any interest, I could make a Swedish version of ReqChange myself (but do *not* expect me to translate the manual! Writing this manual is ok, but translate it and keep both versions updated, no way! I know what I'm talking about. I have some experience of this from MemClock). (No, I don't know anything about locale.library, except that it can be used for this in some way). Rewrite more code into assembler, to get a smaller program (this is more or less a constant process!). Change the information requester in ReqTools (!!), so that one also can send IDs to UPD (hey, its only a thought! :). A possibility to view the contets of the currently loaded idfile from the window interface (I'm not sure how to do this though... :). Page 22 ReqChange V1.14 User manual ReqChange V1.14 I'm thinking of placing the code that handles all the changes into a separate handler, while keeping most of the other code (window interface, reading of idfile, saving of settings etc.) in another program, to reduce memory usage. This handler would probably be about as large as the NoFancy version of ReqChange. A way to delete (and maybe view too) the deny list (or parts of it). 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*. Also, if anyone has an icon for ReqChange (or the docs) he/she thinks look better than the ones I made, I sure won't mind if you send it to me, and I might use that one instead. I'm not a painter... :) 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 FidoNet mail should go to my point: "Magnus Holmgren" @ 2:204/404.6 or 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. Page 23 ReqChange V1.14 User manual ReqChange V1.14 Acknowledgments ~~~~~~~~~~~~~~~ There are a few persons I feel I must thank, because they have in some way helped me with this program: Matt Dillon - For the great DICE compiler (and for answering all my (more or less silly) questions about C and DICE). Nico Franτois - For reqtools.library (and many other nice programs for the Amiga). This library started this little program. Stefan Boberg - For helping me to debug ReqChange now and then (and one should not forget LhA! :). 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). Jonas Petersson - For Upd (and letting me include it here), to enable ReqChange to have sounding requesters. A Mattias Johansson - For some beta-testing, and for doing all the stuff with my computer equipment (hardware fixes/improvements)! Revision history ~~~~~~~~~~~~~~~~ Please read the History.Doc file for a revision history! May the Amiga be with you! Page 24 ReqChange V1.14 User manual ReqChange V1.14 Table of contents ~~~~~~~~~~~~~~~~~ Legal stuff................................................... 1 Disclaimer.................................................... 1 What is ReqChange?............................................ 1 AutoRequest & EasyRequest.................................. 3 FileRequest................................................ 4 RequestFile & AslRequest................................... 4 TextRequest................................................ 4 GetString & NewGetString................................... 4 GetLong.................................................... 4 ColorRequester & ExtendedColorRequester.................... 4 FileRequester.............................................. 4 Compatibility................................................. 4 Problems...................................................... 5 Installation.................................................. 6 Removing ReqChange............................................ 7 Options....................................................... 8 MINHEIGHT.................................................. 8 MAXHEIGHT.................................................. 9 TOPOFFSET.................................................. 9 LEFTOFFSET................................................. 9 CENTER..................................................... 9 FRCENTER................................................... 10 CENTERTEXT................................................. 10 POPSCR..................................................... 10 BACKFILL................................................... 10 ASSIGN..................................................... 11 KEYS....................................................... 11 ASL........................................................ 11 ARP........................................................ 11 REQ........................................................ 12 FILEBUFFER................................................. 12 FONTBUFFER................................................. 12 IDFILE..................................................... 12 CX_POPKEY.................................................. 13 CX_POPUP................................................... 13 CX_PRIORITY................................................ 13 Centering..................................................... 13 Make assigns.................................................. 14 Idfile format................................................. 15 Input description strings..................................... 18 Window interface.............................................. 18 Break signals................................................. 20 ReqChange.NF.................................................. 21 About the code................................................ 21 Future improvements........................................... 22 Author contact................................................ 23 Snail mail address......................................... 23 E-mail addresses........................................... 23 Page 25 ReqChange V1.14 User manual ReqChange V1.14 Acknowledgements.............................................. 24 Revision history.............................................. 24 Table of contents............................................. 25 Page 26