////////////////////
// RECYCLER 4.0.3 //
////////////////////
Copyright  1999 Joachim Calvert. All rights reserved.


Contents
	Introduction and history
	Changes in this version
	Features
	Installation and requirements
	Options
	Future plans
	Troubleshooting
	Disclaimer/legal information
	Credits
	Contacting the author


Introduction and history
========================
First of all, thank you for your interest in this module. Together, we can make
it the best of it's kind.

I began working on this module in June, after searching in vain for a good
module that would allow me to use the recycle bin under LiteStep. Sure,
Incinerator is quite good, but it lacked certain features I wanted.

So, in the spirit of the project, I set out to create exactly the module I
wanted, and share it with the community. In the beginning it was rather
simplistic. For example, it couldn't yet empty the 'bin, and it was also
confined to the wharf (which wasn't a problem at the time).

In the months that followed, I made several changes to it, to satisfy the needs
of those who used it. What you have now is the latest incarnation of the module,
with full support for most of the features you'd expect from a module of this
kind.


Changes in this version
=======================
These are only the changes made in this version. For older changes, please refer
to the file 'changes.txt'.

4.0.3	 991101	* Finally someone took the time to provide me with an animation,
		  let's all give J. A. Portugal da Costa a big hand!


Features
========
This is just a list of the supported features. For more details, consult the
Options section below.

Drag 'n' drop		The module provides full support for drag 'n' drop
			operations. There are a few issues involved though (see
			the TS section).

Content aware		It detects if there are files in the 'bin or not, and
			automatically updates itself to reflect this.

Transparency		There is full support for transparent images to allow
			the module to seamlessly integrate into your theme.

Mixed Mode		Can be loaded either as a wharf/dwarf tile, or stand-
			alone as a Load Module.

Fully customizable	When loaded stand alone, you can customize most aspects
			of it, such as setting it's visible state and resizing
			it to any size that suits your needs.

Animated		When you delete files or empty the 'bin through the
			module, it will play a specified animation.

Bang Commands		There are several bang commands that gives you quick
			access to most of it's features.


Installation and requirements
=============================
Before you install, you must ensure that you have a development build dated
after 1999-09-06 (Y-M-D). If you have an official release built after this date,
it should work as well. It is possible that the module works with earlier
builds, but I cannot guarantee it. The module will NOT work with the official
0.24.5 releases or earlier, due to a bug in one of the LSAPI functions.

Also note that it is generally a Good Idea to update your core modules to the
latest builds at least once every month, as there are usually important bug
fixes and other improvements. The dev builds are generally even more stable than
the official releases.

To install the module, unzip the DLL to a directory of your choice. The images
that you are going to use, whether those included or custom, should preferably
reside in your images folder.

Setup your step.rc to load the module, changing the paths accordingly.

	LoadModule	C:\LiteStep\Plugins\Recycler.dll

or, if you prefer the wharf configuration

	*Wharf	"Recycler"	.none	@C:\LiteStep\Plugins\Recycler.dll

To uninstall the module, simply remove the files and the settings from your LS
configuration files. There is no information stored in your registry or
otherwise.


Options
=======
From version 4, I have dropped the support for 'modules.ini'. This was done to
better support theming of the module. Another reason is that the community has
largely abandoned the ini file, as it doesn't support the more advanced features
of LiteStep. Sorry if this gives you a headache.

These options are set in your 'step.rc' or 'theme.rc'. Sorry for the confusion
in the last few revisions. I thought I had updated this info...

RecyclerDebugMode	This setting will activate debug output from the legacy
			routine used to empty the 'bin. Not to be used under
			normal conditions.

RecyclerLegacyMode	Allows the module to work properly even if the
			notification system is inaccessible.

RecyclerHideMenuHide	This will remove the 'Hide' entry from the modules popup
			menu. It was requested, so here it is.

RecyclerNotAlwaysOnTop	This will make the module stick to the background,
			instead of floating above your other windows.

RecyclerStartHidden	Will load the module in it's hidden state, useful if you
			don't want it to be visible at all times. Also useful if
			you only want access to the Bang Commands.

RecyclerBack .none	These specify which images to be used by the module.
RecyclerEmpty Recycler	Currently, only 'RecyclerBack' accept the '.none'
RecyclerFull Recycler 	setting, using it with any of the others will put the
			module in it's failure state (not harmful).

RecyclerAnimation .none	This is the image used for the animation. If it is
			omitted, the module will not be animated. If set, the
			module animates using the values set by
			'RecyclerAniDelay' and 'RecyclerAniFrames'. Naturally
			the animation uses the Great Pink for transparency.
			If you want to use the supplied animation, you don't
			have to set any of the other values.

RecyclerAniDelay 120	Sets the delay in milliseconds between the frames of the
			animation.

RecyclerAniFrames 4	Sets the number of frames in the animation. The image
			height is divided by this value into frames. If the
			frames aren't of equal height, the animation will not
			display correctly.
			
RecyclerAniLength 1200	Sets the length of the animation in milliseconds. Note
			that the actual length depends on the 'AniDelay'
			setting. The total number of frames that will be
			displayed is RecyclerAniLength / RecyclerAniDelay,
			rounded down.

RecyclerLeft -64	These are used to set the location of the module.
RecyclerTop -64		Negative coordinates are relative to the bottom right
RecyclerWidth 64	corner of the screen. If 'RecyclerLeft' and/or
RecyclerHeight 64	'RecyclerTop' is omitted, the module will set them
			internally to keep it in the bottom right corner.

RecyclerCapOpen &Open	Requested by somagix, these options let you localize
RecyclerCapEmpty &Empt	the module to any language.
RecyclerCapHide &Hide

Most of these options are ignored if the module is loaded in a wharf tile, which
ones should be pretty evident.

The following Bang Commands become available when the module is loaded, please
note that calling !RecyclerVisible when the module is loaded in a wharf tile
won't have any effect.

!RecyclerEmpty		As you'd expect, this empties the 'bin.

!RecyclerOpen		Opens the 'bin in an exploder window.

!RecyclerVisible	Calling this without parameters will hide the module if
			it's visible and vice versa. To explicitly set the
			visibility, you can specify 'true' or 'false' as params
			(not including the quotes).


Future plans
============
OK, the animation system is in place, though it could probably be tweaked
somewhat. I have included a short test animation that you can use to test the
system. As you can see, I'm no graphics wizard, so I'd be extremely happy if
anyone wants to create a real animation for it. You will of course be duly
credited for it.

If you have any other suggestions, I'd be happy to code them if I consider them
beneficial to the project (no, I won't add support for making coffee).

If you are wondering why the module is so large, it is because Delphi includes
the runtime support in the DLL itself. I could bring the size down to about 20
kilobytes, but then you'd need the runtime library, and that is more than 1.6
megabytes!


Troubleshooting
===============
As I have no access to any system other than my own (W98/IE5), I haven't been
able to test the module as much as I'd want to. So don't be surprised if the
module doesn't behave as you expected. There are some issues that are quite
common though.

If the module displays a big red X instead of the image you have selected, this
is because it can't find one or more of them. Please verify that all the
specified images exist, and that you haven't quoted the name.

I've noted that on some systems, the module won't update to reflect whether
there are files in it or not. Though I don't know the cause, you can update the
module simply by clicking on it.

If you encounter problems with the module, feel free to contact me, but please
include information about your system when you do so.

The information I need is: Version of Windows, if 'Active Desktop' is installed,
and also the build date of your 'lsapi.dll' (can be found with the
'!About Detailed' command). It would also help if you sent me the relevant lines
from your 'step.rc' and 'modules.ini'.


Disclaimer / legal information
==============================
If you've read one, you've read them all, but I have to say this so you can't
sue me if anything goes wrong...

  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

By installing the module, you agree to the above terms.

The source is available at my site.


Credits
=======
Without the aid of the following people and companies, this module wouldn't be
what it is today. I'm eternally grateful for their, sometimes unknowing,
assistance.

Francis Gastellu	Without him, LiteStep would never have been born.

Fahim Farook		Under his guidance, LS has evolved to heights it would
			never have reached otherwise.

The Dev Team		You have to admire these fellows, who just keep going,
			and going, and going...

Earl F. Glynn		For pointing at some code telling me how to empty the
			recycle bin. It was just an API call unmentioned in my
			docs.
			
Christian Leinen	For opening my eyes on how to empty the recycle bin when
			the API call is unavailable.

somagix		For translating these docs to French for the benefit of
			the LS users in all French-speaking countries.

J. A. Portugal da Costa	For the awsome animation, it was exactly what I wanted,
			you can't begin to comprehend how happy I am for it!

Borland			The company now called Inprise will in our hearts always
			be remembered as Borland, the creators of the finest
			development tools on the market. Latest news: Delphi and
			C++Builder are being ported to Linux!


Contact
=======
Don't you just hate it when someone releases a program and doesn't tell where to
find the upgrades, or even his mail address?

For upgrades and other software please visit my site on

	hem.passagen.se/jcalvert/software

If you have comments, suggestions, bug reports or just want to say hi, my
address is

	jcalvert@hem.passagen.se

Before sending me bug reports, or questions about the operation of the module,
please ensure that you have read through the sections 'Installation and
requirements', 'Options' and 'Troubleshooting'. You wouldn't believe me if I
told you how many messages I receive with questions answered in those sections.

= EOF =