                         ****************************
                         *--------------------------*
                         *- MegaBoard Version 1.74 -*
                         *--------------------------*
                         ****************************

Please note this program is SHAREWARE, please refer to the end of this file
for details.

----------------
- Introduction -
----------------
MegaBoard is a desktop Backdrop utility designed as a replacement for the
Pinboard Module supplied with Risc OS 3. It offers a number of extra features
and enhancements.

-----------------------
- System Requirements -
-----------------------
Unlike previous versions this version of MegaBoard will work with all
versions of Risc OS from 3.1 onwards.

---------------
- Terminology -
---------------
"MegaBoard" refers to this Program.
"Pinboard"  refers to the Risc OS 3 utility.

---------------
- Starting up -
---------------
MegaBoard can be Loaded by double clicking on the icon !MegaBoard in the
directory viewer.
When MegaBoard is first loaded it is necessary for it to reinitialise the
Filer. This will cause all open Filer Windows to be closed. Installing
MegaBoard into the boot sequence (see below) avoids this Problem.

-------
- Use -
-------

Filer icons
-----------
Placing Filer icons on MegaBoard:
An icon is placed on MegaBoard by dragging it from a Filer window and
dropping it on MegaBoard.

Moving:
An icon dragged and dropped onto another part of MegaBoard will be moved
to that position unless it is locked (see below).

Positioning and Grid lock:
Normally filer icons are positioned at the exact position they were dropped
on MegaBoard. However if the Grid lock option is on then any icons
placed or moved on MegaBoard will be positioned at the closest grid
point. The Grid lock option is toggled by choosing the Grid lock menu item
on MegaBoard menu.
Note: Grid lock only applies to Filer icons placed or moved when it is
      activated. Activating Grid lock has no effect on existing icons unless
      they are moved.
      Grid lock has no effect on special or window icons

Double-clicking:
Double-clicking Select on an icon placed in the manner described above has
the same effect as it would in a Filer window. Double-clicking Adjust is
identical unless the 'Adjust Removes' option is set in the main menu, in
which case the icon is also removed from MegaBoard.

Dragging:
Icons dragged from MegaBoard and dropped on other applications (including the
Filer) are also treated in the same way as icons dragged from a Filer window
with the exception of dragging with Shift copying not moving the selected
items.
Dragging with Adjust additionally removes the items from MegaBoard if the
'Adjust Removes' option is set in the main menu.

Selecting:
Filer icons can be selected in several ways:
1. Clicking Select on an unselected icon selects it and deselects all others.
   Clicking Select on a selected icon has no effect.
2. Clicking Adjust on an unselected icon selects it.
   Clicking Adjust on a selected icon deselects it.
3. Dragging Select on MegaBoard produces a bounding box within which all
   icons are selected.
4. Dragging Adjust on MegaBoard produces a bounding box within which all
   unselected icons are selected and selected icons are deselected.
5. Clicking Menu over an icon when none are selected selects that icon and
   opens the main menu.

Information:
Information on a Filer icon can be obtained by choosing the 'Info' option
from the 'File' Submenu.

Removing:
Filer icons that are no longer required can be removed from MegaBoard by
selecting them and choosing the 'Remove' option from the 'File' submenu.

Opening the parent directory:
The parent directory of a file or directory can be opened by choosing the
'Open Directory' option from the 'File' submenu.

Locking:
An icon can be locked to MegaBoard to prevent it from being moved. Locking is
toggled by choosing the 'Lock' option in the 'File' submenu. Locked filer
icons can still be dragged, but dropping them back onto MegaBoard will not
move them.

Moving to the front or back:
Should an icon be obscuring another it is possible to move it to the back of
the heap by choosing the 'Back' option from the 'File' submenu. Similarly an
icon can be moved to the front by choosing the 'Front' option from the same
submenu.

Navigating a directory:
Clicking menu over a directory icon enables the "Navigate" option in the
'File' submenu. Moving to its submenu arrow opens a submenu with the contents
of the directory as menu items, with directories (except application
directories) having subemnu arrows of their own. Moving over one of these
submenu arrows will open a similar submenu for the directory in question.
Choosing such a menu item with has the same effect as double-clicking on the
corresponding object in a filer window.
Note: Due to a shortcoming in Risc OS it is only possible to navigate six
directories deep from the parent directory, at this point directory items
will still have submenu arrows to indicate the fact that they ARE
directories, but they will not have any effect.

Altered files:
If a file whose icon is on MegaBoard, is deleted or renamed the icon will be
automatically removed from MegaBoard. Similarly if the filetype is altered,
the MegaBoard icon will be updated to reflect the change.

