------------------------------------------------------------------------ MagicFileRequester V1.2 Documentation 17-Mar-1992 ------------------------------------------------------------------------ (C) Copyright 1992 by Stefan Stuntz - All Rights Reserved Copyright --------- The program MagicFileRequester and this documentation are written and copyrighted 1992 by Stefan Stuntz. They may be distributed freely as long as the following restrictions are met: The distributor may only charge a fee up to the costs of obtaining a public domain diskette from Fred Fish. The distributor agrees to cease distributing the programs and data involved if requested to do so by the author. The distributor may only distribute an unmodified copy of the original program, with all the supplied documentation and copyright notices intact. The program must not be used for commercial purposes without the written permission of the author. Disclaimer ---------- This software and documentation is provided "as is". No warranties are made with respect to the accuracy, reliability, performance or operation of this software and information. All use is at your own risk. The author is not responsible for any loss of data, damages to software or hardware that may result directly or indirectly from the use of the described program. Roadmap ------- 0. Revision History 1. What is MFR? 2. Why should I use MFR? 3. Basics 4. System requirements 5. Installation 6. Configuration 7. Using MFR 7.1. ... with mouse 7.2. ... with keyboard 7.3. File actions 7.4. Searching 7.5. CLI Usage 8. Future plans 9. Acknowledgements 0. Revision History ------------------- V1.0 (24-Jan-92): Initial release. V1.1 (05-Mar-92): Sorry, I didn't have the time to implement many new ideas. This version   is just a bug fixed and little enhanced V1.0, so don't expect too much.   New features will come up in near future. - Some minor enhancements in design. - If the specified list font is 9 pixel or smaller, a second set of icons is used. - Because of problems with some programs, MFR will now cut off the slash following a directory name before returning. - An A2024 monitor is no longer considered LoRes. - The contents of Hide & Show gadgets are now passed back to the calling program, so they can be reused at later calls with the same structure. - The key combination now toggles between Drawer and Hide gadget or between File and Show gadget. - Fixed bug with the wrong calculated free disk space. - Fixed some other strange bugs. - MFR can now be called from CLI to pop up a file requester and print the results to stdout. See section 7.5 for details. - Added new tooltype NOTIFY to turn file notification on and off. - You may now select between six different scrollbar designs: Goonie, GoonieSym, Stuntzi, StuntziSym, Kick20 and Kick20Sym, configurable with the tooltypes SCROLLBAR and SCROLLBARL (lores). - MFR now uses the system-suggested colors for rendering (DrawInfo->dri_Pens). Images are also adjusted accordingly. - Late- and Nonbinding-Assigns are now displayed. - Added new tooltype DEFHIDEPAT to specify the a default value for the "Hide" gadget. If the application does not specify a hide pattern (ASL will never), DEFHIDEPAT is used instead. Otherwise, the given pattern and DEFHIDEPAT are concatenated using "(%s|%s)". - FAST keyword now obsolete. Instead, MFR measures the time for finding the next directory entry and increases/decreases its internal entry buffer accordingly. Thus, display refresh is rare with fast medias but often with slow medias. Maximum number of buffered entries is adjustable with the new tooltype ENTRYBUF (1..50). With ENTRYBUF=1, MFR behaves just like FAST=OFF. - Speeded up directory sorting algorithm. This will possibly result in faster directory reading on 68000 based machines. - Since MFR does for some reasons not work with 'AssignX' (I really don't know why... any ideas?), the ASL requester will be called when the window title matches "Assignment for*". V1.2 (17-Mar-92): Sorry again, this is also just a bugfix. I messed up something with the file search mechanism in V1.1. Now it should work. - File searching did not work right in V1.1. Fixed this problem. - MFR 1.1 could only be started from within sys:wbstartup/. This has been fixed. - MFR now also rejects the german AssignX. - Due to a strange compiler behaviour, every string was stored about five times in the executable. This bug has been fixed. - MFR now has a second way of configuration. You may write your tooltype entries to the file "env:mfr.prefs", and MFR will parse them as usual. Entries in mfr.prefs will replace tooltypes in mfr.info with the same name. MFR recognizes changes in "env:mfr.prefs" and reloads it automatically, so you don't have to restart it every time you change your config. - Included the program "TagScreens" from Martin Berndt to force old style screens to use the new Kick 2.x look. 1. What is MFR? --------------- A file requester is propably the most used program inside an Amiga. Since none of the currently available file requesters suited my needs, I decided to write my own. MFR is the result and I hope, you'll enjoy it as as much as I do. 2. Why should I use MFR? ------------------------ · MFR is completely controllable via keyboard, so you will never have to touch your mouse when selecting files (of course you can, if you really want to). · MFR looks very nice, especially on high resolution screens. · MFR will use any font you want in it's display. Proportional fonts like helvetica look really marvellous. · MFR has the ability to quickly search your hard disk for any file, so you needn't remember each file's directory. · MFR can display pictures, play sounds, view archives, etc. with the aid of some external programs. · MFR has a sizing gadget. · MFR takes advantage of new Kick 2.0 features like file notification. · MFR is configurable through a wide range of keywords. · MFR is simply magic :-) 3. Basics --------- MFR is not distributed like other file requesters. You do not get an additional library for your LIBS: drawer and you may not call MFR directly from within your own applications. All you get is a single program that replaces some library vectors at installation time. So every program that uses one of the supported file requesters will use MFR instead. MFR is designed as commodity, so you can control it via the "Exchange"-Program on your Workbench disk. Currently, the only possibility is to quit MFR, but there may come up other things like opening a configuration window in future. MFR is especially designed for the new Kick 2.0 colors and resolutions. It will look best on a high resolution display with a pixel aspect ratio of nearly 1:1 (e.g. Hires + Interlace). Although MFR can be used on low resolution screens too, the 'feeling' won't be there. 4. System requirements ---------------------- As you probably noticed, MFR requires at least Kickstart 2.04 (also known as V37.175) to work properly. If you are still using Kick 1.3, it's time to update now. You won't regret it. Particularly, the following libraries are needed: intuition.library >= v37 graphics.library >= v37 gadtools.library >= v37 diskfont.library >= v36 icon.library >= v37 commodities.library >= v37 utility.library >= v37 asl.library >= v37 req.library >= v1 Make sure, all these libraries are available in your system. MFR will refuse to work if not. 5. Installation --------------- Couldn't be easier. Simply drag the MFR-Icon into your SYS:WBStartup/ drawer, then edit the tool types to suit your needs. Detailed explanation off all tool types can be found in the configuration chapter. If you don't already have a req.library in your libs: directory, copy it to this place. Note that from version 1.1 on, it is no longer possible to start MFR from CLI, since the CLI-Interface is used for popping up a requester. See section 7.5 for details. You may quit MFR with Exchange or bye starting MFR a second time. MFR will pop up a requester to inform you about quitting. Note that you cannot quit MFR if any other program has some FileRequester structures allocated. In this case, you will have to quit all these programs first. 6. Configuration ---------------- MFR is configurable through a wide range of keywords. Note that MFR will possibly not work, if you make some mistakes here, so please read the following chapter carefully. The configuration is stored within the programs icon, thus you have to use the "Information" menu item of your workbench if you want to edit it. Here is a quick list of all known keywords together with a short explanation. DONOTWAIT - Used by workbench. Should be left as is. CX_POPUP - Used by commodities.library. No need to change. CX_POPKEY - Used by commodities.library. No need to change. CX_PRIORITY - Priority of MFR in commodities input chain. Leave as is. LIBS - File requesters to replace. LISTFONT - Font wihtin file and volume list. LFHEIGHT - This font's height. GADFONT - Font within the string gadgets. GFHEIGHT - This font's height. LISTFONTL - Fonts to be used in non interlace screens LFHEIGHTL - "  " GADFONTL - " " GFHEIGHTL - " " SHOWVOL - Pattern for displaying volumes. HIDEVOL - " " SCROLLBAR - Scrollbar design SCROLLBARL - Scrollbar design for lores screens DEFHIDEPAT - Default Hide Pattern MINPIXEL - Minimum size of displayed file name. DEFWIDTH - Dimension and position of MFR's window. DEFHEIGHT - " " ENTRYBUF - Max. number of buffered directory entires OVRDIM - " " OVRPOS - " " CENTER - " " BACKRAST - Background appearance. NOTIFY - Turn on/off file notification Following is a detailed description of every keyword and its parameters. LIBS=[][,][,]... With LIBS, you specify which file requesters should be replaced by MFR. The parameter identifies the library. Valid values for are currently "ASL" and "REQ", referencing asl.library and req.library. So if you want MFR to replace both, the ASL and the REQ requester, you should use LIBS=ASL,REQ If you don't specify a valid library to patch, MFR will refuse to work. LISTFONT=.font LFHEIGHT= These keywords tell MFR which font to use within the file and volume list. You can use every font you want, even proportional fonts are handled correctly and will look marvellous. Note that some of MFR's little icons are 11 pixels high, so smaller fonts won't look too good. Make sure that the given font exists in your FONTS: directory, MFR will refuse to open if not. Example: To specify a 15 pixel Times-Font, you should say LISTFONT=Times.font LFHEIGHT=15 If these two keywords are ommited, the default font helvetica/11 is used to render the lists. GADFONT=.font GFHEIGHT= These keywords tell MFR which font to use when rendering gadgets. Default font is helvetica/13. LISTFONTL=.font LFHEIGHTL= GADFONTL=.font GFHEIGHTL= On lores screens (e.g. non interlace), fonts like helvetica/13 look terrible. Thus, MFR allows configuring a second set of fonts with this four keywords. Default font on lores screens is topaz/8. MINPIXEL= The bigger the file requester, the more information is shown in the file list. MINPIXEL specifies the minimum size reserved to display file names. MFR will hide Flags, Time, Date and Length in the given order to show at least pixels of the filename. If MINPIXEL is ommited, the default value will be 96. SHOWVOL= HIDEVOL= MFR shows a list of all known devices, volumes and assigns. This list can become very large in an average system. With SHOWVOL and HIDEVOL, you may specify which entries should appear in this list. If you give a HIDE pattern and a volume matches this pattern, it will not show up. If you give a SHOW pattern and a volume doesn't match, it will not show up either. So if you e.g. want only your hard drive partitions to appear, you could use SHOWVOL=dh#? Or if you want to hide all assigns concerning your mailbox and your programming environment, HIDEVOL=(mail#?|prog#?) will do it for you. Of course you can use SHOWVOL and HIDEVOL the same time, so SHOWVOL=(dh#?|df#?) HIDEVOL=df4: will show all your hard amd floppy drives, except df4: in the volume list. Note that is case insensitive. If you ommit SHOWVOL and HIDEVOL, or if is empty, all known volumes will appear. DEFWIDTH= DEFHEIGHT= If an application does not specify the size of it's file requester, MFR will appear with the given dimensions. Note that MFR will always adapt it's size to fit on the screen. Default values are 410 for and <350> for height. CENTER=ON/OFF If an application does not specify the position of it's file requester, MFR will appear either in the middle of the current screen (CENTER=ON) or directly under the mouse pointer (CENTER=OFF). Default is CENTER=ON. OVRDIM=ON/OFF OVRPOS=ON/OFF As you propably noticed, MFR will take up more space than e.g. the ASL requester, because of its design. So if you specify OVRDIM=ON, MFR will override the application-told width and height and use the default width and default height instead. This useful option is ON by default. OVRPOS works for positions like OVRDIM for dimensions. Thus, MFR will appear as specified with CENTER, if OVRPOS=ON. By default, this option is enabled, so if you use the default values, MFR will always appear in a useful position and size. BACKRAST=ON/OFF By default, the background of MFR's window appears rastered in the darkest color. If you do not like this outfit, specify BACKRAST=OFF. Note that MFR automagically turns of rastered background on non interlace screens. CLASS_=[],[], With the CLASS_ keywords, you can tell MFR what to do with different file classes. This allows MFR to show pictures, play sounds, view archives, etc.. There are twenty possible file classes, so you can use CLASS_0 through CLASS_9 as keywords. If you select the "Action" menu item, MFR checks the current file against . If this one matches, MFR checks the first 256 Bytes of the file against . In case of match, the command is performed on this file. Note that is case insensitive but is case sensitive. An ommited pattern matches always. The parameter must be a valid command, exactly as if typed into a CLI. The first "%s" in will be replaced with the full path specification of the current file. Note that formatting of the command is done via sprintf() (because of my laziness), so you should be careful not to use other printf style formatting commands such as "%l" or "%x". Your machine may crash if you do so! If you use commands that print to the current console (e.g. all archivers), you must use IO-redirection. Some examples for file classes are: CLASS_0=*.(lha|lzh),,lz >con:120/50/500/250/LH-Archive/CLOSE/WAIT v %s CLASS_1=*.zoo,,zoo l >con:120/50/500/250/Zoo-Archive/CLOSE/WAIT l %s CLASS_2=*,FORM????ILBM*,mostra %s CLASS_3=*,FORM????8SVX*,play %s CLASS_4=*.rexx,/*,rx %s Since the configuration mechanism is going to change, I am too lazy to descripe the new keywords in detail here. See revision history for a short explanation. 7. Using MFR ------------ 7.1. ... with mouse ------------------- Using MFR with a mouse is not too different from using other file requesters, so I won't say too much about it. Just klick on a directory or volume to enter it. The "Parent" gadget is located beside the "Directory" gadget and will try to change to the parent directory (Note that this action can also be performed with the middle mouse button, if you have one). A double klick on a file will exit MFR, returning this file to the calling program. The "Okay" gadget will exit MFR with the file currently displayed in the "File" gadget being returned. If the calling program enables this feature, you may select multiple files by holding the Shift-Key and single klicking some files. Additionally, MFR offers some menus. Try them! 7.2. ... with keyboard ---------------------- You don't have to touch your mouse anymore, MFR can be controlled completely via keyboard, without loosing any features. MFR's window has got six input areas, as there are directory and device list and the four string gadgets. You may cycle through these areas with either TAB and Shift-TAB or with AMIGA-'.' and AMIGA-','. Additionally, you may activate a specific list by pressing AMIGA-1 to AMIGA-6. Look at MFR's menu items, if you forget some shortcuts. Within directory and device list, you can move up and down with the cursor keys and some qualifiers. To walk through directories, you may press RETURN or CURSOR RIGHT to enter, AMIGA-P or CURSOR LEFT to leave a directory. Pressing RETURN on a file will exit the file requester with this file being returned. If Multiselect is enabled, you may additionally select and deselect a file using the SPACE key. The ESCAPE key and Amiga-Q are synomyms for the 'Cancel' gadget, Amiga-O activates the 'Okay' gadget. Note that all key combinations will also work from within a string gadget. 7.3. File actions ----------------- File actions allow you to display pictures, play sounds, do anything you want with a particular file. Of course, the CLASS_ tool types must be initialized correctly for this feature to work. A file action is performed by pressing AMIGA-F or Alt-RETURN. The current file (the file under the cursor) will then be tested against your file classes and the appropriate action will be performed. If the file doesn't match any class, no action will take place. 7.4. Searching -------------- MFR has the ability to quickly search your devices for specific files. This feature works only in conjuction with the FIND-Package from Larry Phillips, which is included in MFR's distribution archive. First, you will have to create a data base with the program 'UpdateDB'. Refer to Larry's 'find.doc' for details. After this step, you may type some file name into MFR's string gadget and then press AMIGA-S or use the gadget labeled '?'. The data base will be searched for your file and all occurances will be displayed, together with their directory. You may then select the desired file with the cursor keys and RETURN or by clicking the mouse. The way of searching can be influenced by the 'Search' menu, the menu items should speak for themselves. Additionally, you can specify a pattern to search for in the file gadget. Note that this will take a little longer, because DOS-Library's pattern matching isn't the fastest. 7.5. CLI Usage -------------- From version 1.1 on, MFR has a CLI interface that allows using the requester from within script files. Calling MFR with the following template mfr [DIR=] [FILE=] [PATTERN=] [TITLE=] [OKTEXT=<oktext>] [CANCELTEXT=<canceltext>] [LEFT=<left>] [TOP=<top>] [WIDTH=<width>] [HEIGHT=<height>] [MULTI] [MATCHDIRS] [SAVE] [PATGAD] will pop up a file requester, wait for the user to select some file and print the results (full path specification) to stdout. If the requester is cancelled, nothing is displayed. You can use this feature from a shell or arexx script, redirecting the result to a file for further usage. For example, the command mfr >env:result DIR=cap: PATTERN=*.cap TITLE="Select a capture file" will create an environment variable named 'result' which consists of the selected file. If you don't select a file, 'result' will be empty. MFR will return 0 if a file was selected, 5 if the requester was cancelled. A return code of 10 indicates an error (wrong parameters, out of memory, ...). Note that MFR will internally call the asl.library file requester, so if you didn't allow it to patch this library, you will just see an ASL requester popping up. 8. Future plans --------------- - Support for the AslHook-, DoWildFunc- and DoMsgFunc-TagItems. Tell me a program that makes use of these Tags, so I can test it. - Directory caching between multiple calls. Since this program is designed for Kick 2.0, A3000 and fast HDs, this feature wasn't considered too important. - Disabling File-Gadget whithin a DIRONLY requester. Sorry, I was too lazy to do that for this version. Will be corrected in next release. - Nice configuration window. MFR will become a sys:prefs/ Preferences tool. Configuration will be moved from ToolTypes to envarc: and env: - Filename completor. Woul be nice, I think. - Directory sorting according to date or size. Why not? - Multi-Selects from different directories. Is there really any need for that? - Replacing of arp-, reqtools- and kd_freq-library. I hope all programs will use the standard ASL file requester in near future, so there is propably no need to replace all the other libs. BTW: There's a tool out there named 'ArpToAsl' by Fabio Rosetti. It works fine in conjunction with MFR. - Replacing of the font requesters. If DPaint would use an external font requester, this feature would already have been implemented. - DeleteFile option, MakeDir option. In my wildest dreams, I think of two or more communicating MFRs, making up a nice CLI tool together. - I received many other ideas from people all over the world, and they all found their way into my "brainstorm" file. If you can't find your   suggestions here, it's just because I am too lazy to transform this   "brainstorm" file into a human readable form. :-) If you have some additional ideas and/or bug reports, feel free to send a letter (E-Mail preferred) or to give me a call. You can reach me via Internet: stuntz@informatik.tu-muenchen.de Fido....: 2:246/46.10 (Stefan Stuntz) Z-Netz..: S.STUNTZ@AMC.ZER Snail...: Stefan Stuntz Eduard-Spranger Straße 7 D-8000 München 45   Germany Phone: 089 / 313 12 48 9. Acknowledgements ------------------- Last of all, I want to thank Andreas Schildbach for many good ideas and for some artwork. Martin Berndt for debugging, debugging and debugging again and for the permission to include his program "TagScreens". Michael Berger for the set of Lores Icons. Ralf Kemle & for some more ideas and for testing MFR with Oliver Kilian good old 68000er. Oliver Vaross for additional debugging. Larry Phillips for the "Find" package. I hope I may include it in the MFR archive. Fabio Rosetti for his program "ArpToAsl". I hope I may include it in the MFR archive. ... and all the other guys and girls (!) who reported bugs and made suggestions. That's all for now. Sorry for the propably too short docs, but I just finished writing a big documentation for another project some time ago and now I'm really fed up. I hope you will enjoy your new file requester. Goodbye now, and thanks for all the fish... Stefan Stuntz