             !PinWay (C) Bernard Veasey 2003-2021 version 0.36
                  for RISC OS 3.10 - 5.xx (and Select 6.06)
                          >>> G I F T W A R E <<<
                       Email: bernard@bapfish.org.uk
                      Web: http://www.bapfish.org.uk/
                          Revised - 16 May 2020

MAIN FEATURES
-------------
o  Create and display up to 8 pinboards.

o 'PinWay' pinboards can be auto-saved.  eg. When the computer is shutdown,
   the program is quit or the user manually clicks 'Save'.

o  As well as normal Filer type objects such as Applications, Files and
   Directories which can be dragged to the 'PinWay' pinboard, 'Command'
   type objects which execute RISC OS commands can also be created on the
   pinboard.

o  You can choose the current backdrop.

o  Files from most other applications can be saved direct to the 'PinWay'
   pinboard.  eg. Just drag a 'save' icon from another application to a
   blank part of the 'PinWay' pinboard.

o  If you drop the 'save' icon from most other applications on to a
   directory icon that has previously been placed on the 'PinWay' pinboard,
   it will be saved to that directory and not the 'PinWay' pinboard.

o  'Link' objects on the 'PinWay' pinboard can have a different
   'display name' to the file it is linked to.  eg. An application could
   have a 'display name' to not include the '!' character.


INSTALLATION
------------
It is best to run !PinWay automatically on computer startup.  This can be
achieved by putting !PinWay in one of the following directories:

o  '!Boot.Choices.Boot.Tasks' (for RISC OS 3.10 to 4.02 and 5.xx)
o  '!Boot.Choices.Users.Single.Boot.Tasks' (for RISC OS Select)
o   Any directory that you have set to run using the RISC OS
    'Configuration > Boot > Run' window.

Alternatively, it can be placed wherever required.

PinWay's 'Options' and 'Pins' files are saved in the 'Choices$Write'
directory, which on RISC OS 3.10 to 4.02 and 5.xx is at:
'!Boot.Choices.PinWay.Options'.  With RISC OS Select, it is usually at:
'!Boot.Choices.Users.Single.PinWay.Options'.


INTRODUCTION
------------
'PinWay' is additional to the normal RISC OS pinboard and does not interfere
with or rely on it in any way.  It just sits in front of it - if you close
the 'PinWay' pinboard window by 'adjust' clicking on the 'PinWay' icon bar
icon, the RISC OS pinboard will be revealed if still required.

A PinWay pinboard supports 3 object types:

o  Link    - A Filer object dragged to the PinWay pinboard.
             (Similar to the RISC OS pinboard)
             'Link' objects can be 'removed' when finished with, leaving
             the original file intact.

o  File    - A file saved from another application on to the PinWay
             pinboard which is automatically stored in the
             <PinWayDrop$Dir> directory.
             'File' objects can be 'deleted' when finished with, deleting
             the actual file stored within the <PinWayDrop$Dir> directory.

o  Command - A command created from PinWay that operates a user-defined
             RISC OS command.


ICONBAR CONTROLS
----------------
'Select'              Opens the main 'PinWay' window.
                      (Also puts pinboard to background if in the foreground)
   SHIFT/Select       Brings 'PinWay' window to foreground.
                      (Clicking 'Select' only again reveals previous desktop
                      windows putting the PinWay window behind them.)

'Adjust'              Closes the main 'PinWay' window.
                      (eg. This reveals the normal RISC OS Pinboard)

'Menu'                Opens the 'PinWay' menu.


MAIN PINWAY PINBOARD WINDOW
---------------------------
'Select'              on icon selects it.
'Select' Drag         on icon - drags it around.
                      on background - drags out marker box around objects.
'Select' Double-Click on icon - Run's that 'PinWay' object.
                      If SHIFT is held down an application is opened etc.
                      If CTRL is held down when double-clicking a 'link' or
                      a 'file', its parent directory is also opened.
'Adjust'              on icon selects or de-selects an object.
'Adjust' Drag         on background - drags out marker box around objects.
SHIFT/'Select' Drag   to a Filer window on a 'link' or a 'file' moves it
                      instead of copying it.

Dragging a Filer Window object to the 'PinWay' window places it there ready
for Filer_Running etc.

A special PinWay object exists within the main PinWay window called 'Pins'.
When this is double-clicked, it cycles through the available 'Pinboards'.
The current 'Pinboard' is shown by the number displayed in the 'Pins' icon.
This can be dragged to a different position if required but be aware that
it moves the 'Pins' icon on ALL the pinboards to keep it in the same
relative position when cycling through all the pinboards to make for
easier operation.

Dragging a 'save' icon from most other applications to the 'PinWay' pinboard
will save it there.  It is stored in the directory <PinWayDrop$Dir> which is
at '<Choices$Write>.PinWay.Drop' by default.  If the name is the same as a
file already saved to the PinWay pinboard, that file will be overwritten.