Window icons
------------
iconising application windows:
Clicking on a window's close icon with Shift will cause it to be reduced to a
MegaBoard icon. An exception is filer windows, these will only be handled in
the same way if the 'iconise dirs' option is set in the MegaBoard menu,
otherwise the icon of the parent directory is placed on MegaBoard as a Filer
icon (see above).

Removing:
Window icons cannot be removed using the MegaBoard menu. Double clicking
Adjust or Select on a window icon brings the window to the front and removes
the icon. The icon will also be removed if the window's parent application
closes or reopens the window.

Accessing menus of iconised windows:
iconised windows may have menus associated with them, if this is the case
then clicking Menu while pressing Shift opens this menu.

Note: Window icons cannot be locked.

Backdrops
---------
To create a backdrop execute the following steps:
1. Choose the 'Make' option from the backdrop submenu. This opens the
   backdrop setup dialogue box.
2. Drag the object (directory (see below), sprite, or draw file) containing
   the backdrop to the appropriately marked icon.
3. Select the desired horizontal and vertical positioning icons or the tiled
   icon.
4. Click on 'OK'.

To remove a backdrop choose the 'Remove' option from the Backdrop submenu.
If the 'Autoscale' option in the 'Backdrop' submenu is selected then the
backdrop will be scaled to always occupy the same number of OS-units not
pixels on the screen in the same way as icons. E.g. a backdrop in the
standard 1600x600 mode will be scaled to the same size it would be if the
resolution were 1600x1200. This sounds more complicated than it is the effect
of the autoscale option is best understood by experimentation.
When a backdrop is created, it is possible that part of the screen becomes
corrupted and is then redrawn, this is normal and not a bug.

Changing the background colour:
To change the colour of the background choose the 'Colour' option from the
Backdrop submenu.
Under Risc OS 3.5 this will produce a standard colour picker, which can be
used to select a new colour. The colour can then be chosen using a standard
colour selector. Under earlier versions, MegaBoard's own colour selector will
be opened. A colour can either be selected by clicking on one of the 16
desktop colours or by dragging the red green and blue sliders to the desired
values. Once the desired colour has been selected clicking on OK will apply
it to the background.

Cycled backdrops:
It is possible to select a number of backdrop pictures that will be displayed
successively each being visible for a user-defined time period before being
replaced by the next. This is achieved by the following procedure:

- Create a directory to hold the backdrop pictures.
- Copy the files into this directory (it is irrelevant whether these are draw
  files or sprites or a mixture of both).
- Create a script file, either by using the supplied !MakeScrpt application
  or you can write it yourself:

  Write a text file containing a list of entries of the following format:

    Start_Backdrop
      Horizontal position: <position>
      Vertical position: <position>
      Time: <Time the file should be displayed seconds>
      Name: <Filename of the file>
      Background colour red component: <percentage of colour saturation>
      Background colour green component: <percentage of colour saturation>
      Background colour blue component: <percentage of colour saturation>
    End_Backdrop

  Where the horizontal position is one of the following words:
  Centered
  Scaled
  Left
  Right

  and the horizontal position one of the following:
  Centered
  Scaled
  Top
  Bottom

  The colour saturation percentages are floating point numbers between 0 and
  100 e.g. "53.86%". The percent sign "%" is optional. If one or more of
  these fields is blank then those colour components be preserved from the
  previous backdrop.

  The filename should not be a complete path, but only a leafname i.e. if the
  pathname was "adfs::harddisc4.$.fred.pic0" then the filename would be
  "pic0". If this field is blank or the file does not exist in the directory
  then the backdrop picture will be removed for the specified time.

  There should be one such entry for each file to be displayed.

  Save the file in the same directory as the pictures with the filename
  "Script".

- Use the same procedure described above for creating normal backdrops, but
  instead of a sprite or draw file, drag the directory to the icon in the
  backdrop setup window. The settings of the positioning icons is irrelevant
  in this case as the positioning of the pictures is determined by the script
  file.

Special icons
-------------
Special icons are icons which can perform a variety of additional functions,
and can be defined by users with a knowledge of ARM code programming. See the
files 'ProgGuide' and 'ProgTut' for instructions on how to create new special
icons.

Placing:
Special icons are placed on MegaBoard by choosing their menu items from
the Special icon submenu.

Locking:
Special icons can be locked in the same way as filer icons, but contrary to
filer icons they cannot be dragged at all when they are locked.

Moving to the front or back:
Special icons can be moved to the front or back the same way as filer icons
(described above).

This version of MegaBoard includes the following special icons:

Pointer:
Displays the current position of the mouse pointer in screen coordinates.

