home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / desktop / t / trash / !Trash / !Help < prev    next >
Encoding:
Text File  |  1990-10-24  |  17.0 KB  |  387 lines
  1. >$.!Trash.!ReadMe
  2.  
  3.                   Documentation for Trash Can Module V1.40
  4.                   ----------------------------------------
  5.  
  6. *********************************** Notice ******************************
  7. *                                                                       *
  8. *  The documentation, source, binary and resources for the Trash Can,   *
  9. *  whilst the copyright of Richard K. Lloyd, may be freely distributed  *
  10. *          provided that this Notice is not altered in any way.         *
  11. *                                                                       *
  12. *************************************************************************
  13.  
  14. New features present in V1.40
  15. -----------------------------
  16.  
  17. * Context-sensitive support for the !Help application has been (grudgingly)
  18.   provided. I don't like !Help at all - it doesn't co-operate in a sensible
  19.   way when you want to resize its window, you can't get help on menu options
  20.   and, worst of all, it doesn't let you pass it more than 256 bytes or 4 lines
  21.   of help text ! By the way, there's help for the Info Window too... :-)
  22.   I'll tell you this: I've fiddled around with the help text so many times now
  23.   I'm going blue in the face...I've had to cut it down to terse descriptions
  24.   in four lines or less.
  25.  
  26. * The menu is now "persistent" i.e. it stays open if the right button is
  27.   clicked on a menu item.
  28.  
  29. * The Trash Can module is now "Spark-aware" regardless of the order of
  30.   installation. This wasn't easy and shows up a big hole in the Wimp SWI
  31.   calls: there's no call to get a list of active Wimp task handles/names !
  32.   I ended up sending a dummy broadcast, translating the handles returned
  33.   into task names and comparing them with the "Spark" name...horrible :-(
  34.  
  35. * Two new sprites, !trash3 and !trash4, have been defined with an extra
  36.   Spark-like "flash" - these are used to indicate that Spark is installed
  37.   simultaneously with the Trash Can module.
  38.  
  39. * The 'feature' of the border turning red when the Trash Can is simply clicked
  40.   on (with Warning and Immediate options enabled) rather than a file being
  41.   dragged onto it has now been fixed i.e. removed.
  42.  
  43. How to install the Trash Can
  44. ----------------------------
  45.  
  46. The Trash Can module is supplied with the following files:
  47.  
  48. !Trash            : The application dir.
  49. !Trash.!ReadMe    : This file.
  50. !Trash.!Run       : An Obey file to set up the Trash Can (may need editing).
  51. !Trash.!RunImage  : The Trash Can Module. Do NOT run this on its own.
  52. !Trash.!Sprites   : Five trash can sprites...
  53.                              !trash : Used in the Filer window
  54.                     !trash1/!trash2 : Used on the icon bar
  55.                     !trash3/!trash4 : As 1/2, but with an extra "flash"
  56.                     Do NOT rename any of these sprites !
  57. !Trash.Templates  : The definition, created by !FormEd, for the Info window.
  58. !Trash.TrashSrc   : The heavily annotated source code.
  59. !Trash.VanSprites : Six trash van sprites...
  60.                     vanlft1..vanlft3 : 3-stage animation of left-pointing van
  61.                     vanrgt1..vanrgt3 : Ditto, but for right-pointing van
  62.  
  63. The Trash Can Module has been designed to run from the Desktop by double-
  64. clicking on the !Trash directory and, because it is a service utility, it
  65. installs an icon on the left-hand side of the icon bar. Attempts to run it
  66. outside the Desktop (by typing *!Trash) will install the Trash Can module
  67. with a message informing you to enter the Desktop afterwards with a *Desktop
  68. command to properly start up the utility.
  69.  
  70. Setting up the Trash$Dir directory
  71. ----------------------------------
  72.  
  73. The environmental variable Trash$Dir is read (and deliberately re-read
  74. frequently during the module's life) - this should be set in the !Run file
  75. to point to a directory where the trash is to be placed. If the directory
  76. does not exist, then it will created when the first trashing or viewing of
  77. the trash contents takes place.
  78.  
  79. The recommended settings are:
  80.  
  81. For hard disk owners:  Set Trash$Dir <Obey$Dir>.Trash
  82. For floppy    owners:  Set Trash$Dir <Obey$Dir>.Trash
  83.                   OR   Set Trash$Dir adfs:$.Trash
  84.                   OR   Set Trash$Dir adfs:$.!Trash.Trash
  85.  
  86. Whatever you decide, Trash$Dir (after environmental variable expansion) MUST
  87. contain the filing system name (usually adfs:) and at least ONE full-stop
  88. (directory separator to give it its full title). Please note that there is
  89. now a second environmental variable called TrashWork$Dir declared in the !Run
  90. file. This is used by the Trash Can Module to locate the sprites and template
  91. files it needs.
  92.  
  93. Problems with floppy disc-based Trash Can
  94. -----------------------------------------
  95.  
  96. If you specify <Obey$Dir> in the Trash$Dir variable, then the disk with the
  97. !Trash directory on it MUST be in a drive at all times. If it isn't, then
  98. the Filer will prompt you for it VERY frequently...
  99.    If you decide to rename the floppy disk (*NameDisc or whatever) that
  100. contains the Trash$Dir directory, then you should restart the Trash Can by
  101. double-clicking on !Trash again to get the new disk name read in.
  102.    One tip for people who are panicking - define Trash$Dir as the string
  103. 'adfs:$.!Trash.Trash' (the third alternative mentioned above) and copy the
  104. !Trash directory (without the TrashSrc file !) onto all your workdisks.
  105.  
  106. If you are still annoyed at having to fumble for disks, you can now enable
  107. a new 'Immediate' option which will bypass the Trash$Dir directory and
  108. immediately delete files that are dragged onto the Trash Can icon. This
  109. is not recommended for hard disk owners unless you are short of hard disk
  110. space.
  111.  
  112. Using the RAM Disk
  113. ------------------
  114.  
  115. Yes, it is possible to use the RAM Disk to store trashed files, but this has
  116. some snags:
  117.  
  118. 1. Files will always be COPIED/DELETED (assuming you are trashing an ADFS
  119.    file) rather than renamed - making the trashing a lot slower process.
  120.  
  121. 2. It's likely that the size of your RAM disc will not be large enough to
  122.    trash many files (especially compared to a hard disk).
  123.  
  124. 3. The biggest problem: A hard reset or a power off will lose the contents
  125.    of the RAM disk - and hence all the files you trashed will be irrecoverable.
  126.  
  127. There are only two advantages as far as I can see:
  128.  
  129. 1. Floppy owners won't have to keep the disk containing Trash$Dir in one
  130.    of the drives all the time.
  131.  
  132. 2. Emptying the trash is incredibly fast.
  133.  
  134. If, after all this, you still want to use the RAM Disk, change the Trash$Dir
  135. line in the !Run file to:
  136.  
  137. Set Trash$Dir RAM:$.Trash
  138.  
  139. Make sure you have a fairly big RAMFsSize setting too (128K recommended).
  140.  
  141. The Trash Can Icon Bar Icon (now known as the 'Trash Can Icon')
  142. ---------------------------
  143.  
  144. There are TWO possible trash can icons depending on the state of the contents
  145. of the Trash Can :
  146.  
  147. If Trash$Dir is empty or doesn't exist, then the thin icon (!trash1/3) is used.
  148. If Trash$Dir is not empty, then the fat icon (!trash2/4) is used.
  149.  
  150. The icon is updated during any *SAVE,*RENAME,*DELETE,*WIPE,*COPY,*CREATE or
  151. file opening for output, which should mean that it reflects the current
  152. contents of Trash$Dir accurately.
  153.  
  154. Context-sensitive help will be shown if the pointer is moved over the Trash Can
  155. Icon whilst the !Help window is open. Put more simply, the help text changes
  156. depending on the current settings of the Immediate, Warning and Animation
  157. modes.
  158.  
  159. If Spark is installed at the same time as the Trash Can module, then an extra
  160. Spark-like "flash" is shown on the Trash Can icon.
  161.  
  162. Trashing Files
  163. --------------
  164.  
  165. To trash a file, select it using the left button (right button if more than
  166. one) and drag it over the trash can icon using the left button. If the
  167. 'Warning' and 'Immediate' options are both enabled, then the border will turn
  168. red whilst the drag is over the Trash Can icon as a warning that a button
  169. release will immediately and irretrieveably delete the dragged files.
  170.  
  171. If the 'Immediate' option is disabled, the Trash Can Module will attempt a
  172. *Rename for speed. If this fails (and you're not trying to be clever by
  173. dragging the Trash$Dir directory onto the trash can icon !), then a
  174. *Copy/*Delete mechanism is used instead. Any identically named files in
  175. Trash$Dir will be overwritten.
  176.  
  177. Lucky owners of V2.xx of Spark will be able to drag compressed files from
  178. a Spark Archive window onto the Trash Can icon. The files will be decompressed
  179. (to a temporary Wimp$Scrap file), moved to Trash$Dir and then deleted from the
  180. original Archive. Please note: Due to the use of the Wimp$Scrap system,
  181. an Archived directory will appear as an ARCHIVE FILE in Trash$Dir when it is
  182. dragged onto the Trash Can.
  183. PLEASE NOTE: Beta-test copies of Spark 2.00 do not behave properly with
  184.              this facility (they have a tendency to fatally crash).
  185.              Use the proper commercial release of Spark 2.00.
  186.  
  187. When you want to empty the contents of the Trash Can, select the 'Empty Trash'
  188. memu item (see below). If the emptying of the Trash Can or the trashing of
  189. files fails (e.g. write-protected disk, disk fault), then a standard error
  190. dialogue box will appear (OK = retry, Cancel = abort). If the operations are
  191. OK, but are taking longer than 1 second, then an Hourglass pointer will appear.
  192.  
  193. The Trash Can Window
  194. --------------------
  195.  
  196. When the trash can icon is clicked on using the left or right buttons, a
  197. Filer window is opened to show the current contents of Trash$Dir. All normal
  198. Filer operations can be performed on this window, which makes it far more
  199. flexible than all other Trash Can Windows I've seen to date (he says
  200. modestly !). The Trash Can Window CANNOT be viewed whilst the Immediate option
  201. is enabled.
  202.  
  203. The Trash Can Menu
  204. ------------------
  205.  
  206. When the trash can icon is clicked on using the middle button, a pop-up menu
  207. appears as follows:
  208.  
  209.     Info      =>
  210.  
  211.     This is a version/author message displayed as a standard Info window,
  212.     which can now be dragged around the screen for no apparent reason.
  213.     It was created by !FormEd and saved in the Templates file. There is
  214.     !Help text available for the Info Window (overkill, but since it uses
  215.     a special 'auto-stamp' system for version/date stamping, it's worth
  216.     mentioning).
  217.  
  218.     Immediate
  219.  
  220.     If this option is ticked, then any files dragged onto the Trash Can icon
  221.     will be immediately and irretrieveably deleted. If is not ticked, then
  222.     the files will be *Renamed (or *Copied/*Deleted) into the Trash$Dir
  223.     directory instead. The Immediate option state is saved in Bit 0 of
  224.     CMOS RAM location 38.
  225.  
  226.     Warning
  227.  
  228.     If this (and the 'Immediate' option) option is ticked, then the border
  229.     will turn red whilst the pointer (during a file drag) is situated over the
  230.     Trash Can icon. The border will also turn red if the 'Immediate' option is
  231.     disabled and the 'Empty Trash' option is highlighted. These signal
  232.     'dangerous' operations for the unwary... The Warning option state is saved
  233.     in Bit 1 of CMOS RAM location 38.
  234.  
  235.     Animation
  236.  
  237.     If this option is ticked, then a simple Trash Van animation occurs on
  238.     the icon bar whenever 'Empty Trash' is selected or when files are dragged
  239.     onto the Trash Can icon with the 'Immediate' option enabled. The Animation
  240.     option state is saved in Bit 2 of CMOS RAM location 38. Many thanks to
  241.     Gary Bartlett for the inspiration and the sprite definitions !
  242.     NOTE: The animation only works in 16-colour MODEs.
  243.  
  244.     Empty Trash
  245.  
  246.     This will appear 'shaded' (normally grey) if either Trash$Dir is empty or
  247.     if the Immediate option is enabled, but solid if it contains any files and
  248.     the Immediate option is disabled. THIS IS THE ONLY WAY TO CLEAR Trash$Dir
  249.     using the Trash Can Module - direct drags from the Trash Can Window
  250.     onto the trash can icon DO NOT delete the files (in fact, they get
  251.     renamed onto themselves !).
  252.  
  253.     Quit      =>
  254.     
  255.     This points to a sub-menu which has two options:
  256.  
  257.     Quit      => Temporary
  258.  
  259.     This removes the Trash Can utility from the Desktop, but the module still
  260.     remains in memory. You can, of course, use the Task Manager to Quit the
  261.     Trash Can Module in an identical way. To reactivate, use the Task Manager's
  262.     'New Task' to type *Desktop_TrashCan (you can use the f12 mechanism also)
  263.     or simply exit and re-enter the Desktop (Shift-Ctrl-f12 then *Desktop).
  264.  
  265.     Quit      => Permanent    (this is the default if Quit is selected
  266.                                on the MAIN menu)
  267.  
  268.     This not only removes the Trash Can Desktop utility but also kills the
  269.     Trash Can module and unsets the two environmental variables used by it
  270.     (Trash$Dir and TrashWork$Dir). This is the recommended way to completely
  271.     remove the Trash Can program from the system.
  272.  
  273. The Trash Can Menu is now "persistent" - it remains open if the right button
  274. is clicked on a menu item.
  275.  
  276. Recovering trashed files
  277. ------------------------
  278.  
  279. To recover files that have been trashed with the 'Immediate' option disabled
  280. (assuming that you haven't emptied the trash yet), open the Trash Can Window
  281. (left or right button) and SHIFT-drag the files from that window onto another
  282. open Filer Window. Remember that holding down SHIFT during a file drag deletes
  283. the files in the source window, which is what you want.
  284.  
  285. What can the Trash Can Module survive ?
  286. ---------------------------------------
  287.  
  288. Unlike BASIC versions of the Trash Can, this module can survive:
  289.  
  290. 1.  Complete wipe of application workspace (e.g. *InitStore 0).
  291. 2.  Exit from and re-entry to the Desktop.
  292. 3.  A soft reset.
  293. 4.  *RMReInit TrashCan.             } Normally issued
  294. 5.  *RMTidy.                        } outside the Desktop
  295. 6.  Various run-time errors (e.g. missing sprites/templates, not enough RMA).
  296. 7.  *Unset Trash$Dir.
  297. 8.  Setting (the expanded) Trash$Dir longer than 63 characters.
  298. 9.  The Trash Can Temporary Quit option.
  299. 10. Shutdown of it via the Task Manager window.
  300.  
  301. Please note that 2, 4, 5, 9 and 10 above will cause a reload of the Trash Can
  302. sprite and template files upon re-entry to the Desktop. If you are inside the
  303. Desktop, the Trash Can can be restarted by issuing the *Desktop_TrashCan
  304. command after any problems have been fixed.
  305.  
  306. It cannot survive:
  307.  
  308. 1. A hard reset.
  309. 2. *RMKill TrashCan.
  310. 3. *RMClear.
  311. 4. The Trash Can Permanent Quit Option.
  312. 5. Power off and on (obvious !).
  313.  
  314. Known Problems (some of which may be fixed in the next release)
  315. --------------
  316.  
  317. * Someone from Acorn claims that the border is flashed red when the
  318.   pointer is moved over the "Empty Trash" menu item when it is actually
  319.   greyed-out. I suspect that he was running a version of RISC OS higher than
  320.   2.00, because I've been unable to reproduce this fault under any conditions.
  321.  
  322. * The Trash Van flickers due to the use of Wimp_SpriteOp (much slower than
  323.   OS_SpriteOp). This can be solved by buying an ARM3 upgrade :-)
  324.  
  325. * The "!spark -d <file inside archive>" command in the command window of
  326.   Spark 2.00 (15 Jun 90 version) quite often causes Spark to fatally crash.
  327.   Unfortunately, this is the command the Trash Can module sends to Spark
  328.   to delete an archive file...it's up to David Pilling to fix this I'm afraid.
  329.  
  330. Conclusion
  331. ----------
  332.  
  333. Well, that's it. My first multi-tasking RISC OS module. The Trash Can icons
  334. were based (as was the idea of storing the files in a Trash directory) on
  335. the Macintosh icons (ResEdit was rather handy...). At least my module doesn't
  336. empty the trash when you start a new application or eject the disk (a
  337. disgraceful oversight on the part of Apple) ! Have you seen a better Trash Can
  338. program ? If so, let me know because my disks are full of them (although you
  339. can now 'trash' all other Trash Cans apart from mine !!)...
  340.  
  341. I just realised something: the source code for this project is 86K long !
  342. What started out as a quick and dirty hack has now become a labour of love
  343. and I feel the quality of code now surpasses anything I have previously
  344. released into the Public Domain. However, I'm hoping that the next version,
  345. V1.50, will be last main release for some considerable time - updates after
  346. V1.50 will simply be bug-fix releases (unless someone suggests a missing
  347. feature that's not too difficult to include...).
  348.  
  349. Revision History
  350. ----------------
  351.  
  352. Supplied in the form of comments at the start of the source code. New features
  353. in this latest release are described at the top of this document.
  354.  
  355. Future Enhancements (see "Known Problems" too)
  356. -------------------
  357.  
  358. * Grab some RMA for buffer storage. In particular, the environmental variable
  359.   translation buffer, the Filer_Open/CloseDir OS_CLI strings, the Wimp palette
  360.   and the Help text (store the latter in an !Help text file and read at
  361.   startup).
  362.  
  363. * Optional digitised sound playback when the trash is emptied. Now if only
  364.   RISC OS had support for playing a digitised sound sample (rather than having
  365.   to rely upon the third-party, but admittedly clever, SoundTracker module)...
  366.  
  367. Estimated Date of Release of V1.50
  368. ----------------------------------
  369.  
  370. Approximately December 1990, but no guarantees...
  371. Likely to be last time I do any extensive work on this program.
  372.  
  373. A Plea From The Author
  374. ----------------------
  375.  
  376. If you make some USEFUL changes to the source or fix any bugs, can you please
  377. send me those changes to the following address:
  378.  
  379. Snail Mail                   JANET e-mail
  380. ----------                   ------------
  381.  
  382. Richard K. Lloyd,            rkl@uk.ac.liv.cs.and
  383. 1, Banks Road,
  384. Lower Heswall,
  385. Wirral,
  386. Merseyside. L60 9JS
  387.