BDotD2
~~~~~~

(c) Musus Umbra 1996

Permission is granted for unlimited personal use & modification.

Permission is granted for redistribution (by any method) provided that:
	No charge is made for this software.  A reasonable charge may be
		made for media / handling / etc. This software is *free*.
	Any distributed copy of this software must be unaltered and entire.
		You may not distribute modified / imcomplete copies of this
		software.  If you fix a bug / add a feature, let me know so
		that I can update the master copy.

As usual with freeware, there is no warranty of any kind.  The author cannot
be help responsible for any loss/damage arising from the use/inability to
use this software.  It is the user's responsibility to determine the fitness
of this software for any purpose they put it to.

(But if it doesn't work, I will try to help :-)




What it does, and why it does it
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Well, BDotD2 stands for 'BackDrop Of The Day (version 2)'.  It seems faily
logical therefore to assume that BDotD2 simply chooses a backdrop of the
day.  And, indeed, this it does.  And more...

BDotD2 was originally written so that I could have a different backdrop on
the pinboard every time I (re)started my machine.  What I wanted, in essence,
was a utility that would work out which backdrops I had available, choose one,
and then decide whether it should be scaled, centred or tiled.  In addition,
I wanted it to make sure that all the backdrops had been chosen before it
repeated any.

Now then, scanning directories with many backdrops in can take a while.  Don't
panic!  This is a little while as in a couple of seconds!  So, I wanted BDotD2
to be usable *before* the desktop starts.  That way I could run it as part
of my PreDesk sequence (whilst my natty startup screen & Thought of The Day
were still displayed).  This probably won't affect anyone other than those
geeky enough to know what I'm talking about...

BDotD2 is smart enough to cope with files appearing and disappearing willy-
nilly.  There are no configuration files to change when you add or remove
a backdrop.


How to use it (geeky version)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The only part of !BDotD2 that you really need is the BDotD2 executable.
Thus, you could copy it into your library directory and use it as a
command line utility from there.

BDotD2 takes a number of command line arguments and produces its output
in the form of two system variables:

	BDotD$Backdrop		holds the filename of the chosen backdrop
	BDotD$Flag		is one of '-tile', '-center', or '-scale'

Thus, after running BDotD2, you can issue the command:

	*Backdrop <BDotD$Flag> <BDotD$Backdrop>

(in your DeskBoot file, for example) to actually put the chosen backdrop on
the pinboard.



How to use it (WIMPy version :-)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Edit the !Run file in this directory (follow the instructions in it) so that
BDotD2 can find your backdrops.

Now, make sure that !BDotD2 is run during your desktop boot.

If you are using a RiscPC (like me), this can be arranged by copying this
entire directory into your !Boot.Choices.Boot.Tasks directory.

If you're using an older machine (also like me :-), add a line to your
Desktop boot file that runs !BDotD2.

Or, if you didn't want to put BDotD2 in your boot sequence, you could simply
edit the !Run file and double-click on !BDotD2 to change backdrop at will!



Arguments
~~~~~~~~~

BDotD2 recognises the following arguments (all may be abbreviated):


-dir <directory>
	BDotD2 will search the directory specified looking for Sprite
	files.  Subdirectories will *not* be searched.

[-path] <directory>
	If a directory name is preceeded by -path, or has no preceeding
	-dir, it is searched recursively, ie. Subdirectories *are*
	searched.

-nostate
-statefile <filename>
	These options allow you to control whether BDotD2 should keep
	track of chosen backdrops, etc.  If you specify -nostate, no
	state information is kept.  If you specify -statefile with a
	filename, state information will be read/written from the named
	file.
	The default is to use a file 'bdotdState' in the first directory
	named on the command line.

-mode <mode>
	Because BDotD2 decides whether to scale/tile/center the backdrop
	it chooses, it needs to know what screen mode you will be using
	in the desktop.
	If no -mode is specified, BDotD will use the current screen mode.
	NB: 'standard' modes may be specified as (for example) -mode 31
	however, 'new' screen modes (that is, modes without numbers) must
	be specified as 'mode selector strings', eg. X1024Y768C256EX1EY1
	Note that only the X and Y parts are actually used but you can
	supply the rest if you want :-)

-raw_paths
-canonicalise_paths
	BDotD2 is smart about working out with backdrops it has already
	chosen.  A lesser program might consider two files called:
		ADFS::Frinkle.Backdrops.Fred
	and	ADFS::Frinkle.$.Backdrops.Fred
	to be different files, which they clearly are not!  BDotD2 gets
	around this problem by canonicalising all the filenames it works
	with.  (in this context, canonicalising means "working out what it
	_really_ is").
	This option will only really be of use to anyone who wants to be able
	to run BDotD2 at the command line as well as as part of a boot
	sequence.
	To prevent BDotD2 from canonicalising paths (which takes longer
	that using raw paths), use -raw_paths.

-border_tolerance
	When deciding whether to center an image, BDotD2 works out how big
	a border would be left/clipped around the image.  You can override
	the default 'cut off' value using this option.
	The default is 32 OS units (usually 16 pixels) on a side.

-tile_tolerance
	When deciding whether to tile an image, BDotD2 works out how many
	times the image would be repeated over the screen horizontally and
	vertically.  If fewer the image would repeat fewer than the
	tile_tolerance in *both* directions, BDotD2 rules out tiling.
	You can override the default value of 1.25 by using this option.

-aspect_tolerance
	After ruling out centering and tiling, BDotD2 is only left with
	scaling.  However, BDotD2 does not take defeat lying down and will
	check how bady scaling would 'distort' the image.  To do this it
	calculates the relative error in the image's aspect ratio that would
	occur if the image was scaled to fit the pinboard.
	You can override the default value of 0.15 using this option.



Things to Note:
~~~~~~~~~~~~~~~

	You may specify as many directories as you wish (either as -path or
	-dir arguments).

	You *must* specify at least one directory (either as a -path or
	-dir) to search!  If you don't, BDotD2 will print a helpful
	reminder of the command line syntax :-)

	You can specify a -border_tolerance of 0 to prevent any clipping
	or grey borders happening.

	Similarly, a  -tile_tolerance of 0 will prevent any image from being
	*scaled* (since it will always pass the -tile test).

	If none of the three options (-scale/-tile/-center) is suitable, BDotD2
	will settle for -center and have done with it.

	The first time BDotD2 encounters a backdrop file it will work out
	the dimensions of the image in that file.  By cacheing this size
	information in the statefile, BDotD2 can save time the next time
	it encounters that file.



Contact:
	e-mail:		musus@argonet.co.uk
	WWW:		http://www.argonet.co.uk/users/musus/
	Snail:		c/o 23 Baronsway, Whitkirk, Leeds, LS15 7AW, ENGLAND.