Dragging a 'save' icon from most other applications to a directory icon that
has previously been placed on the 'PinWay' pinboard will save it to that
directory and not the 'PinWay' pinboard.

SHIFT/Clicking a vacant part of the PinWay pinboard opens the
<PinWayDrop$Dir> filer window where PinWay puts files saved from other
applications direct to the PinWay pinboard.

Dragging a 'link' or a 'file' out of PinWay to a Filer window copies that
object to the destination directory.  If SHIFT is held down the object is
moved instead.  If the object is dragged to another application, if it
supports the protocol, it loads it.


'PINWAY' WINDOW MENU
--------------------
Info               Opens the 'About this program' window.
                   Clicking the 'Globe' icon goes to the PinWay web page.
                   Clicking the 'i' icon loads this PinWay !Help file.

Link/File/Command
  Remove/Delete    Remove selected icons from the current 'PinWay' window.
                   If the object is a file that has been saved direct to the
                   Pinboard, it will be deleted.

  Pathname         Display object pathname.

                   If the object is a file saved on the pinboard, changing
                   the filename will rename it.

  Display name     Name of the object that is displayed on the 'PinWay'
                   pinboard.  By default, this is the same as the original
                   object.
                   
                   You can't change the display name of a file saved to the
                   'PinWay' pinboard.  Change the filename in the 'pathname'
                   menu entry (above) to rename it instead.

  Help             Run an applications !Help file.

  Command          View/Edit object command - Opens the 'Command' window.

  Open Filer       Opens the <PinWayDrop$Dir> filer window holding the files
                   that have been saved direct to the Pinboard.
                   
                   Open the filer window relating to the object selected.

  Copy             Copy selected objects to the PinWay clipboard.
                   This is useful for copying PinWay objects to another
                   PinWay pinboard.

  Paste            Paste previously selected objects to the current PinWay
                   pinboard.  The objects appear in the same place as the
                   copied objects.  If you want to make a copy of an object
                   on the same pinboard, 'copy' it, move the original and
                   then 'paste'.

Select all         Select all PinWay objects.

Clear selection    Clear selection of PinWay objects.

Options            Opens the 'PinWay' 'Options' window.

New command        Open the 'Command' window.

Pinboards          Open the 'Pinboards' menu - You can then choose which
                   pinboard you want by clicking on it.

Save               Saves the contents of the 'PinWay' pinboards.

Quit               Quit this program.


ICONBAR MENU
------------
Info               Opens the 'About this program' window.

Save               Saves the contents of all the 'PinWay' pinboards.

Quit               Quit this program.


OPTIONS WINDOW
--------------
X Grid lock        Sets the 'PinWay' object 'X' grid lock option on/off.
Y Grid lock        Sets the 'PinWay' object 'Y' grid lock option on/off.

Open on startup    Sets the 'Open on startup' option on/off.
                   When set to 'on', the 'PinWay 1' window is opened
                   automatically when !PinWay is first run.

Keep iconbar icon  When set to 'on', the 'PinWay' icon bar icon remains on
                   the iconbar until the application is quit, otherwise
                   it dissapears when a 'PinWay' window is opened.

Auto save          When !PinWay is quit or the computer is shutdown, the
                   current contents of all the pinboards are saved.

Confirm            When set to 'on', the user is presented with the
file deletes       message 'Do you really want to delete the file '###'?'
                   when deleting a file previously saved to the PinWay
                   pinbaord.
                   Clicking 'OK' deletes the file.
                   Clicking 'Cancel' aborts the delete operation.


Background colour  Choose the background colour of the text in a 'PinWay'
                   pinboard window as desired.  If you choose colour 1,
                   the text will have a transparent background.

Foreground colour  Choose the foreground colour of the text in a 'PinWay'
                   pinboard window as desired.

Up/Down arrows     Select your chosen backdrop from Sprite files stored
                   in 'BootResources:Configure.Textures'
                   The current Sprite filename is shown to the left.

White Arrow        Drag a suitable sprite file to this icon for your
                   custom designed backdrop.  Its filename will be shown
                   to the left.

Toggle icons       Clicking either of the toggle icons will choose either
                   a standard or custom backdrop.
                   'Adjust' click the custom toggle icon to clear the
                   custom pathname.

Cancel             Close the 'Options' window.

Save               Saves the 'PinWay' options.


COMMAND WINDOW
--------------
Name               Name of command.

Sprite <n>         Sprite name to represent command.