Time:
Displays the current time in the format defined in its Format parameter (see
below for how to edit parameters). The Format parameter is a standard time
and date format string as described on page 327 of the RISC OS 3 User Guide. 
If the format string contained a syntax error the icon will not display the
time, but the word "ERROR" instead.

Gobbler:
Deletes files dragged onto it.

Acornlogo:
Displays an Acorn logo in the top-right corner of the screen. (Logo sprite by
Adam Goodfellow (adam@comptech.demon.co.uk)).

Parameters:
Some special icons (e.g. Time) can be configured by the user. This is
accomplished by editing its parameters in the following manner:
A special icon has parameters associated with it if its menu item has a
submenu arrow pointing to a parameter dialog box which contains a writaeble
icon for each parameter. Initially these icons contain the default values for
the parameters. If you wish to change any of them edit the value displayed.
When all parameters contain the desired values place the icon by clicking on
the 'Create' icon in the dialog box.

Surfaces
--------
Entering a name into the 'New surface' submenu then choosing that menu item
creates an icon resembling a directory. Double-clicking this icon appears to
clear the board,in reality however, it has merely caused a new 'surface' to
be displayed. Double-clicking Adjust on the background will return to the
previous surface and the icons will reappear.
Icons including additional surface icons can be placed on this new surface
as before. Nested surfaces can be viewed in a similar manner to
subdirectories in filer windows, double-clicking Adjust on the background
always moves to the parent surface.

Special icons:
Normally a special icon, like a filer or window icon will be restricted to
the surface in which it was created, however it may sometimes be desirable to
have a special icon visible on all surfaces. For example the AcornLogo
special icon would not be much use if it were only visible on one surface. In
order to make a special icon visible on all surfaces set the 'All surfaces'
option by choosing its entry in the 'Special' submenu.
Note: This option only applies to the icon for which it is set not to all
      special icons.

The Overview Window
-------------------
Opening:
The overview window is opened by choosing the 'Overview' option from the
MegaBoard Menu.

Function:
Displayed on the overview window is a "map" of MegaBoard. The white rectangle
around the centre represents the visible area i.e. the screen excluding the
icon bar. The surrounding light grey represents the area invisible to the
user.

Icons:
Icons are represented on the overview menu by small colour coded rectangles,
the following is a table of icon types and their colour codes:

  Red......File
  Blue.....Directory
  Green....Application
  Magenta..iconised window
  Black....Special icon
  Cyan.....Surface icon

Dragging icons on the on overview window:
Dragging an overview window icon and dropping it back onto the overview
window has the same effect as dragging it would on the MegaBoard i.e. the
icon is moved to the position it is dropped on. Dragging an overview window
icon to a different window has no effect.
Unless the 'Move locked' radio icon on the overview window is selected, an
attempt to drag a locked icon will have no effect.
If the 'Move locked' radio icon is selected, icons can be dragged and moved
regardless of whether or not they are locked. However this only applies to
the icons' representations on the overview window, restrictions to dragging
locked icons on the MegaBoard remain.


* Commands
----------
MegaBoard's support module provides two * Commands, '*Pin' and '*Backdrop'.

'*Pin <Pathname> <x_coordinate> <y_coordinate>' places the filer icon
specified by <Pathname> on the MegaBoard at the given coordinates.
Example: *Pin adfs::harddisc4.$.fred 200 200

'*Backdrop [-options] [Pathname]' creates a backdrop, whose positioning is
determined by the options as follows:

'-Centre'  centres the backdrop horizontally and vertically.
'-HCentre' centres the backdrop horizontally.
'-VCentre' centres the backdrop vertically.

'-Scale'  Scales the backdrop horizontally and vertically.
'-HScale' Scales the backdrop horizontally.
'-VScale' Scales the backdrop vertically.

'-Tile' Makes the backdrop tiled.

'-Top'    Aligns the top of the backdrop picture with the top of the screen.
'-Bottom' Aligns the bottom of the backdrop picture with the top of the icon
          bar.

'-Left'  Aligns the left of the backdrop picture with the left of the screen.
'-Right' Aligns the right of the backdrop picture with the right of the
         screen.

'-Remove' Removes the current backdrop (if present).

This list of options is in order of reverse priority i.e. if two or more
contradictory options are specified (e.g. -hscale and -hcentre) in one
command the one lowest on the above list will take effect.

Example: *Backdrop -HCentre -VScale adfs::4.$.Pic0
         Will use the picture in the file 'adfs::4.$.Pic0' as a backdrop. The
         picture will be horizontally centred and vertically scaled.

