home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Club Amiga de Montreal - CAM
/
CAM_CD_1.iso
/
files
/
620.lha
/
MFR_v1.1
/
mfr.doc.pp
/
mfr.doc
Wrap
Text File
|
1992-03-12
|
23KB
|
647 lines
------------------------------------------------------------------------
MagicFileRequester V1.1 Documentation 05-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 <Alt><Return> 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*".
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=[<lib>][,<lib>][,<lib>]...
With LIBS, you specify which file requesters should be replaced by MFR.
The parameter <lib> identifies the library. Valid values for <lib> 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=<name>.font
LFHEIGHT=<height>
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=<name>.font
GFHEIGHT=<height>
These keywords tell MFR which font to use when rendering gadgets.
Default font is helvetica/13.
LISTFONTL=<name>.font
LFHEIGHTL=<height>
GADFONTL=<name>.font
GFHEIGHTL=<height>
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=<size>
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 <size> pixels of the filename. If MINPIXEL is ommited,
the default value will be 96.
SHOWVOL=<pattern>
HIDEVOL=<pattern>
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 <pattern> is case insensitive.
If you ommit SHOWVOL and HIDEVOL, or if <pattern> is empty, all known
volumes will appear.
DEFWIDTH=<width>
DEFHEIGHT=<height>
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 <width> 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_<n>=[<namepattern>],[<contentspattern>],<action>
With the CLASS_<n> 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 <namepattern>. If this one matches, MFR checks the first 256
Bytes of the file against <contentspattern>. In case of match, the
command <action> is performed on this file. Note that <namepattern> is
case insensitive but <contentspattern> is case sensitive. An ommited
pattern matches always.
The parameter <action> must be a valid command, exactly as if typed into
a CLI. The first "%s" in <action> 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_<n> 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=<dir>] [FILE=<file>] [PATTERN=<pattern>] [TITLE=<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
Zerberus: S.STUNTZ@AMC.ZER
Fido....: 2:246/46.10 (Stefan Stuntz)
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.
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.
... 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