Command            Command to be executed - Any valid RISC OS command.

                   Some example 'commands':

 Name         Sprite      Command                                   Slab Task
 ----         ------      -------                                   ---- ----
 Modules      file_ffa    Help Modules                                No  Yes
 Podules      ramfs       Podules                                     No  Yes
 Free         harddisc    showfree -fs adfs 4                         No  No
 Hosts        network     FwShow                                      No  Yes
 Basic        file_ffb    Basic                                       No  Yes
 Null         directory   Filer_OpenDir Null::$                       No  No
 ROMs         ramfs       RomModules                                  No  Yes
 USB Devices              USBDevices                                  Yes Yes
 Hard Drive   harddisc    Filer_OpenDir ADFS::HardDisc4.$             No  No
 Task Window              TaskWindow -display                         Yes No
 Your message file_fff                                                Yes No
 NetRiscPC    file_f9f    Filer_OpenDir Share::NetRiscPC.$            No  No

         CAUTION - Some RISC OS commands could cause you a problem

Other possible * commands:

 *LanMan:ListFS
 *LanMan:LMInfo

Slab               If selected, this creates a slab type icon and does
                   not use the above sprite choice.

Taskwindow         If selected, this enables the output of a 'Command'
                   to be directed to a 'Taskwindow'.

KEYS
----
When 'PinWay' has the input-focus, by clicking on the pinboard, the
following key commands are available:

F1            Opens the PinWay 'About this program' information window.
              After opening this window with F1 another press of F1 opens
              the '!PinWay.!Help' file.
F3            Save the contents of all the PinWay pinboards.
F5            Open 'Goto pinboard <1-8>' menu.
DELETE        Remove/Delete selected object(s) from PinWay pinboard.
CTRL-F        Opens the filer window containing the selected object(s).
CTRL-C        Copy selected object(s) to PinWay clipboard.
CTRL-V        Paste previously copied/cut object(s) to current PinWay
              pinboard.
CTRL-X        Cut selected object(s) and copy to PinWay clipboard.
CTRL-A        Select all PinWay pinboard objects.
CTRL-Z        Clear all PinWay pinboard objects.
CTRL-F1       Engage pinboard 1
to            to
CTRL-F8       Engage pinboard 8
CTRL-PageUp   Bring PinWay pinboard to foreground.
CTRL-PageDown Return PinWay pinboard to background.


GENERAL INFORMATION
-------------------
Applications that are placed on the PinWay pinboard are automatically
booted (eg. 'seen') when the program starts up.

All 'PinWay' menus if 'adjust' is clicked keep the menu open whenever
possible.


PINWAY OPTIONS FILE FORMAT
--------------------------
o  File Version
o  Current standard backdrop number
o  Custom backdrop pathname
o  Custom/Standard backdrop flag (TRUE/FALSE)
o  8 spare
o  'X' grid lock (TRUE/FALSE)
o  'Y' grid lock (TRUE/FALSE)
o  Main PinWay window open (TRUE/FALSE)
o  PinWay icon bar icon (TRUE/FALSE)
o  Foreground colour
o  Background colour
o  Auto save option (TRUE/FALSE)

PINWAY PINS FILE FORMAT
-----------------------
o  File Version
o  Quantity of objects in Pinboard 1
o  Quantity of objects in Pinboard 2
o  Quantity of objects in Pinboard 3
o  Quantity of objects in Pinboard 4
o  Quantity of objects in Pinboard 5
o  Quantity of objects in Pinboard 6
o  Quantity of objects in Pinboard 7
o  Quantity of objects in Pinboard 8

o  Pinboard objects - pathname - sprite name - command -
   task window flag - Saved to Pinboard flag - 'x' postion - 'y' position



=============================================================================
ABOUT GIFTWARE
--------------
This program is giftware, not public domain.  Giftware means that if you
use this program regularly you are asked to send the author a 'gift'.

By sending a gift, your support helps to provide updates to this program
and an incentive for other RISC OS software to be developed.

To make a gift
--------------
Online donations can be made at http://www.bapfish.org.uk/software.htm

Upgrades
--------
The current site to obtain the latest version is from:

    http://www.bapfish.org.uk/

End-User licence conditions
---------------------------
You may give a copy of this software to a friend but you may only
distribute this software from your web site or on a CD-ROM or similar
device in bulk with the express permission of the author.
In the event of my death, this software will become open-sourced.

Disclaimer of liability
-----------------------
1. The software is supplied 'as is' the Author makes no warranty, whether
   express or implied, as to the merchantability of this software or its
   fitness for any particular purpose.

2. In no circumstances will the Author be liable for any damage, loss of
   profits, goodwill or for any indirect or consequential loss arising out of
   your use of the Software, or inability to use the Software, even if the
   Author has been advised of the possibility of such loss.

3. The author reserves the right to change the specification of this program
   without notice.


Bug Reports and Suggestions
---------------------------
Bug reports and suggestions will be welcome from all users, even if you have
not made a gift (yet).

Please enclose the following information:

    Computer:

    RISC OS version:

    Software version: 

    Problem/Suggestion:

    Any other relevant information:

and contact me by Email at:

    bernard@bapfish.org.uk

or by snail mail.
