>$.!Trash.!ReadMe

                  Documentation for Trash Can Module V1.40
                  ----------------------------------------

*********************************** Notice ******************************
*                                                                       *
*  The documentation, source, binary and resources for the Trash Can,   *
*  whilst the copyright of Richard K. Lloyd, may be freely distributed  *
*          provided that this Notice is not altered in any way.         *
*                                                                       *
*************************************************************************

New features present in V1.40
-----------------------------

* Context-sensitive support for the !Help application has been (grudgingly)
  provided. I don't like !Help at all - it doesn't co-operate in a sensible
  way when you want to resize its window, you can't get help on menu options
  and, worst of all, it doesn't let you pass it more than 256 bytes or 4 lines
  of help text ! By the way, there's help for the Info Window too... :-)
  I'll tell you this: I've fiddled around with the help text so many times now
  I'm going blue in the face...I've had to cut it down to terse descriptions
  in four lines or less.

* The menu is now "persistent" i.e. it stays open if the right button is
  clicked on a menu item.

* The Trash Can module is now "Spark-aware" regardless of the order of
  installation. This wasn't easy and shows up a big hole in the Wimp SWI
  calls: there's no call to get a list of active Wimp task handles/names !
  I ended up sending a dummy broadcast, translating the handles returned
  into task names and comparing them with the "Spark" name...horrible :-(

* Two new sprites, !trash3 and !trash4, have been defined with an extra
  Spark-like "flash" - these are used to indicate that Spark is installed
  simultaneously with the Trash Can module.

* The 'feature' of the border turning red when the Trash Can is simply clicked
  on (with Warning and Immediate options enabled) rather than a file being
  dragged onto it has now been fixed i.e. removed.

How to install the Trash Can
----------------------------

The Trash Can module is supplied with the following files:

!Trash            : The application dir.
!Trash.!ReadMe    : This file.
!Trash.!Run       : An Obey file to set up the Trash Can (may need editing).
!Trash.!RunImage  : The Trash Can Module. Do NOT run this on its own.
!Trash.!Sprites   : Five trash can sprites...
                             !trash : Used in the Filer window
                    !trash1/!trash2 : Used on the icon bar
                    !trash3/!trash4 : As 1/2, but with an extra "flash"
                    Do NOT rename any of these sprites !
!Trash.Templates  : The definition, created by !FormEd, for the Info window.
!Trash.TrashSrc   : The heavily annotated source code.
!Trash.VanSprites : Six trash van sprites...
                    vanlft1..vanlft3 : 3-stage animation of left-pointing van
                    vanrgt1..vanrgt3 : Ditto, but for right-pointing van

The Trash Can Module has been designed to run from the Desktop by double-
clicking on the !Trash directory and, because it is a service utility, it
installs an icon on the left-hand side of the icon bar. Attempts to run it
outside the Desktop (by typing *!Trash) will install the Trash Can module
with a message informing you to enter the Desktop afterwards with a *Desktop
command to properly start up the utility.

Setting up the Trash$Dir directory
----------------------------------

The environmental variable Trash$Dir is read (and deliberately re-read
frequently during the module's life) - this should be set in the !Run file
to point to a directory where the trash is to be placed. If the directory
does not exist, then it will created when the first trashing or viewing of
the trash contents takes place.

The recommended settings are:

For hard disk owners:  Set Trash$Dir <Obey$Dir>.Trash
For floppy    owners:  Set Trash$Dir <Obey$Dir>.Trash
                  OR   Set Trash$Dir adfs:$.Trash
                  OR   Set Trash$Dir adfs:$.!Trash.Trash

Whatever you decide, Trash$Dir (after environmental variable expansion) MUST
contain the filing system name (usually adfs:) and at least ONE full-stop
(directory separator to give it its full title). Please note that there is
now a second environmental variable called TrashWork$Dir declared in the !Run
file. This is used by the Trash Can Module to locate the sprites and template
files it needs.

Problems with floppy disc-based Trash Can
-----------------------------------------

If you specify <Obey$Dir> in the Trash$Dir variable, then the disk with the
!Trash directory on it MUST be in a drive at all times. If it isn't, then
the Filer will prompt you for it VERY frequently...
   If you decide to rename the floppy disk (*NameDisc or whatever) that
contains the Trash$Dir directory, then you should restart the Trash Can by
double-clicking on !Trash again to get the new disk name read in.
   One tip for people who are panicking - define Trash$Dir as the string
'adfs:$.!Trash.Trash' (the third alternative mentioned above) and copy the
!Trash directory (without the TrashSrc file !) onto all your workdisks.

If you are still annoyed at having to fumble for disks, you can now enable
a new 'Immediate' option which will bypass the Trash$Dir directory and
immediately delete files that are dragged onto the Trash Can icon. This
is not recommended for hard disk owners unless you are short of hard disk
space.

Using the RAM Disk
------------------

Yes, it is possible to use the RAM Disk to store trashed files, but this has
some snags:

1. Files will always be COPIED/DELETED (assuming you are trashing an ADFS
   file) rather than renamed - making the trashing a lot slower process.

2. It's likely that the size of your RAM disc will not be large enough to
   trash many files (especially compared to a hard disk).

3. The biggest problem: A hard reset or a power off will lose the contents
   of the RAM disk - and hence all the files you trashed will be irrecoverable.

There are only two advantages as far as I can see:

1. Floppy owners won't have to keep the disk containing Trash$Dir in one
   of the drives all the time.

2. Emptying the trash is incredibly fast.

If, after all this, you still want to use the RAM Disk, change the Trash$Dir
line in the !Run file to:

Set Trash$Dir RAM:$.Trash

Make sure you have a fairly big RAMFsSize setting too (128K recommended).

The Trash Can Icon Bar Icon (now known as the 'Trash Can Icon')
---------------------------

There are TWO possible trash can icons depending on the state of the contents
of the Trash Can :

If Trash$Dir is empty or doesn't exist, then the thin icon (!trash1/3) is used.
If Trash$Dir is not empty, then the fat icon (!trash2/4) is used.

The icon is updated during any *SAVE,*RENAME,*DELETE,*WIPE,*COPY,*CREATE or
file opening for output, which should mean that it reflects the current
contents of Trash$Dir accurately.

Context-sensitive help will be shown if the pointer is moved over the Trash Can
Icon whilst the !Help window is open. Put more simply, the help text changes
depending on the current settings of the Immediate, Warning and Animation
modes.

If Spark is installed at the same time as the Trash Can module, then an extra
Spark-like "flash" is shown on the Trash Can icon.

Trashing Files
--------------

To trash a file, select it using the left button (right button if more than
one) and drag it over the trash can icon using the left button. If the
'Warning' and 'Immediate' options are both enabled, then the border will turn
red whilst the drag is over the Trash Can icon as a warning that a button
release will immediately and irretrieveably delete the dragged files.

If the 'Immediate' option is disabled, the Trash Can Module will attempt a
*Rename for speed. If this fails (and you're not trying to be clever by
dragging the Trash$Dir directory onto the trash can icon !), then a
*Copy/*Delete mechanism is used instead. Any identically named files in
Trash$Dir will be overwritten.

Lucky owners of V2.xx of Spark will be able to drag compressed files from
a Spark Archive window onto the Trash Can icon. The files will be decompressed
(to a temporary Wimp$Scrap file), moved to Trash$Dir and then deleted from the
original Archive. Please note: Due to the use of the Wimp$Scrap system,
an Archived directory will appear as an ARCHIVE FILE in Trash$Dir when it is
dragged onto the Trash Can.
PLEASE NOTE: Beta-test copies of Spark 2.00 do not behave properly with
             this facility (they have a tendency to fatally crash).
             Use the proper commercial release of Spark 2.00.

When you want to empty the contents of the Trash Can, select the 'Empty Trash'
memu item (see below). If the emptying of the Trash Can or the trashing of
files fails (e.g. write-protected disk, disk fault), then a standard error
dialogue box will appear (OK = retry, Cancel = abort). If the operations are
OK, but are taking longer than 1 second, then an Hourglass pointer will appear.

The Trash Can Window
--------------------

When the trash can icon is clicked on using the left or right buttons, a
Filer window is opened to show the current contents of Trash$Dir. All normal
Filer operations can be performed on this window, which makes it far more
flexible than all other Trash Can Windows I've seen to date (he says
modestly !). The Trash Can Window CANNOT be viewed whilst the Immediate option
is enabled.

The Trash Can Menu
------------------

When the trash can icon is clicked on using the middle button, a pop-up menu
appears as follows:

    Info      =>

    This is a version/author message displayed as a standard Info window,
    which can now be dragged around the screen for no apparent reason.
    It was created by !FormEd and saved in the Templates file. There is
    !Help text available for the Info Window (overkill, but since it uses
    a special 'auto-stamp' system for version/date stamping, it's worth
    mentioning).

    Immediate

    If this option is ticked, then any files dragged onto the Trash Can icon
    will be immediately and irretrieveably deleted. If is not ticked, then
    the files will be *Renamed (or *Copied/*Deleted) into the Trash$Dir
    directory instead. The Immediate option state is saved in Bit 0 of
    CMOS RAM location 38.

    Warning

    If this (and the 'Immediate' option) option is ticked, then the border
    will turn red whilst the pointer (during a file drag) is situated over the
    Trash Can icon. The border will also turn red if the 'Immediate' option is
    disabled and the 'Empty Trash' option is highlighted. These signal
    'dangerous' operations for the unwary... The Warning option state is saved
    in Bit 1 of CMOS RAM location 38.

    Animation

    If this option is ticked, then a simple Trash Van animation occurs on
    the icon bar whenever 'Empty Trash' is selected or when files are dragged
    onto the Trash Can icon with the 'Immediate' option enabled. The Animation
    option state is saved in Bit 2 of CMOS RAM location 38. Many thanks to
    Gary Bartlett for the inspiration and the sprite definitions !
    NOTE: The animation only works in 16-colour MODEs.

    Empty Trash

    This will appear 'shaded' (normally grey) if either Trash$Dir is empty or
    if the Immediate option is enabled, but solid if it contains any files and
    the Immediate option is disabled. THIS IS THE ONLY WAY TO CLEAR Trash$Dir
    using the Trash Can Module - direct drags from the Trash Can Window
    onto the trash can icon DO NOT delete the files (in fact, they get
    renamed onto themselves !).

    Quit      =>
    
    This points to a sub-menu which has two options:

    Quit      => Temporary

    This removes the Trash Can utility from the Desktop, but the module still
    remains in memory. You can, of course, use the Task Manager to Quit the
    Trash Can Module in an identical way. To reactivate, use the Task Manager's
    'New Task' to type *Desktop_TrashCan (you can use the f12 mechanism also)
    or simply exit and re-enter the Desktop (Shift-Ctrl-f12 then *Desktop).

    Quit      => Permanent    (this is the default if Quit is selected
                               on the MAIN menu)

    This not only removes the Trash Can Desktop utility but also kills the
    Trash Can module and unsets the two environmental variables used by it
    (Trash$Dir and TrashWork$Dir). This is the recommended way to completely
    remove the Trash Can program from the system.

The Trash Can Menu is now "persistent" - it remains open if the right button
is clicked on a menu item.

Recovering trashed files
------------------------

To recover files that have been trashed with the 'Immediate' option disabled
(assuming that you haven't emptied the trash yet), open the Trash Can Window
(left or right button) and SHIFT-drag the files from that window onto another
open Filer Window. Remember that holding down SHIFT during a file drag deletes
the files in the source window, which is what you want.

What can the Trash Can Module survive ?
---------------------------------------

Unlike BASIC versions of the Trash Can, this module can survive:

1.  Complete wipe of application workspace (e.g. *InitStore 0).
2.  Exit from and re-entry to the Desktop.
3.  A soft reset.
4.  *RMReInit TrashCan.             } Normally issued
5.  *RMTidy.                        } outside the Desktop
6.  Various run-time errors (e.g. missing sprites/templates, not enough RMA).
7.  *Unset Trash$Dir.
8.  Setting (the expanded) Trash$Dir longer than 63 characters.
9.  The Trash Can Temporary Quit option.
10. Shutdown of it via the Task Manager window.

Please note that 2, 4, 5, 9 and 10 above will cause a reload of the Trash Can
sprite and template files upon re-entry to the Desktop. If you are inside the
Desktop, the Trash Can can be restarted by issuing the *Desktop_TrashCan
command after any problems have been fixed.

It cannot survive:

1. A hard reset.
2. *RMKill TrashCan.
3. *RMClear.
4. The Trash Can Permanent Quit Option.
5. Power off and on (obvious !).

Known Problems (some of which may be fixed in the next release)
--------------

* Someone from Acorn claims that the border is flashed red when the
  pointer is moved over the "Empty Trash" menu item when it is actually
  greyed-out. I suspect that he was running a version of RISC OS higher than
  2.00, because I've been unable to reproduce this fault under any conditions.

* The Trash Van flickers due to the use of Wimp_SpriteOp (much slower than
  OS_SpriteOp). This can be solved by buying an ARM3 upgrade :-)

* The "!spark -d <file inside archive>" command in the command window of
  Spark 2.00 (15 Jun 90 version) quite often causes Spark to fatally crash.
  Unfortunately, this is the command the Trash Can module sends to Spark
  to delete an archive file...it's up to David Pilling to fix this I'm afraid.

Conclusion
----------

Well, that's it. My first multi-tasking RISC OS module. The Trash Can icons
were based (as was the idea of storing the files in a Trash directory) on
the Macintosh icons (ResEdit was rather handy...). At least my module doesn't
empty the trash when you start a new application or eject the disk (a
disgraceful oversight on the part of Apple) ! Have you seen a better Trash Can
program ? If so, let me know because my disks are full of them (although you
can now 'trash' all other Trash Cans apart from mine !!)...

I just realised something: the source code for this project is 86K long !
What started out as a quick and dirty hack has now become a labour of love
and I feel the quality of code now surpasses anything I have previously
released into the Public Domain. However, I'm hoping that the next version,
V1.50, will be last main release for some considerable time - updates after
V1.50 will simply be bug-fix releases (unless someone suggests a missing
feature that's not too difficult to include...).

Revision History
----------------

Supplied in the form of comments at the start of the source code. New features
in this latest release are described at the top of this document.

Future Enhancements (see "Known Problems" too)
-------------------

* Grab some RMA for buffer storage. In particular, the environmental variable
  translation buffer, the Filer_Open/CloseDir OS_CLI strings, the Wimp palette
  and the Help text (store the latter in an !Help text file and read at
  startup).

* Optional digitised sound playback when the trash is emptied. Now if only
  RISC OS had support for playing a digitised sound sample (rather than having
  to rely upon the third-party, but admittedly clever, SoundTracker module)...

Estimated Date of Release of V1.50
----------------------------------

Approximately December 1990, but no guarantees...
Likely to be last time I do any extensive work on this program.

A Plea From The Author
----------------------

If you make some USEFUL changes to the source or fix any bugs, can you please
send me those changes to the following address:

Snail Mail                   JANET e-mail
----------                   ------------

Richard K. Lloyd,            rkl@uk.ac.liv.cs.and
1, Banks Road,
Lower Heswall,
Wirral,
Merseyside. L60 9JS
