Help file accompanying the multitasking !FileTree application :
*************************************************************

***************************  Copyright Notice  ***************************
*                                                                        *
*   The object code and documentation for the '!FileTree' application,   *
*   module 'FontMenu' and its documentation 'FntMenuDoc' excluded,       *
*   are the exclusive copyright of John A.M. TYTGAT and are freely       *
*   distributable, provided this notice is left intact and all of the    *
*   files listed below are included, UNALTERED.                          *
*                                                                        *
*   Note that the 'FontMenu' module and its documentation 'FntMenuDoc'   *
*   is written by Joris Rling and so you should also refer to his       *
*   copyright notice.                                                    *
*                                                                        *
**************************************************************************

Included :
========

     (1) !Run file
     (2) !RunImage  (main program)
     (3) !Sprites
     (4) !Help application
     (5) FontMenuJR (written by Joris Rling)
     (6) FntMenuDoc (document about FontMenu)

Due to a module name clash, I had to rename 'FontMenu' (together with its SWI base name) to 'FontMenuJR'.  'FontMenu' is now the name of one of the RISC OS Toolbox modules.

Aim :
===

!FileTree allows you to create Draw files containing the file tree structure of any disc medium (most probably a harddisc).

I wrote this program because I wanted to know from time to time the disc structure of my harddisc.  There are a few commercial programs which can also show the file tree structure but as far as I know they have not any print facilities.  The Draw files produced with !FileTree can be printed by your favourite Draw printing application (e.g. !Draw itself).

BASS :
====

!FileTree is been released as a BASS product.  BASS (Belgian Acorn Software-writers Society) is a group of young enthousiast software-writers who like to write RISC OS programs.

Use :
===

Double click on !FileTree's filer icon and its window will open :

Section 'Directory' :

At the top of the window you can fill in the directory to be scanned.  Instead of explicit filling in this icon, you can choose an entry from a menu which can be obtained by clicking on the menu button when the pointer is on the 'Right Arrow' icon.

Note that the pointer is context sensitive and will change in a caret when you can type text and will change in a small menu when you can press the menu button for a special menu entry (cfr. Computer Concepts' user interface).  This interface has been used several times in !FileTree and will not being repeated each time in this manual.

By dragging a directory from the filer window to the !FileTree window will automatically set the scanning directory.

Section 'Text' :

In this section you can choose which font (outline or bitmap) !FileTree will use in its Draw files.  The first font in the menu list is called 'SystemFont' and is the only not-outline font but the default RISC OS system font and is always available.

If other outline fonts are known to the system they will also be displayed in the menu and then you can also select the 'Font Size'.  Note that the 'Font Size' entry does not apply for the SystemFont.

Section 'Sprites' :

In the Draw file !FileTree places the sprite icon of each filename/directory/application entry at the left size of their name.  Normally two versions of filer sprites are known to the system : small and big ones.  You can choose either of them : the small sprite is preferred if you are concerned about the Draw file size but the big sprite gives better print results.

But if the selected version of the sprite is not found, !FileTree will take the other version.  When the other version is also not known then the 'default application' sprite or the 'unknown filetype' sprite is taken.

It is also possible to enlarge/shrink the sprites.  The default size of 'Magnify sprite' is 100 % but if you fill in 0 % no sprites are placed in the Draw file.  If you use the 'Big sprites' option a reasonable 'Magnify sprite' option is 50 %.

With some applications/files which have not been 'seen' by the filer !FileTree can avoid that they get the default 'application'/'unknown filetype' sprite in the Draw output.  You do this by selecting the icon 'Make own sprite pool', so !FileTree will make its own sprite pool by merging each application's !Sprites22 file (or !Sprites file when !Sprites22 doesn't exist) during its scan through the directories.

Note that this sprite pool is NOT build up in the RMA area avoiding excessive RMA memory usage.  When this option is selected it will take a bit more time to construct the Draw files but the results are much better.

Section 'Page Size' :

In the 'Page Size' section you can fill in which paper size, page orientaion and border size you want to use.  Default the A4 paper size is selected but when the printer driver is installed you can select 'Printer Dim' from the 'Size' menu and paper size & borders will be set like the printer driver settings.  It is advisable to do the latter when you want to print out the generated Draw files.

Note that it is possible that some objects in the Draw file do cross the boundary (it is nearly impossible to program otherwise and lucky enough the printer driver will automatically cut the print borders off) but these objects are repeated on the next Draw file so it is very easy to make a large poster of the !FileTree Draw files.  That is the reason why I added the option 'Mark borders' : when this option is selected each Draw file will have got small lines showing the borders lines.

Section 'File Size Count' :

With !FileTree it is also possible to have a more accurate file size count than the RISC OS Count instruction gives you.  You can switch this option on and off by clicking on 'Count the size of the files'.  The option 'Count the size of the directories' allows to count the dir size as well.  You can fill in the amount of disc space a directory takes (is 4 KByte for floppies but can be much larger on harddisc).

