=============================================================================
Float - Floating Interactive Help                                Version 1.01

(C) Stephen Fryatt, 1999-2017                                    5 March 2017
=============================================================================

Licence
-------

  Float is licensed under the EUPL, Version 1.1 only (the "Licence"); you may
  not use this work except in compliance with the Licence.

  You may obtain a copy of the Licence at
  http://joinup.ec.europa.eu/software/page/eupl

  Unless required by applicable law or agreed to in writing, software
  distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  See the Licence for the specific language governing permissions and
  limitations under the Licence.

  The source for Float can be found alongside this binary download, at
  http://www.stevefryatt.org.uk/software

  The necessary libraries and build tools can be found at
  http://www.stevefryatt.org.uk/software/build



Introduction
------------

  Float is a "Floating Interactive Help" application for RISC OS.  It is
  intended to replace Acorn's Help application, providing interactive help in
  small "floating" panes that follow the mouse around the screen.  This is
  similar to some of the systems available on other platforms.

  Float will work with any application that supports Acorn's interactive help
  protocol, that is any application that works with Help.

  Some of the "nice" features of Float are:

  * Configurable pane appearance: font, colours and shadow can be user set
  * Supports help on window tools
  * Can ignore help from selected applications (such as Filer, Pinboard, etc)
  * Supports full iconbar help
  * Ability to quickly toggle panes on and off
  * Full support of Help dictionary



Installing Float
----------------

  Float requires RISC OS 3.8 or later; it may work on earlier versions, but
  requies the Nested Wimp and is not supported.  The code should be 26/32-bit
  neutral and ARMv7 aware, and should therefore run on all hardware systems.
  Float can be run off a hard disc or floppy disc.

  To install Float, copy the !Float application to a suitable place on your
  disc.  If you want it to run on startup, Float should be placed in your
  boot sequence.  On a machine with the new boot structure installed, this
  can be done by adding it to the list of tasks to be run on startup via
  Configure.  On older machines, you will have to make your own arrangements
  (but you will probably have made your own boot system anyway).

  | (!) If you are updating to Float 1.00 or later from version 0.36 or
  |     earlier, the contents of the application directory have changed.  As
  |     such, you are advised to delete (or move out of the way) your
  |     existing !Float application and replace it with the new one, instead
  |     of simply copying the new one on top of the old.

  By default, Float will set the system variable <Help$Start> when it is seen
  or run by the Filer.  This makes it the default interactive help client to
  be loaded if one is required.

  This feature can be disabled if required.  Shift-double-click on !Float and
  load the !Boot and !Run files into a text editor (Shift-double-click on
  them).  Find the line in each file that starts with:

    Set Help$Start ...

  Comment it out by inserting a vertical bar in front of it, like this:

    |Set Help$Start ...

  Re-save the two files and after the machine has been re-started Float will
  no longer be the default interactive help client.

  To restore Float as the default client, repeat the process but remove the
  vertical bar.



Using Float
-----------

  To use Float, run it in the usual way by double-clicking on the !Float icon
  in a directory viewer.  When its icon appears on the iconbar, pointing at
  different bits of the desktop will cause help panes to appear after a short
  (user-defined) interval.  Moving the mouse causes the panes to disappear;
  they disappear on their own after a given time anyway or when the mouse is
  clicked or a key pressed.

  The panes can be toggled on and off by clicking Select on the Float icon on
  the iconbar.  When the icon is "greyed out", no help is provided: this can
  allow you to get on without the help getting in the way.