Installing MegaBoard in the boot sequence
-----------------------------------------
With Risc OS 3.5 onwards:
Run the supplied !Install applicationto install MegaBoard in the boot
sequence. It can be removed using the !UnInstall application.

With earlier versions of Risc OS:
If your system does not yet have a !Boot application it is necessary to
create one see the Risc OS User Guide for details on how to do this.

Copy the PinSupport module from the !MegaBoard application directory into the
!Boot directory and add the following line to the !Boot.!Run file:

  RMLoad <Obey$Dir>.PinSupport

Note: installing MegaBoard into the boot sequence removes the need for the
      filer to be reinitialise when it is first run.

-----------
- Credits -
-----------
Thanks are due to the following for testing, ideas and nagging for more
features:
Pavendip Birah (IRC nickname: PAV)
Asif Nazir (IRC nickname: Hawks)

And to the following:
Eli-Jean Leyssens (IRC nickname: Zorack) for the majority of the
conversion to Risc OS 3.1.
Roalt Zijlstra for desiging the multiple file sprite for Risc OS 3.1
and Adam Goodfellow for letting me use his AcornLogo sprite.

--------------------
- Copyright notice -
--------------------
Except for the addition of special icons this application may NOT be altered.
Nor may it be distributed for profit without my approval, this includes
distribution as an 'extra' with commercial products, however should you wish
to do so you are welcome to contact me do discuss details. A small charge to
cover copying and media is acceptable.

This program is SHAREWARE, if you find it useful please register as a user.
Registered users will be entitled to receive free upgrades (see below) and
improved support. The cost of registration is 15 Deutschmarks or 5 UK pounds
including a disc with the latest version of MegaBoard.
Please make all payments in cash only. Users outside the UK or Germany may
send local currency in, it should be equivalent to 15 Deutschmarks. (No coins
please. Should the amount sent exceed DM 15, you will be entitled to receive
upgrades free of P&P equivalent to the excess amount.)

Send registrations, comments, bug reports etc. to:

Sham Gardner
Vorderstr 19
76189 Karlsruhe
GERMANY

or EMail: un9l@rz.uni-karlsruhe.de

Upgrades
--------
Registered users can receive upgrades as follows:

From within Germany: Send a disc and a stamped-addressed jiffy bag to the
                     above address.
From outside Germany: Send a disc and the equivalent of 3 Deutschmarks (e.g.
                      1 Pound) to cover P&P to the above address.
Or by EMail from anywhere in the world: Send a short mail to the above
                                        address and I will reply with a
                                        uuencoded archive containing the
                                        latest version of MegaBoard (no P&P
                                        for EMail).

-------------------
- Version history -
-------------------

1.00 - First release version

1.01 - Minor bug fixed that occasionally caused icons to disappear.
       Option added to prevent double clicks with Adjust from removing icons.

1.50 - Special icon interface rewritten to require special icons to be
       written in ARM code. Avoiding the unpredictable memory requirements of
       BASIC librarys.
       The three special icons provided with MegaBoard rewritten in ARM code
       to adjust to this requirement.

1.51 - Minor bugs fixed and several little features added.

1.52 - Overview window and option to place directories instead of iconising
       filer windows added.
       iconised windows reopened by their tasks are now automatically
       removed.

1.53 - Selections of objects dragged from filer windows no longer all appear
       in the same spot

1.54 - Bug in special icon placing removed

1.55 - Scaled backdrops now require less memory.

1.61 - * commands '*Pin' and '*BackDrop' supported allowing e.g. textures to
       be set from !Configure.
       Special icon 'AcornLogo' added.

1.62 - Cycled backdrops supported.

1.63 - Changes to the desktop font handled properly.
       The colour picker now always reflects the current backdrop colour.
       Filer and window icon text is either black or white to ensure it is
       readable with any backdrop colour.
       Filer icons whose objects are altered e.g. their have type changed are
       automatically updated to reflect these changes.

1.64 - Facility to move icons to the front or back of the heap added.
       Window icons not longer slow down the system.

1.65 - Option added to auto-scale backdrops to fit the screen size in OS
       units not pixels.

1.66 - Minor bug fixes.
       Special icon parameters are now edited using a dialog box instead of a
       cumbersome submenu structure.

1.67 - Option to save as additional items added.

1.68 - "Navigator" feature added

1.69 - Multiple surfaces feature added.

1.70 - Adapted to work with versions of Risc OS earlier than 3.5.

1.71 - Bug concerning tiled backdrops removed.

1.73 - Bug causing icons to be incorrectly redrawn when using the system font
       removed.

1.74 - Bug involving the redraw of window icons removed.