The size can be specified in bytes (e.g. 4096) or KBytes (e.g. '40K').  To find out how much space a directory takes on your (hard)disc, do the following :

- Press F12 when you are in desktop
- Select the filing system of your (hard)disc :
  e.g. : 'Ram', 'SCSI', 'ADFS', etc.
- Select the (hard)disc :
  e.g. : 'Dir :4', 'Dir :0', 'Dir HardDisc4', etc.
- Find out how much disc space there is now available :
  'Free'
  The output is something like :
    Bytes free &00A6EC00 =  10939392
    Bytes used &0BD11000 = 198250496
- Create a non existing directory :
  e.g. : 'CDir test'
- Find out how much disc space there is now available :
  'Free'
  The output is something like :
    Bytes free &00A6B000 =  10924032
    Bytes used &0BD14C00 = 198265856
- You can now remove the just create directory :
  e.g. : 'Delete test'    
- Find out the disc space taken by a directory.  This is the difference between the two 'Bytes free' numbers we just found.  In our example this is : 10939392-10924032 = 15360 bytes = 15K (= 15 KByte).

This is the first reason why !FileTree's count is more accurate than the RISC OS count but an other one is that !FileTree can take the file size rounded to the sector size instead of the real file length.  This is because files are placed on sector boundaries (as far as I know is that 1 Kbyte under FileCore but other sizes can be used in !FileTree).

Section 'Varia' :

'Compressed tree' : will try to fit as much as possible on one page but the alphabetic order of the file entries will always being preserved.

'Look inside applications' : will not stop scanning at an application and will also show the contents of that application.

Section 'Create Tree' :

The actual Draw files are generated by dragging the directory icon found at the bottom of !FileTree's main window to a filer window.  A directory will be created with the supplied leafname in that filer window and all the Draw files will appear in that directory.  Or you can also press the 'OK' when the supplied pathname for the directory is correct.

You can quit the application by clicking on the close icon of !FileTree's main window or choose the 'Quit' option in the menu when the pointer is not on a 'Right Arrow' icon.

Versions :
========

This program is made in 100 % hand-written ARM code and supports the RISC OS !Help application.

v1.00 : First public domain version
v1.01 : Small bug fixes :
          - Works now correctly in 256 colours modes
          - Small memory problem fixed
          - For the opton/optoff icons, light comes now from the right direction
v1.02 : - some minor bug fixes and esthetical clean-ups
        - uses now the new BASS 3D Wimp library
        - while looking for !Sprite files, !FileTree first looks for the !Sprite22 file before looking for a !Sprite file.
        - multitasking scanning of the disc (!)
        - uses a more recent version of Joris Rling's FontMenu module.

Version v1.02 has been written and tested under RISC OS 3 and *probably* runs ok under RISC OS 2 too.  However this hasn't been tested.  If this isn't the case, I'm sorry for this and I strongly suggest you to upgrade to RISC OS 3.  RISC OS 3 is not only a so much nicer environment but remember also, by upgrading you support RISCOS Ltd and the RISC OS community too.

v1.03 : - SA compatible
v1.04 : - RISC OS 4 compatible
v1.05 (12 June 2002) :
   - Draw files now contain the 'options object' so that the page size in Draw is that page size selected in FileTree (otherwise Draw tries to be smart and calculate the page size based on the contents).
   - More RISC OS 4 compatible.  I doubt the GUI will look ok on RISC OS 3.  Upgrade to RISC OS 4 or even RISC OS Select !

Manual version v1.3

Conditions of use :
=================

This software is supplied "as is"; no warranty, express or implied, of the merchantability of this software or its fitness for any particular purpose is given.  In no circumstances shall the providers of this software be liable for any damage, loss of profits, or any indirect or consequential loss arising out of the use of this software or inability to use this software.

You are free to give this application to anyone you please via any medium, provided it is delivered with ALL the supplied files, UNALTERED.  You may NOT sell this software, or use it otherwise for personal gain.  If you wish to upload it to a Bulletin Board, FTP or HTTP site or include it in your Public Domain library then that, too, is OK, but if possible, please let me know if you do either of these and please send me a catalogue or whatever is appropriate.  A modest charge for media and postage is acceptable, but should not be excessive.  I reserve the right to change these terms and conditions at any time.

Norwich Computer Services (Archive magazine) has my explicit permission to include !FileTree on one of their Shareware/Careware discs.

Acorn User has my explicit permission to include !FileTree on a disc to be freely given away to new subscribers.

Please report any bugs you find to me, so that other users may benefit from improved versions.  I cannot guarantee to fix any bugs, but I will do my best.


My address is :

John Tytgat      Brusselbaan 445        B-1600 St.-Pieters-Leeuw   BELGIUM

E-mail address : John.Tytgat@aaug.net

 BASS 1991-2002