home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 607.lha / MagicFileRequester_v1.0 / mfr.doc.pp / mfr.doc
Text File  |  1992-02-05  |  18KB  |  526 lines
  1. ------------------------------------------------------------------------
  2. MagicFileRequester V1.0 Documentation                        24-Jan-1992
  3. ------------------------------------------------------------------------
  4.  
  5.       (C) Copyright 1992 by Stefan Stuntz - All Rights Reserved
  6.  
  7.  
  8. Politics
  9. --------
  10.  
  11. The  program  MagicFileRequester  and this documentation are written and
  12. copyrighted  1992  by  Stefan Stuntz.  They may be distributed freely as
  13. long as the following restrictions are met:
  14.  
  15. The  distributor  may  only  charge a fee up to the costs of obtaining a
  16. public  domain diskette from Fred Fish.  The distributor agrees to cease
  17. distributing the programs and data involved if requested to do so by the
  18. author.   The  distributor may only distribute an unmodified copy of the
  19. original  program,  with  all  the  supplied documentation and copyright
  20. notices intact.
  21.  
  22. The program must not be used for commercial purposes without the written
  23. permission of the author.
  24.  
  25. The  author is in no way responsible for any damage caused by the use or
  26. misuse of this program.
  27.  
  28.  
  29.  
  30. Roadmap
  31. -------
  32.  
  33.  1.   What is MFR?
  34.  2.   Why should I use MFR?
  35.  3.   Basics
  36.  4.   System requirements
  37.  5.   Installation
  38.  6.   Configuration
  39.  7.   Using MFR
  40.  7.1. ... with mouse
  41.  7.2. ... with keyboard
  42.  7.3. File actions
  43.  7.4. Searching
  44.  8.   Future plans
  45.  9.   Version history
  46. 10.   Acknowledgements
  47.  
  48.  
  49.  
  50. 1. What is MFR?
  51. ---------------
  52.  
  53. A  file  requester  is  propably  the most used program inside an Amiga.
  54. Since none of the currently available file requesters suited my needs, I
  55. decided  to write my own.  MFR is the result and I hope, you'll enjoy it
  56. as as much as I do.
  57.  
  58.  
  59.  
  60. 2. Why should I use MFR?
  61. ------------------------
  62.  
  63. · MFR is completely controllable via keyboard, so you will never have
  64.   to touch your mouse when selecting files (of course you can, if you
  65.   really want to).
  66.  
  67. · MFR looks very nice, especially on high resolution screens.
  68.  
  69. · MFR will use any font you want in it's display. Proportional fonts
  70.   like helvetica look really marvellous.
  71.  
  72. · MFR has the ability to quickly search your hard disk for any file,
  73.   so you needn't remember each file's directory.
  74.  
  75. · MFR can display pictures, play sounds, view archives, etc. with
  76.   the aid of some external programs.
  77.  
  78. · MFR has a sizing gadget.
  79.  
  80. · MFR takes advantage of new Kick 2.0 features like file notification.
  81.  
  82. · MFR is configurable through a wide range of keywords.
  83.  
  84. · MFR is simply magic :-)
  85.  
  86.  
  87.  
  88. 3. Basics
  89. ---------
  90.  
  91. MFR  is  not  distributed like other file requesters.  You do not get an
  92. additional  library  for  your  LIBS:   drawer  and you may not call MFR
  93. directly from within your own programs.  All you get is a single program
  94. that  replaces  some  library  vectors  at  installation time.  So every
  95. program  that  uses  one  of  the supported file requesters will use MFR
  96. instead.
  97.  
  98. MFR   is   designed  as  commodity,  so  you  can  control  it  via  the
  99. "Exchange"-Program   on   your  Workbench  disk.   Currently,  the  only
  100. possibility  is  to  quit  MFR,  but there may come up other things like
  101. opening a configuration window in future.
  102.  
  103. MFR  is especially designed for the new Kick 2.0 colors and resolutions.
  104. It will look best on a high resolution display with a pixel aspect ratio
  105. of  nearly  1:1  (e.g.  Hires + Interlace).  Although MFR can be used on
  106. low resolution screens too, the 'feeling' won't be there.
  107.  
  108.  
  109.  
  110. 4. System requirements
  111. ----------------------
  112.  
  113. As  you  probably  noticed,  MFR  requires at least Kickstart 2.04 (also
  114. known  as  V37.175)  to work properly.  If you are still using Kick 1.3,
  115. it's time to update now.  You won't regret it.
  116.  
  117. Particularly, the following libraries are needed:
  118.  
  119. intuition.library   v37
  120. graphics.library    v37
  121. gadtools.library    v37
  122. diskfont.library    v36
  123. icon.library        v37
  124. commodities.library v37
  125. utility.library     v37
  126. asl.library         v37
  127. req.library         v1
  128.  
  129. Make sure, all these libraries are available in your system. MFR
  130. will refuse to work if not.
  131.  
  132.  
  133.  
  134. 5. Installation
  135. ---------------
  136.  
  137. Couldn't  be  easier.  Simply drag the MFR-Icon into your SYS:WBStartup/
  138. drawer,  then  edit  the  tool  types  to  suit  your  needs.   Detailed
  139. explanation  off  all  tool  types  can  be  found  in the configuration
  140. chapter.   If  you  don't  already  have  a  req.library  in  your libs:
  141. directory, copy it to this place.
  142.  
  143.  
  144.  
  145. 6. Configuration
  146. ----------------
  147.  
  148. MFR  is  configurable  through  a wide range of keywords.  Note that MFR
  149. will  possibly  not work, if you make some mistakes here, so please read
  150. the following chapter carefully.
  151.  
  152. The  configuration  is stored within the programs icon, thus you have to
  153. use  the  "Information"  menu item of your workbench if you want to edit
  154. it.   Here  is  a quick list of all known keywords together with a short
  155. explanation.
  156.  
  157. DONOTWAIT   - Used by workbench. Should be left as is.
  158. CX_POPUP    - Used by commodities.library. No need to change.
  159. CX_PRIORITY - Priority of MFR in commodities input chain. Leave as is.
  160. LIBS        - File requesters to replace.
  161. LISTFONT    - Font wihtin file and volume list.
  162. LFHEIGHT    - This font's height.
  163. GADFONT     - Font within the string gadgets.
  164. GFHEIGHT    - This font's height.
  165. LISTFONTL   - Fonts to be used in non interlace screens
  166. LFHEIGHTL   -              "            "
  167. GADFONTL    -              "            "
  168. GFHEIGHTL   -              "            "
  169. MINPIXEL    - Minimum size of displayed file name.
  170. SHOWVOL     - Pattern for displaying volumes.
  171. HIDEVOL     -          "         "
  172. DEFWIDTH    - Dimension and position of MFR's window.
  173. DEFHEIGHT   -            "          "
  174. CENTER      -            "          "
  175. OVRDIM      -            "          "
  176. OVRPOS      -            "          "
  177. BACKRAST    - Background appearance.
  178. PROP3D      - Scrollbar outfit.
  179. FAST        - Directory reading mode.
  180. CLASS_<n>   - File class specification.
  181.  
  182.  
  183. Following is a detailed description of every keyword and its parameters.
  184.  
  185.  
  186. LIBS=[<lib>][,<lib>][,<lib>]...
  187.  
  188.   With  LIBS, you specify which file requesters should be replaced by MFR.
  189.   The  parameter <lib> identifies the library.  Valid values for <lib> are
  190.   currently  "ASL" and "REQ", referencing asl.library and req.library.  So
  191.   if  you  want  MFR  to  replace both, the ASL and the REQ requester, you
  192.   should use
  193.  
  194.   LIBS=ASL,REQ
  195.  
  196.   If  you  don't  specify  a  valid  library to patch, you will just get a
  197.   single demo requester.
  198.  
  199.  
  200. LISTFONT=<name>.font
  201. LFHEIGHT=<height>
  202.  
  203.   These  keywords  tell  MFR  which font to use within the file and volume
  204.   list.   You  can  use  every  font you want, even proportional fonts are
  205.   handled  correctly  and  will  look marvellous.  Note that some of MFR's
  206.   little  icons  are 11 pixels high, so smaller fonts won't look too good.
  207.   Make sure that the given font exists in your FONTS:  directory, MFR will
  208.   refuse to open if not.
  209.  
  210.   Example: To specify a 15 pixel Times-Font, you should say
  211.  
  212.   LISTFONT=Times.font
  213.   LFHEIGHT=15
  214.  
  215.   If these two keywords are ommited, the default font helvetica/11 is used
  216.   to render the lists.
  217.  
  218.  
  219. GADFONT=<name>.font
  220. GFHEIGHT=<height>
  221.  
  222.   These keywords tell MFR which font to use when rendering gadgets.
  223.   Default font is helvetica/13.
  224.  
  225.  
  226. LISTFONTL=<name>.font
  227. LFHEIGHTL=<height>
  228. GADFONTL=<name>.font
  229. GFHEIGHTL=<height>
  230.  
  231.   On  lores  screens  (e.g.   non interlace), fonts like helvetica/13 look
  232.   terrible.   Thus, MFR allows configuring a second set of fonts with this
  233.   four keywords.  Default font on lores screens is topaz/8.
  234.  
  235.  
  236. MINPIXEL=<size>
  237.  
  238.   The bigger the file requester, the more information is shown in the file
  239.   list.  MINPIXEL  specifies  the  minimum  size  reserved to display file
  240.   names.  MFR will hide Flags, Time, Date and Length in the given order to
  241.   show  at  least  <size> pixels of the filename.  If MINPIXEL is ommited,
  242.   the default value will be 96.
  243.  
  244.  
  245. SHOWVOL=<pattern>
  246. HIDEVOL=<pattern>
  247.  
  248.   MFR  shows  a list of all known devices, volumes and assigns.  This list
  249.   can  become  very large in an average system.  With SHOWVOL and HIDEVOL,
  250.   you may specify which entries should appear in this list.  If you give a
  251.   HIDE pattern and a volume matches this pattern, it will not show up.  If
  252.   you  give a SHOW pattern and a volume doesn't match, it will not show up
  253.   either.  So if you e.g.  want only your hard drive partitions to appear,
  254.   you could use
  255.  
  256.   SHOWVOL=dh#?
  257.  
  258.   Or  if  you  want  to  hide all assigns concerning your mailbox and your
  259.   programming environment,
  260.  
  261.   HIDEVOL=(mail#?|prog#?)
  262.  
  263.   will  do it for you.  Of course you can use SHOWVOL and HIDEVOL the same
  264.   time, so
  265.  
  266.   SHOWVOL=(dh#?|df#?)
  267.   HIDEVOL=df4:
  268.  
  269.   will  show  all  your hard amd floppy drives, except df4:  in the volume
  270.   list.  Note that <pattern> is case insensitive.
  271.  
  272.   If  you  ommit  SHOWVOL and HIDEVOL, or if <pattern> is empty, all known
  273.   volumes will appear.
  274.  
  275.  
  276. DEFWIDTH=<width>
  277. DEFHEIGHT=<height>
  278.  
  279.   If  an application does not specify the size of it's file requester, MFR
  280.   will  appear with the given dimensions.  Note that MFR will always adapt
  281.   it's  size to fit on the screen.  Default values are 410 for <width> and
  282.   <350> for height.
  283.  
  284.  
  285. CENTER=ON/OFF
  286.  
  287.   If  an application does not specify the position of it's file requester,
  288.   MFR  will  appear either in the middle of the current screen (CENTER=ON)
  289.   or directly under the mouse pointer (CENTER=OFF).  Default is CENTER=ON.
  290.  
  291.  
  292. OVRDIM=ON/OFF
  293. OVRPOS=ON/OFF
  294.  
  295.   As  you propably noticed, MFR will take up more space than e.g.  the ASL
  296.   requester, because of its design.  So if you specify OVRDIM=ON, MFR will
  297.   override the application-told width and height and use the default width
  298.   and default height instead.  This useful option is ON by default.
  299.  
  300.   OVRPOS  works  for positions like OVRDIM for dimensions.  Thus, MFR will
  301.   appear  as specified with CENTER, if OVRPOS=ON.  By default, this option
  302.   is  enabled, so if you use the default values, MFR will always appear in
  303.   a useful position and size.
  304.  
  305.  
  306. BACKRAST=ON/OFF
  307.  
  308.   By  default,  the  background  of  MFR's  window appears rastered in the
  309.   darkest  color.   If  you do not like this outfit, specify BACKRAST=OFF.
  310.   Note  that  MFR  automagically  turns  of  rastered  background  on  non
  311.   interlace screens.
  312.  
  313.  
  314. PROP3D=ON/OFF
  315.  
  316.   MFR  uses  it's  own  three dimensional scrollbar design.  If you do not
  317.   like  this,  specify  PROP3D=OFF  and  you will get a standard intuition
  318.   knob.  Note that MFR will automagically switch to the standard scrollbar
  319.   when appearing on a non 3d screen.
  320.  
  321.  
  322. FAST=ON/OFF
  323.  
  324.   By default, MFR displays each new directory entry when it is read.  This
  325.   looks nice and is useful sometimes, but takes a little extra time.  When
  326.   you  specify  FAST=ON,  MFR  will  first read the entire directory, then
  327.   display  it.  Nevertheless you may use the file requester while reading,
  328.   so you will never have to wait for the entire directory to be read.
  329.  
  330.  
  331. CLASS_<n>=[<namepattern>],[<contentspattern>],<action>
  332.  
  333.   With  the CLASS_<n> keywords, you can tell MFR what to do with different
  334.   file  classes.   This  allows  MFR  to  show pictures, play sounds, view
  335.   archives,  etc..  There are twenty possible file classes, so you can use
  336.   CLASS_0 through CLASS_19 as keywords.
  337.  
  338.   If  you  select  the  "Action"  menu  item,  MFR checks the current file
  339.   against  <namepattern>.   If  this one matches, MFR checks the first 256
  340.   Bytes  of  the  file  against  <contentspattern>.  In case of match, the
  341.   command  <action> is performed on this file.  Note that <namepattern> is
  342.   case  insensitive  but  <contentspattern> is case sensitive.  An ommited
  343.   pattern matches always.
  344.  
  345.   The parameter <action> must be a valid command, exactly as if typed into
  346.   a  CLI.   The first "%s" in <action> will be replaced with the full path
  347.   specification  of the current file.  Note that formatting of the command
  348.   is done via sprintf() (because of my laziness), so you should be careful
  349.   not  to use other printf style formatting commands such as "%l" or "%x".
  350.   Your  machine may crash if you do so!  If you use commands that print to
  351.   the current console (e.g.  all archivers), you must use IO-redirection.
  352.  
  353.   Some examples for file classes are:
  354.  
  355.   CLASS_0=*.(lha|lzh),,lz >con:120/50/500/250/LH-Archive/CLOSE/WAIT v %s
  356.   CLASS_1=*.zoo,,zoo l >con:120/50/500/250/Zoo-Archive/CLOSE/WAIT l %s
  357.   CLASS_2=*,FORM????ILBM*,mostra %s
  358.   CLASS_3=*,FORM????8SVX*,play %s
  359.   CLASS_4=*.rexx,/*,rx %s
  360.  
  361.  
  362.  
  363. 7. Using MFR
  364. ------------
  365.  
  366. 7.1. ... with mouse
  367. -------------------
  368.  
  369. Using  MFR  with  a  mouse  is  not  too different from using other file
  370. requesters, so I won't say too much about it.  Just klick on a directory
  371. or  volume  to  enter  it.   The  "Parent"  gadget is located beside the
  372. "Directory" gadget and will try to change to the parent directory.
  373.  
  374. A  double  klick  on  a  file  will exit MFR, returning this file to the
  375. calling  program.   The  "Okay"  gadget  will  exit  MFR  with  the file
  376. currently displayed in the "File" gadget being returned.  If the calling
  377. program  enables  this feature, you may select multiple files by holding
  378. the Shift-Key and single klicking some files.
  379.  
  380. Additionally, MFR offers some menus. Try them!
  381.  
  382.  
  383. 7.2. ... with keyboard
  384. ----------------------
  385.  
  386. You  don't  have  to  touch  your  mouse  anymore, MFR can be controlled
  387. completely via keyboard, without loosing any features.  MFR's window has
  388. got six input areas, as there are directory and device list and the four
  389. string  gadgets.   You may cycle through these areas with either TAB and
  390. Shift-TAB  or  with  AMIGA-'.'  and  AMIGA-','.   Additionally,  you may
  391. activate  a specific list by pressing AMIGA-1 to AMIGA-6.  Look at MFR's
  392. menu items, if you forget some shortcuts.
  393.  
  394. Within  directory  and  device  list,  you can move up and down with the
  395. cursor  keys  and some qualifiers.  To walk through directories, you may
  396. press RETURN or CURSOR RIGHT to enter, AMIGA-P or CURSOR LEFT to leave a
  397. directory.
  398.  
  399. Pressing  RETURN  on  a file will exit the file requester with this file
  400. being  returned.  If Multiselect is enabled, you may additionally select
  401. and deselect a file using the SPACE key.
  402.  
  403. The ESCAPE key and Amiga-Q are synomyms for the 'Cancel' gadget, Amiga-O
  404. activates  the  'Okay' gadget.  Note that all key combinations will also
  405. work from within a string gadget.
  406.  
  407.  
  408. 7.3. File actions
  409. -----------------
  410.  
  411. File actions allow you to display pictures, play sounds, do anything you
  412. want  with  a particular file.  Of course, the CLASS_<n> tool types must
  413. be  initialized  correctly  for  this feature to work.  A file action is
  414. performed by pressing AMIGA-F or Alt-RETURN.  The current file (the file
  415. under  the cursor) will then be tested against your file classes and the
  416. appropriate  action  will  be  performed.  If the file doesn't match any
  417. class, no action will take place.
  418.  
  419.  
  420.  
  421. 7.4. Searching
  422. --------------
  423.  
  424. MFR  has  the ability to quickly search your devices for specific files.
  425. This  feature  works only in conjuction with the FIND-Package from Larry
  426. Phillips,  which  is included in MFR's distribution archive.  First, you
  427. will  have  to create a data base with the program 'UpdateDB'.  Refer to
  428. Larry's 'find.doc' for details.  After this step, you may type some file
  429. name  into  MFR's string gadget and then press AMIGA-S or use the gadget
  430. labeled  '?'.   The  data  base  will  be searched for your file and all
  431. occurances  will  be  displayed, together with their directory.  You may
  432. then  select  the  desired  file  with  the cursor keys and RETURN or by
  433. clicking the mouse.
  434.  
  435. The  way  of  searching can be influenced by the 'Search' menu, the menu
  436. items  should  speak  for  themselves.   Additionally, you can specify a
  437. pattern  to  search  for in the file gadget.  Note that this will take a
  438. little longer, because DOS-Library's pattern matching isn't the fastest.
  439.  
  440.  
  441.  
  442. 8. Future plans
  443. ---------------
  444.  
  445. - Support for the AslHook-, DoWildFunc- and DoMsgFunc-TagItems.
  446.   Tell me a program that makes use of these Tags, so I can test it.
  447.  
  448. - Directory caching between multiple calls.
  449.   Since this program is designed for Kick 2.0, A3000 and fast HDs,
  450.   this feature wasn't considered too important.
  451.  
  452. - Disabling File-Gadget whithin a DIRONLY requester.
  453.   Sorry, I was too lazy to do that for this version. Will be corrected
  454.   in next release.
  455.  
  456. - Nice configuration window.
  457.   I am not sure if this is really neccesary.
  458.  
  459. - Filename completor.
  460.   Woul be nice, I think.
  461.  
  462. - Directory sorting according to date or size.
  463.   Why not?
  464.  
  465. - Multi-Selects from different directories.
  466.   Is there really any need for that?
  467.  
  468. - Replacing of arp-, reqtools- and kd_freq-library.
  469.   I hope all programs will use the standard ASL file requester in near
  470.   future, so there is propably no need to replace all the other libs.
  471.   BTW: There's a tool out there named 'ArpToAsl' by Fabio Rosetti. It
  472.   works fine in conjunction with MFR.
  473.  
  474. - Replacing of the font requesters.
  475.   If DPaint would use an external font requester, this feature would
  476.   already have been implemented.
  477.  
  478. - Delete files option.
  479.   In my wildest dreams, I think of two or more communicating MFRs,
  480.   making up a nice CLI tool together.
  481.  
  482.  
  483. If you have some additional ideas and/or bug reports, feel free to send
  484. a letter or to give me a call. You can reach me via
  485.  
  486. Internet: stuntz@informatik.tu-muenchen.de
  487. Fido....: 2:246/46.10 (Stefan Stuntz)
  488. Snail...: Stefan Stuntz
  489.           Eduard-Spranger Straße 7
  490.           D-8000 München 45
  491.           Germany
  492.           Phone: 089 / 313 12 48
  493.  
  494.  
  495.  
  496. 9. Version history
  497. ------------------
  498.  
  499. V1.0 (24-Jan-92): Initial release.
  500.  
  501.  
  502.  
  503. 10. Acknowledgements
  504. --------------------
  505.  
  506. Last of all, I want to thank
  507.  
  508. Andreas Schildbach  for many good ideas and for some artwork.
  509.  
  510. Ralf Kemle &        for some more ideas and for testing MFR with
  511. Oliver Kilian       good old 68000er.
  512.  
  513. Oliver Vaross       for additional debugging.
  514.  
  515. Larry Phillips      for the FIND package. I hope I may include
  516.                     it in the MFR archive.
  517.  
  518.  
  519. That's  all  for now.  Sorry for the propably too short docs, but I just
  520. finished  writing a big documentation for another project some weeks ago
  521. and  now  I'm  really  fed  up.   I  hope  you  will enjoy your new file
  522. requester.
  523.  
  524. Goodbye now, and thanks for all the fish...
  525.                                                            Stefan Stuntz
  526.