User Choices
------------

  Clicking Adjust on Float's iconbar icon or selecting 'Choices...' from its
  iconbar menu allows many aspects of Floating Help's operation to be
  altered.  The dialogue is split into three sections on separate tabs, which
  can be accessed by clicking on their buttons in the right-hand margin.

  Once the choices have been set as required, clicking Select on 'Apply' will
  apply them to Float; clicking with Adjust will also leave the dialogue open
  so that further changes can be made.  Clicking on 'Save' behaves in a
  similar way, but also saves the changes to disc so that they become the new
  default options when Float is next loaded.

  In contrast, clicking Select on 'Cancel' will forget any changes made in
  the dialogue and close it; clicking with Adjust will leave the dialogue
  open, but reset its contents to reflect the settings currently in force.


  Display options
  ---------------

  The 'Display' tab contains options which affect the way that help messages
  are opened and closed (the 'Opening' section), and which messages are
  presented to the user (the 'Messages' section).

  'Open panes' determines whether help panes are shown or not.  This is not
  quite the same as clicking Select on Float's iconbar icon, as it also takes
  effect when Float is next run.  If the state of this option is changed,
  then the new state is reflected on the iconbar when the changes are applied
  (by clicking on 'Apply' or 'Save'); if the state is not changed, then the
  iconbar state is not affected (even if it differs from the setting of 'Open
  panes').

  'Open after' gives the time, in seconds, that the mouse must be
  "stationary" for before a pane is displayed.  Stationary means that it does
  not move more than, by default, 8 OS units in any direction.

  'Auto close panes' determines whether panes are closed after a given time.
  If set, panes will be closed after being open the number of seconds given
  in the 'Close after' field; if unset, panes remain on display indefinitely
  if no mouse or keyboard activity is seen.

  'Close on key press or mouse click' indicates whether to close a pane when
  keyboard or mouse activity is detected, and to prevent a pane from opening
  if a key press or mouse click occurs before the 'Open after' time. 'Stay
  closed over drags' can be used to prevent panes opening at the end of a
  drag.  It can only used if the option above is selected.

  The remaining options on this pane control the types of help message to be
  displayed. 'Show help for window furniture' allows the user to decide
  whether or not help should be shown for the furniture around the edge of a
  window.  If this is off, the potentially distracting messages will not
  appear.  This can be temporarily overridden by the 'Show all' option in the
  iconbar menu.

  'Show help over iconbar' selects whether or not help is given for the icons
  on the iconbar.  When on, help is given for all the icons (with the
  information being 'made up' for those applications who do not provide help
  if the 'Show default message' option is ticked).  This setting is ignored
  (with messages being displayed) if 'Show all' is ticked in the iconbar
  menu.

  'Show default message' determines whether or not Float will make up
  messages for applications not responding to the help requests.  This
  message will just identify the application that the window (or iconbar
  icon) belongs to.  If 'Show all' in the iconbar menu is ticked, these
  messages will appear regardless of this setting.


  Appearance options
  ------------------

  The 'Appearance' tab contains options relating to the appearance of the
  help message pane.

  The 'Font' section selects the font used to display the help text.  This
  can be changed by clicking Select on the pop-up menu icon to the right of
  the 'Font' field; its size and aspect ratio (the width divided by the
  height) can also be set.  If you have RISC OS 3.5 or later, then ticking
  'Use desktop font' will ignore these choices and use the currently selected
  desktop font; if the desktop font is the System font, then the font set in
  Float's choices will still be used.

  The 'Colours' section specifies the colours which will be used when drawing
  the help panes. 'Text' sets the colour for the text and pane borders, while
  'Background' sets the colour used for the the pane background.  If 'Draw
  shadows' is ticked, then 'Shadow' sets the colour for the drop-shadows
  behind the panes.  For each colour, clicking Select on the pop-up menu
  button to the right of the field will allow a new colour to be selected
  from the Wimp's palette.

  The 'Draw shadows' switch determines whether to draw drop shadows behind
  the help panes.  When present, these are a fixed size and appear as if the
  light is from the top left of the screen.


  Task Ignore options
  -------------------

  The 'Ignore Tasks' section allows Float to be configured to ignore help
  messages from certain applications; the 'Ignore' section contains a list of
  tasks which are currently being ignored.

  To add a task to the list, enter its name in the field below the list (at
  the base of the 'Ignore' section, to the left of the 'Add' button) and
  click on 'Add'.  The name must appear EXACTLY as it does in the Task
  Manager's display, with all spacing, punctuation or control characters
  reproduced exactly.  To make this easier to achieve, the pop-up menu button
  to the right of the field gives a list of the names of all the applications
  which are currently running.  Task names can be selected from this menu to
  insert them into the field (after which, 'Add' must be clicked to add the
  name to the list in the usual way).

  To remove applications from the list, select their entries (by clicking
  Select and Adjust in the usual way) and click on 'Remove'.

  As with the other options for restricting the help messages which are
  presented, the contents of the ignore list will itself be ignored (such
  that help will be shown for all applications) if 'Show all' is ticked in
  the iconbar menu.


  Other options
  -------------

  All of the choices are stored in a file called Choices.  Depending on
  whether the machine has a new Boot structure, this will either be at
  Choices:Float.Choices or at !Float.Choices.  The default options can be
  restored by deleting this file; you should always do this before letting
  anyone have a copy of Float if the file is stored inside the application.
  Note that if all the options are default there may not be a Choices file
  present at all.

  Some options are not available from the choices window, but these can be
  added manually to the Choices file using a text editor.  One choice
  occupies a line, with the option name being followed by a colon and the
  value.  The extra options that you can specify here are as follows:

  Mouse jitter

    How far the mouse can be moved in any direction before the bubble gets
    closed, measured in OS units.  Default is 8.

  Poll delay

    How many centiseconds between WIMP idle poll requests.  This value can be
    increased to reduce the overhead on a slower machine, at the expense of
    responsiveness.  Default is 5.

  If there is no Choices file, create a new one by opening the Choices
  dialogue and clicking on 'Save': this will place the file in the correct
  location for the system it is running on.

  Lines in the file starting with a "#" are comments.  An example file might
  be:

    # >Choices
    #
    # An example file

    Poll delay: 10
    Mouse jitter: 16

  Float will need to be reloaded to make changes made to the Choices file
  take effect.



Known Limitations and Problems
------------------------------

  As far as I know there are no bugs in Float, although I will probably be
  proved wrong.  There are one or two known limitations, though.

  Float does not deal fully with the GSTrans specification when it parses
  help messages.  It will treat "|M" as a line (or paragraph) break, and it
  will substitute "|", "<" and """ for "||", "|<" and "|"" respectively, but
  all other GSTrans codes are currently ignored (and stripped out).  If you
  do something like "|G" or "|!)" it will not work (the first being ignored
  and the second coming out as ")" instead of the copyright symbol).

  Two consecutive line breaks ("|M|M") are treated as a string terminator.
  This is deliberate, as it appears to be what Acorn's Help does, but it does
  not appear to be in the specification in the PRMs.  Unfortunately, some
  programs appear to "make use of" this feature by putting garbage between
  the "|M|M" and the help text terminator.

  All control characters in the help text are also treated as terminators.
  This does not follow the spec, which states that a char 0 is the
  terminator, but some applications use char 13 to terminate and yet more do
  other nasty things.

  Some of the pane hiding features (such as 'hide across drags') do not
  always work as expected.  This is because the WIMP does not always talk to
  Float enough, especially when dragging and scrolling windows.  I am looking
  into fixing this.

  Finally, if a screen refresh occurs (for example by pressing F12 followed
  by Return) the area immediately around the pane will be corrupted,
  especially if a shadow is present.  This is a limitation of the way
  transparent windows are handled by the WIMP, but it is not harmful.



Future Plans
------------

  The following is a list of ideas that will hopefully be added to future
  versions of Float.  If you would like to add to this list, please contact
  me and let me know.

  * Checking the icon below the pointer to stop help repeatedly appearing
    over the same icon or window background.



Version History
---------------


  0.01 (20 February 1999)
  -----------------------

  * Initial release version.


  0.02 (6 March 1999)
  -------------------

  * Keypresses now close bubbles.
  * Code to open and close bubbles rationalised.


  0.03 (16 March 1999)
  --------------------

  * Fixed problems with different help abbreviations in different versions of
    RISC OS.
  * Fixed bug causing lockup for null help texts.
  * Added option to hide help from window furniture.
  * Added Adjust click on iconbar to open Choices window (Ticket #3).


  0.04 (6 June 1999)
  ------------------

  * Added task handle checking to allow specific tasks to be ignored.
  * Moved more hard-coded text to the Messages file.
  * Added option to hide help from the iconbar.
  * Correct internationalisation added, including automatic resource
    location.


  0.05 (27 April 2000)
  --------------------

  * Tidied up and improved the bubble opening and closing code.
  * Option to display default text for windows that do not respond to help
    requests.
  * RISC OS 4 compliant.


  0.06 (17 October 2000)
  ----------------------

  * Recognises Message_HelpEnable (&504) to allow the help state and
    configuration to be altered.
  * Fixed some internationalisation issues, including to_upper function.


  0.07 (10 February 2001)
  -----------------------

  * Help pane has bit 23 of the window flags set, to make operation on
    RISC OS 4 better.
  * Font options are now set from the Choices window; an option has been
    added to allow the desktop font to be used under RISC OS 3.5 or above.
  * Problem with swallowed F12 keypresses has been fixed (occurred if Choices
    had the caret).


  0.10 (19 February 2001)
  -----------------------

  * Fixed new Desktop Font option so that it cannot be selected on versions
    of the Window Manager of 3.11 or less.


  0.11 (1 March 2001)
  -------------------

  * Made Choices window action buttons more Style Guide compliant
    (Adjust-'Cancel' now resets window contents but leaves window open).
  * Fixed some typos in the UK Messages file and !Help file.


  0.20 (25 June 2001)
  -------------------

  * Now uses ROM Messages for token expansion and furniture messages so it
    will work 'out of the box' on any version of RISC OS (thanks to Justin
    Fletcher for pointing this out).
  * Possible bug with Messages file fixed.
  * Help file linked to iconbar menu.
  * Templates tidied up for RISC OS 4.


  0.21 (27 June 2001)
  -------------------

  * Added fallback to internal lists of message tokens if the ROM messages
    can not be found.


  0.22 (29 June 2001)
  -------------------

  * Fixed the bugs in the code added in 0.21 (specifically the fact that
    Float would fall over if system variables set in the new Boot were not
    present).


  0.23 (30 June 2001)
  -------------------

  * Fixed further problem with MessageTrans file handling that prevented
    messages being displayed correctly if Float was loaded in the Boot
    sequence.
  * Choices window opens centred on pointer, as per Style Guide.


  0.24 (3 July 2001)
  ------------------

  * Hopefully fixed problems which allowed the Desktop font to be selected on
    RISC OS 3.1.
  * Stopped the state of the iconbar icon getting confused when the choices
    were applied (ie. it could show on when actually off).


  0.25 (2 August 2001)
  --------------------

  * An option to turn off the default help giving the task name for
    applications which do not respond to help requests has been added.


  0.26 (15 August 2001)
  ---------------------

  * If the selected font is not available, Float will fall back to use
    Trinity.Medium.
  * Selections from the font menu are now handled correctly when territories
    are specified in the font name.


  0.27 (26 February 2002)
  -----------------------

  * Fixed bug that prevented expansion of '\\' in help texts from working.


  0.28 (17 June 2002)
  -------------------

  * Supports the use of the WIMPSymbol font for RISC OS 3.5 and later, so
    that symbols like 'shift' appear correctly in help texts.


  0.29 (19 June 2002)
  -------------------

  * Fixed bug causing lockup for non-NULL-terminated help texts, introduced
    in 0.28.


  0.30 (25 June 2002)
  -------------------

  * 'Show all' option added to iconbar menu.


  0.31 (1 August 2002)
  --------------------

  * Poll_Idle events are now only claimed if bubble display is on.
  * The option to set <Help$Start> was added to !Boot and !Run.


  0.32 (18 August 2002)
  ---------------------

  * Corrected behaviour for enable/disable bit of Message_HelpEnable.


  0.34 (29 October 2002)
  ----------------------

  * Fixed Desktop Font corruption which occurred on mode changes.
  * Fixed bug that left pane on screen if help was turned off while text was
    being displayed.
  * Internationalised the help text, converted master copy into ManTools
    format and supplied in StrongHelp and plain text formats.


  0.35 (7 December 2002)
  ----------------------

  * Code checked for obvious 32-bit problems.
  * OS_Byte 13/14 used to request EventV.
  * Choices are now saved into Choices: if this exists.


  0.36 (19 May 2003)
  ------------------

  * Bug in vector code that showed up on Iyonix fixed.


  1.00 (18 January 2015)
  ----------------------

  First full release.

  * Build system revised and licence updated to EUPL.
  * ARMv7 safe and compatible with modern versions of RISC OS 5.
  * Added 'Website' button to Program Info window.
  * Changed error system to use Locate 1's WimpError library.
  * Added 'Help' entry to iconbar menu (Ticket #480).
  * Interactive help code is more tolerant of unexpected input (Ticket #244).
  * New Choices interface implemented, with facility to set applications to
    be ignored.
  * Removed RMA memory leak from OS help token handling code (Ticket #543).
  * Application sprites updated.
  * Choices dialogue now filled correctly, with field length bounds-checking
    and configured font name intact (Ticket #541).
  * Position application to right-hand end of iconbar, alongside RISC OS's
    own Help (Ticket #544).
  * Only one copy of Float can be running at any given time.


  1.01 (5 March 2017)
  -------------------

  Update to first full release.

  * Fix !Help so that 'Help' menu items work correctly.




Updates and Contacting Me
-------------------------

  If you have any comments about Float, or would like to report any bugs
  that you find, you can email me at the address below.

  Updates to Float and more programs for RISC OS computers can be found on
  my website at http://www.stevefryatt.org.uk/software/

  Stephen Fryatt
  email: steve@stevefryatt.org.uk
