/----------------------------------\
|             SFColours            |
| Star Fighter 3000 colours editor |
|     Christopher Bazley, 2001    |
|    Version 1.75 (02 Aug 2022)    |
\----------------------------------/
N.B. This text is best viewed at a display width of 77 columns.

-----------------------------------------------------------------------------
1   Introduction and Purpose
    ========================

  SFColours is an interactive editor for 'Star Fighter 3000' colours files.

  A object colours file (in '!Star3000.Landscapes.Palette') maps the 320
logical colours used for polygonal objects in the game to the 256 colours
which are actually available in screen mode 13. The extra 64 logical colours
are used for flashing lights and different ship liveries.

  A hill colours file (in '!Star3000.Landscapes.Hill') contains the 36
colours that are used to plot hills of a certain terrain type.

  In terms of practical uses of this editor, how about these suggestions:

   Designing a cool new livery for your Predator fighter.
   Creating mountain colours for a new type of landscape, in conjunction
    with SFtoSpr to create new textures. (Desert?)

  SFColours is one of a number of tools currently under development for use
with SF3000; as you will see if you visit my web site, a map editor is
already in existence. When these tools are finished, they will be
distributed as a suite of complementary utilities.

-----------------------------------------------------------------------------
2   Requirements
    ============

   RISC OS 3.10 or better.
   The so-called 'nested Wimp' (softloadable as part of Acorn's universal
    !Boot application).
   A !System directory (which must have been 'seen' by the Filer).
   The Toolbox modules (in !System or in ROM with RISC OS 3.6 and later).

  If any of the above facilities are unavailable then the program will fail
to load, with an error message describing the problem.

  Not essential, but desirable:

   The DragAnObject module (standard with RISC OS 3.5 and later).
   A modern version of the Window Manager which supports auto-scrolling
    (i.e. RISC OS 4 or later).

-----------------------------------------------------------------------------
3   Quick Guide
    ===========

  Load the SFColours application. Open your !Star3000 game directory and
locate the subdirectories 'Hill' and 'Palette' in 'Landscapes' or 'Disc2.
Landscapes'. Drag a file from one of these directories to the SFColours icon
on the icon bar, and an editing window will open.

  Within the editing window will be rows of coloured squares, the exact
layout of which depends on the type of colours file loaded. Each square
represents a logical colour (numbered across and down from the top left
corner), and the colour of that square shows the actual colour mapped to it.

  Click SELECT on a logical colour to exclusively select it, or ADJUST to
individually select/deselect colours. You can also select colours by
enclosing them in a rubber band box (started by dragging from one of the
gaps between the colours). Selected colours are highlighted with a border
and the actual colour number mapped to that logical colour.

  Double-click SELECT on a logical colour to change the actual colour
assigned to it. A colour picker dialogue box will pop-up showing the standard
256 colour palette. Select a colour from this and click OK to confirm your
choice and close the dialogue box.

  You can also copy colours by selecting them and then dragging with the
SELECT mouse button. When the button is released, any logical colours
aligned with the dragged colours (the relative positions of which are
maintained during the drag) will be re-mapped.

  To save the edited colours file, bring up the menu and navigate 'File'>
'Save'> to find an ordinary savebox. Run SF3000 to observe the results of
your changes.

-----------------------------------------------------------------------------
4   User Manual
    ===========

4.1 Jargon
    ------
  "Logical colour" - An abstract colour number that is used by SF3000 in its
definition of polygonal objects or hills, and which must be mapped to an
actual colour in order to be plotted on the screen.

  "Actual colour" - One of the 256 colour numbers available in screen mode
13. It corresponds directly to 8 bits of pixel data in the frame buffer.

  "Clipboard" - an invisible area of temporary storage that is used when
copying selected colours. SFColours uses the global clipboard, which means
that it is shared between all applications.

4.2 Data input and output
    ---------------------
  SFColours will attempt to load files dragged to its icon bar icon or any
of its editing windows. When a compatible file is dropped on an editing
window, logical colours will be re-mapped to the actual colours loaded
from the file, starting with the logical colour where the drag terminated.

  The standard format for colours files is compressed (see section 5.1)
with file type 'Fednet' (&154). Many SF3000 files have the same type and
therefore colours files are identified by their decompressed size. When
decompressed, each byte value is treated as an actual colour number. Files
can be saved in this format via the 'Save as' dialogue box.

  When a Fednet file is loaded, SFColours tries to guess whether it contains
hill or object colours based on its decompressed size (which should be 36 or
320 bytes, respectively). If it does not appear to be either format then an
error is reported.

  For compatibility with other applications and for saving subsets of a
colours file, SFColours can also load and save files of type 'CSV' (&DFE).
Comma-Separated Values is an industry-standard delimited ASCII data format
where fields are separated by commas and records are separated by carriage
return and/or linefeed. It is ideal for representing arbitrary-length
sequences of colour numbers.

  By default, selected colours are exported in CSV format when dragged
from an editing window to a directory display or another application.
However, the recipient can negotiate a different format. (Two incarnations
of SFColours instead exchange colours using the data format documented in
section 5.4.)

  When importing CSV data, SFColours evaluates each field of the first
record as a decimal value and reports an error if any of these values are
not valid colour numbers. Subsequent records are ignored.

4.3 The icon bar
    ------------
  Drag an object or hill colours file to the SFColours icon to open an
editing window. If an editing window is already open for that file then it
will be brought to the front instead.

  You can also drag selected colours from an editing window to the icon bar
icon, in which case they will be copied to a new editing window. However,
the relative positions of the selected colours will be lost.

  Click SELECT to create a new colours file. A dialogue box will open to ask
whether you want to create hill or object colours. All colours will be
initialised to black (except the 256 static object colours that you can't
see or change).

  Click ADJUST to bring all open windows to the front, in case they are
hidden behind other windows on the desktop.

  The icon bar menu entries 'Quit', 'Help...' and 'Info' should be self-
explanatory. The 'Views' submenu lists all open editing windows; click on an
item to bring the corresponding window to the front of the stack. The
'Create' submenu provides an alternative method of choosing which type of
file to create (and requires one fewer mouse click than the dialogue box).

4.4 Editing an object colours file
    ------------------------------
  An object colours file contains of 320 logical colours, but the first 256
colours are static and cannot be remapped. For that reason only 64 logical
colours are shown in the editing window.

  The logical colours are displayed as coloured squares, in sequence from
left to right, and in lines downwards from the top of the window. When
selected, logical colours will be highlighted with a border and the
corresponding actual colour number (0 to 255).

  Colours are shown in groups of four because a flashing light or ship engine
is drawn using an animated cycle of four colours. Most of the editable
colours are allocated to such animations.

  At the bottom of the window, a status bar displays a description of the
group of logical colours under the mouse pointer (e.g. 'Enemy ship lights').

  An overview of the logical colour number allocations is that animated
engine colours come first, then flashing lights (on buildings and fighters),
and lastly the livery of the player's ship (Predator Mk-IV).

  Unfortunately there is not currently a facility for seeing changes to the
Predator livery in real time (e.g. on the actual ship model). Therefore,
anything more than relatively straightforward changes to the existing
liveries may prove difficult.

4.5 Editing a hill colours file
    ---------------------------
  A hill colours file contains only 36 logical colours. These are displayed
as colour squares, in sequence from left to right in lines from the top of
the window. Selected logical colours are highlighted with a border and the
corresponding actual colour (0-255).

  There is no status bar on this window, because there is no simple
relationship between particular logical colours and the hill surfaces upon
which they will be applied. The general rule is to include gradated shades
of the landscape colours you want to include, then 'suck it and see'.

4.6 Mouse actions on editing window
    -------------------------------
MENU click : Open pop-up menu to allow operations on the file or selection.

On a colour

  SELECT click : If this logical colour is not already selected (or the Ctrl
                 key is held) then exclusively select it and deselect all
                 others.
  SELECT double-click: Open a colour picker to change the actual colour
                       associated with the selected logical colour(s).
  SELECT drag:  Copy all selected colour(s) to the drop location while
                maintaining their relative positions.
  ADJUST click : Toggle whether this logical colour is selected.

In gaps between colours

  SELECT drag : Start a rubber band box to exclusively select logical
                colours intersected by it.
  ADJUST drag : Start a rubber band box to toggle whether logical colours
                intersected by it are selected.

4.7 Editing operations
    ------------------
'Edit' > 'Undo'

  Undo the previous change to the colours file. Editing the file after
undoing one or more changes will erase pending redo actions from the edit
history so be careful. Changes to the selection are not recorded and cannot
be undone.

'Edit' > 'Redo'

  Redo the next change in the edit history of the colours file if at least
one change was undone since the last edit. Changes to the selection are not
recorded and cannot be redone.

'Edit' > 'Copy'

  Discard any data held on the global clipboard and copy the selected colours
to it. The positions of the colours, relative to the first selected logical
colour, will also be recorded.

'Edit' > 'Paste'

  If the global clipboard holds colours in a format understood by SFColours
then this operation will paste them into the editing window. Logical colours
in the destination window will be re-mapped to the actual colours on the
clipboard, starting with the first one selected (i.e. the highest and
furthest left). Care is needed because the relative positions of the colours
on the clipboard are restored when pasting; only the first will appear at
the mouse pointer.

'Edit' > 'Select all'

  Select all logical colours in the file.

'Edit' > 'Clear selection'

  Deselect any logical colours that may have been selected.

4.8 Effects on a selection
    ----------------------
'Effect' > 'Set colour' >

  Choose the actual colour to be mapped to the selected logical colours.
This choice is made from the standard 256 colour palette using a colour
picker dialogue box.

'Effect' > 'Interpolate...'

  Re-map the selected logical colours to a smooth gradient of actual colours
between the first and last selected. 'First' means the highest (and
furthest left) whereas 'last' means the lowest (and furthest right). At
least three logical colours (start, intermediate, end) must be selected
before this operation is available.

4.9 Keyboard shortcuts
    ------------------
In dialogue boxes

  Return  : Select default action (the button with a coloured surround).
  Escape  : Select cancel/abort operation, 'run away!'

Main editing window

  F1      : Help, i.e. open application manual (this text file).
  F3      : Open a savebox to allow the colours file or current selection to
            be saved.
  F8      : Undo the previous edit.
  F9      : Redo the next edit.
  Ctrl-F1 : Display file details, including date last saved and size etc.
  Ctrl-F2 : Close editing window (gives discard/save/cancel prompt if no
            other views of the same file exist).
  Ctrl-F3 : Immediate save to current file path (without opening savebox).
  Ctrl-A  : Select all logical colours.
  Ctrl-Z  : Deselect all logical colours.
  Ctrl-C  : Copy selected colours to the global clipboard.
  Ctrl-V  : Paste colours from the clipboard at the first selected logical
            colour.
  Ctrl-I  : Interpolate between first and last selected colour (see above).
  Ctrl-E  : Open colour picker to change the actual colour associated with
            the selected logical colour(s)
  Escape  : Abort a rubber band selection box or drag copy operation.

-----------------------------------------------------------------------------
5   Data formats
    ============

5.1 Compression format
    ------------------
  The first 4 bytes of a compressed file give the expected size of the data
when decompressed, as a 32 bit signed little-endian integer. Gordon Key's
file decompression module 'FDComp', which is presumably normative, rejects
input files where the top bit of the fourth byte is set (i.e. negative
values).

  Thereafter, the compressed data consists of tightly packed groups of 1, 8
or 9 bits without any padding between them or alignment with byte boundaries.
A decompressor must deal with two main types of chunk: The first (load a
byte) consists of 1+8 bits, and the second (copy data within output buffer)
consists of 1+9+8 or 1+9+9 bits.

The type of each chunk is determined by whether its first bit is set:

0.   Decode the next 8 bits of the input file (0-255) and write them as a
   byte at the current output position. The fact that this directive requires
   9 bits to represent 8 bits of information explains the inflation that can
   occur when attempting to compress random data.

1.   Decode the next 9 bits of the input file, which give an offset (0-511)
   within the data already decompressed, relative to a point 512 bytes behind
   the current output position. If this offset is greater than or equal to
   256 (i.e. within the last 256 bytes written) then decode the next 8 bits,
   which give the number of bytes (0-255) to be copied to the current output
   position. Otherwise, the next 9 bits give the number of bytes to be copied
   (0-511).

    If the read pointer is before the start of the output buffer then zeros
  should be written at the output position until it becomes valid again. This
  is a legitimate method of initialising areas of memory with zeros.

    A quirk of 'FDComp' is that least 1 byte is always written. That is
  probably a bug, although a well-written compressor should not insert
  directives to copy 0 bytes anyway. Note also that it isn't possible to
  replicate the whole of the preceding 512 bytes in one operation.

5.2 Object colours file
    -------------------
  Although object colour files always contain 320 values, they are of
variable length because they are stored in a compressed format (see above).
When decompressed, each byte is a colour number in the standard RISC OS 256
colour palette.

  The first 256 logical colours map directly to the standard colours. The
next 44 logical colours are flashing colours in groups of 4 (used for
spacecraft engines and coloured lights). The last 20 logical colours are
used to apply different liveries to the player's spacecraft.

Offset  Data
+0...   Static colours (standard 256 colours)
+256... Engine colours (16 bytes) :
  +256    Player's engine (4 colours)
  +260    Fighter's engine (4 colours)
  +264    Cruiser's engine (4 colours)
  +268    Super fighter's engine (4 colours)
+272... Fast flashing lights (12 bytes) :
  +272    Enemy ships (4 colours)
  +276    Friendly ships (4 colours)
  +280    Player's ship (4 colours)
+284... Medium flashing lights (16 bytes) :
  +284    'Ground obj 1' (4 colours)
  +288    'Ground obj 2' (4 colours)
  +292    Misc. (4 colours)
  +296    Misc. (4 colours)
+300... Player's ship livery (20 bytes)

5.3 Hill colours file
    -----------------
  Although hill colour files always contain 36 values, they are of variable
length because they are stored in a compressed format (see above). When
decompressed, each byte is a colour number in the standard RISC OS 256 colour
palette.

5.4 Colours export file
    -------------------
  The following data format is used by SFColours to export a group of
colours with positional information, if file type 'Data' (&FFD) is higher
than 'Text' (&FFF) and 'CSV' (&DFE) on the list specified by the receiving
task. The length should correspond to the number of colours recorded in the
header, plus the size of the header itself (12 bytes).

Offset  Data
+0      &534C4F43 ('COLS' in ASCII code)
+4      Version number (unsigned word; currently 0)
+8      Number of colours in this file (unsigned word)
+12...  Colours data (variable length) :
  +12     Colour 1 (see below for format of record)
  +24     Colour 2
  +36     Colour 3...

A colour record:
Offset  Data
+0      X offset (signed word)
+4      Y offset (signed word)
+8      Colour (unsigned word; colour number in default RISC OS 256 palette)

  When SFColours copies data to the clipboard, it records the positions of
the selected colours relative to the centre of the first (which will have
offsets 0,0 in the file). When colours are dragged using the mouse, the
coordinates are instead relative to the mouse pointer position at the start
of the drag.

-----------------------------------------------------------------------------
6   File types
    ==========

  The file types used by SF3000 are highly non-official. Presumably they
thought that this wouldn't matter for files used internally in the game. I
already know of some clashes (none serious) with other filetypes, but I
can't really alter them retrospectively.

Type  Name   Contents
----  ----   --------
&154  Fednet May be SF3000 compressed colours data (36 or 320 colours).
&FFD  Data   May be colour numbers with positional information, if exported
             from SFColours.
&DFE  CSV    Comma separated values, which SFColours can interpret as colour
             numbers if they are in the range 0 to 255.

  Note that filetype &154 is also used for other types of compressed Fednet
files, for instance the game title pictures, compressed game code, and Stunt
Racer 2000 tracks.

-----------------------------------------------------------------------------
7   Program history
    ===============

1.00 (7th July 2001) --------------------------------------------------------
   First version.

1.10 (15th August 2001) -----------------------------------------------------
   Implemented unsaved data warning on shutdown/quit.
   Fixed bug in Resources file (button gadgets for hill cols out of order)
   Savebox comes up on f3 even if valid path exists (as claimed in manual).
   Window names on list now include truncated not full filepaths.
   Increased verbosity and downgraded seriousness of errors on load/save.
   Error reporting is now slightly prettier for RISC OS 3.5+ computers.
   'Smooth' is now 'Interpolate' in line with SFskyedit (key is Ctrl-I not
    Ctrl-S).
   Moved File>Discard shortcut from Escape to Ctrl-Q in line with SFskyedit.
   Reduced 640 KB Wimpslot (left from debugging) to sensible level.

1.11 (19th September 2001) --------------------------------------------------
   Fixed bug in Loader component regarding multi-stage RAM transfers.

1.20 (24th December 2001) ---------------------------------------------------
   Total overhaul of sourcecode from the ground up, with many improvements
    and fixes not really externally visible.
   Now uses flexlib rather than the C library heap, for storing large data
    blocks. This means that the Wimpslot expands and contracts as necessary.
   ADJUST-clicking the close icon of a document window now opens its parent
    directory, as proscribed by the Style Guide.
   Added warning beeps for failed actions (e.g. interpolate when <3 entries
    selected).
   Improved greying/ungreying of menu items on ADJUST-click or hotkey press.
   Colours file creation dialogue box now pops up centred.
   Fixed flicker of hint text where pointer is moved over different
    colours, but within the same group.
   Fixed memory leak whenever a file was dragged to an open editing window.
   Fixed bug where dragging colours file to an open editing window
    overwrote bottom rather than final 64 entries.
   Fixed invisible bug where palette was re-opened for every selected
    entry, on Ctrl-E keypress.
   Fixed bug in Loader component with !Scrap transfer from other apps,
    where suggested leafname was shorter than '<Wimp$Scrap>'.
   No longer get weird colours by clicking at very edge of palette.

1.21 (8th January 2002) -----------------------------------------------------
   Minor improvement to handling of ADJUST-clicks on action buttons in
    palette dialogue box.

1.22 (11th November 2002) ---------------------------------------------------
   Improvements to some widely used error-checking macros allowed code size
    to be reduced together with increased efficiency.
   Added signal handler.
   Fixed nonsense in manual about ESCAPE shortcut.
   Shortened yucky 'Selection' menu entries.
   Corrected mistake in !Run file where the CallASWI module was not being
    loaded on RISC OS 3.6, despite being required on all OSes prior to 3.7.
   Recompiled using the official Castle release of 32-bit Acorn C/C++.

1.30 (11th June 2003) -------------------------------------------------------
   The interpolation function had been rather naughtily displaying the
    calculated ideal 24-bit colours rather than their nearest mode 13
    equivalents.
   Fixed a redraw bug in the palette dbox, though this was only evident in
    screen modes with a y eigen factor of less than 1.
   All dialogue boxes can now be reset by ADJUST-clicking on the 'Cancel'
    button.
   Integrates much better with the pinboard - any iconised window icon is
    removed when that window is re-opened independently by the application.
   When closed, transient dialogue boxes that claim the input focus now
    restore it to the previous owner. Implementing this required special code
    to work around deficiencies in the Toolbox and/or Window Manager.
   File paths are now canonicalised before being displayed or compared
    (i.e. 'IDEFS::Tamzin.$.!Boot.Choices' rather than '<Choices$Write>')
   More sensible response to error on Toolbox_Initialise (doesn't rely on
    messages file, which isn't open).
   Changed the close window key shortcut from Ctrl-Q to Ctrl-F2 to conform
    to the Style Guide.
   Moved the 'Help' entry to the top of icon bar menu and added another at
    the bottom of the document menu, as suggested by Castle.
   Now uses the Toolbox's standard 'Quit' dbox object rather than a custom
    dbox. The default action is now 'Cancel' rather than 'Quit'.
   Reorganisation of the document menu structure and other tweaking to the
    user interface after reference to the Style Guide.
   Actually reduced the wimpslot from 64 KB to 60 KB!

1.31 (19th August 2003) -----------------------------------------------------
   Even if there is no unsaved data when a PreQuit message is received, we
    now wait for the Quit message rather than dying prematurely.
   Where possible, changed to use SWIs instead of Star Commands for file
    access. This is faster and also reduces code size.
   Now demands version 5.43 of the shared C library, since this is the
    earliest version documented as supporting C99 functions (some of which
    are used).
   Formatted the manual text for a fixed-width 77 column display (Zap's
    default).
   The hill colours window may now be resized horizontally as well as
    vertically (didn't see why it shouldn't be.)

1.32 (13th September 2003) --------------------------------------------------
   The program now directly incorporates compression code, hence it is no
    longer dependent on the Comp and Decomp modules from !FednetRes.
   Released with source code under the terms of the GNU G.P.L.

1.33 (23rd October 2003) ----------------------------------------------------
   Internal changes.

1.34 (7th November 2003) ----------------------------------------------------
   On shutdown, no longer quits immediately that 'Quit' is selected from
    the quit confirm dbox. Instead all editing windows are closed and we
    wait for a Quit message (analogous to what Paint, Edit & Draw do).
   Now restarts desktop shutdown by sending a keypress event to the task
    that sent us the PreQuit message (as recommended by the PRM), instead of
    using SWI Wimp_ProcessKey.

1.35 (1st March 2004) -------------------------------------------------------
   Re-compiled with release 9 of CBLibrary.

1.36 (7th November 2004) ----------------------------------------------------
   Redesigned the create file dbox to use action rather than radio buttons
    for selection of palette type (only two mouse clicks needed rather than
    three).
   Reduced the size of the colour picker dbox, which now hangs off the
    Edit menu rather than requiring a menu click to open it. It no longer
    claims the input focus because a transient dbox should only 'borrow' it
    (Toolbox issue).
   Changed titlebar colours of transient dboxes to be grey regardless of
    whether they have the input focus (as per the Style Guide).
   Made changes necessary and/or desirable to compile with release 12 of
    CBLibrary.
   We no longer restore the initial savebox filename when a user clicks
    ADJUST on the Cancel button, because by rights this should be handled by
    the SaveAs module (which will hopefully be fixed, as Scale has been).
   Added system variables to !Boot file for Castle's proposed help system.

1.37 (19th November 2004) ---------------------------------------------------
   English default messages are now used to report flex memory errors
    because a bug in the library prevents use of our messages file.

1.38 (8th January 2005) -----------------------------------------------------
   When editing a polygon colours file, the main window now scrolls by the
    correct distance (exactly one 'page') when the user clicks in the well of
    the vertical scroll bar. Previously the area obscured by the status bar
    was not taken into account.
   Fixed longstanding memory leaks that would occur if a single editing
    window was repeatedly opened and then discarded. This was because the
    program had not made provision for removal of event handlers for the
    shared objects attached to this window.

1.39 (6th March 2005) -------------------------------------------------------
   New editing windows are now opened in a downwards stack starting at the
    centre of the screen (as per the Style Guide). Previously, new files
    would open centred on screen and files loaded would open at the pointer.
   The currently selected colour is now highlighted within the palette as
    well as being displayed separately at the bottom of this dbox.
   Duplicate files are now rejected earlier instead of being discarded
    after having been loaded.
   We now use global message 'BadParm' instead of a similar message of own.
   Various other internal changes including those necessary or desirable
    when building with release 15 of CBLibrary.

1.40 (14 May 2005) ----------------------------------------------------------
   Many internal changes - notably to processing of Toolbox events (now use
    our own event numbers) and tidying up upon object deletion. Code size
    has actually shrunk compared with previous versions!
   Added new key shortcut Ctrl-F3 to trigger an immediate save.
   Fixed bug where failure to save a file would result in two error
    messages in succession; one from the application and another from the
    SaveAs module.
   The menu tree is now closed if its state becomes outdated following use
    of a keyboard shortcut.
   Delegated to the Toolbox the task of opening the file creation dialogue
    box in response to clicks on our icon bar icon.
   Added a 'Create' submenu to the icon bar menu as an alternative to the
    file creation dialogue box.

1.41 (05 Aug 2005) ----------------------------------------------------------
   Changed Resource file so that editing windows don't initially open full
    size. This prevents problematic behaviour of the 'toggle size' icon.
   Updated ResFind from version 2.01b to latest version 2.12 (improved
    support for truncated country names & long paths).
   Built with release 18 of CBLibrary (which it requires).
   No longer requires the new (C99, APCS-32) shared C library or a version
    of the floating point emulator that supports LFM/SFM instructions.

1.42 (11 Aug 2005) ----------------------------------------------------------
   Moved definition of system variables for Castle's proposed help system
    from !Boot file to Obey file in subdirectory for relevant country (to
    allow internationalisation).
   !Run file no longer invokes ResFind a second time, having executed !Boot
    (which does so).

1.43 (02 Feb 2006) ----------------------------------------------------------
   General tidy up of excessive brackets and casting in source code.
   Updated our LoaderPreFilter function for compatibility with release 19
    of CBlibrary.

1.50 (10 Sep 2006) ----------------------------------------------------------
   It is now possible to select logical colours by dragging a rubber band
    box around them.
   It is now possible to copy colours by dragging them elsewhere in the
    editing window or to another window (even another application).
   Changed the layout of the hill colours window to resemble that for
    object colours. This allows colours to be easily transferred.
   Built with release 21 of CBLibrary (which it requires).
   Had to increase the wimpslot from 72 KB to 84 KB.

1.51 (14 Sep 2006) ----------------------------------------------------------
   Improved the efficiency of the code that searches for selected colours.
   The configured auto-scroll delay is now used during a drag operation
    (in the previous version scrolling started immediately).
   The data transfer message protocol is now bypassed if it is discovered
    that colours dragged from one of our editing windows were dropped in
    another (the data is instead copied locally).

1.52 (25 Oct 2006) ----------------------------------------------------------
   The icon bar icon now claims drags where it is interested in the file
    type offered, and accepts selected colours dragged from an editing
    window.
   You can now force exclusive selection by holding Ctrl whilst clicking a
    selected colour.
   Added a 'Web' button to the 'About this program' window. This requires
    a later version of the ProgInfo module.
   Can now import colours in the Data file format produced by SFskyedit.
   Can now export (but not import) selected colours in CSV and text format
    for compatibility with other applications.
   Now supports the global clipboard as well as drag and drop.
   Redesigned the menu tree attached to the editing window: Added 'Copy' and
    'Paste' entries to the 'Edit' submenu and moved 'Interpolate' and 'Set
    colour' to a new 'Effects' submenu.
   Renamed some objects in the Resource file.
   Major revisions to the manual text.
   Large-scale restructuring of source code for a better balance between
    source files.
   Increased initial memory requirement to 100 KB.

1.53 (09 Nov 2006) ----------------------------------------------------------
   Can now import colours in CSV format, so it is no longer necessary to
    support the esoteric data format in which selected colours were exported
    by SFskyedit versions 1.40 to 1.42.
   The default export format is now CSV. This manifests most clearly when
    selected colours are dragged to a directory display.
   Imported colours are now selected when displayed in a new editing
    window, after having been dragged to the icon bar icon.
   The name of file type &DFE is now defined when the application is 'seen'
    by the Filer. Moved the naming of file types into the country-specific
    Obey file 'SFColoursRes:SysVars'.

1.54 (18 Nov 2006) ----------------------------------------------------------
   Linked with a new version of CBLibrary to fix a bug where a spurious
    'your_ref' value was included in outgoing DataSave messages, if a drag
    had previously been claimed (even if the recipient was not the claimant).

1.55 (23 Nov 2006) ----------------------------------------------------------
   Fixed a minor bug where CSV was not treated as a compatible format for
    clipboard data, when deciding whether to fade the 'Paste' menu item.
   Corrected the title input focus colour of the colour picker dialogue box.

1.56 (26 Nov 2006) ----------------------------------------------------------
   Removed dependence on CBLibrary's Loader module. As a consequence it has
    been possible to reduce the initial memory requirement by 4 KB.
   The default document name (e.g. "<untitled>") and default leaf name for
    the save box are now in the messages file, to allow nationalisation.

1.57 (12 Sep 2007) ----------------------------------------------------------
   Fixed a bug where data of type Fednet (&154) imported directly from an
    application into an editing window (e.g. by dragging the file icon from a
    savebox) was not decompressed. This manifested as a misleading warning
    message 'Fednet data is not a recognised size of colours file'.
   Fixed a bug where DataSave messages received in reply to a DragClaim
    message were ignored if the drag destination was not the last window to
    be created (was dependent on the order of event handler registration).
    This was concealed by the fact that SFColours uses a short-cut when the
    drag destination is another editing window which it owns.

1.58 (25 Jun 2009) ----------------------------------------------------------
   Internal changes in preparation for saving in a format negotiated with
    the recipient, when a file icon is dragged from the save dialogue box
    (not yet utilised).
   It is now possible to save only the selected colours, rather than the
    entire file, by means of a new option button in the savebox.
   Fixed a bug where the heap block holding the path associated with a file
    being edited was deallocated immediately before copying that string to a
    new block, after the user chose 'File' > 'Save' from the menu. (Uncovered
    by Fortify, which overwrites the content of deallocated blocks
    immediately.)
   Now tends to stop whatever it was doing if the user chooses to continue
    execution after an unexpected error (to prevent recurring errors).
   Documented the decompression algorithm here.

1.59 (13 Sep 2009) ----------------------------------------------------------
   A binary search is now used to find which initialisation function to call
    (if any) for the template named in a Toolbox_ObjectAutoCreated event.
   The same code is now used when claiming a drag for the iconbar icon as
    when claiming a drag for a document window.
   Now uses a new CBLibrary function to read screen size instead of caching
    the current mode's dimensions in pixels.
   Slight optimisation/bugfix in the code for handling Dragging messages,
    which no longer continues iterating over the list of file types after
    finding an acceptable one.
   Changes to guard against "Invalid Object Id" errors when trying to
    determine whether Wimp messages are of interest to editing windows that
    have been deleted but for which no Toolbox_ObjectDeleted event has yet
    been delivered.
   Errors when dealing with activation of the 'Quit' button in the query
    dialogue box displayed during desktop shutdown are now treated as fatal.
   Stopped using reserved identifiers (those starting with an underscore
    followed by a capital letter).
   Reduced the decompressed executable size from 76928 to 75304 bytes by
    substituting data for code and hand-optimising.

1.60 (28 Jun 2010) ----------------------------------------------------------
   Fixed a bug where insufficient memory to paste colours from the clipboard
    when owned by SFColours had unintended the side-effect of wiping the
    clipboard. If it still owned the clipboard when told to quit then
    SFColours would linger indefinitely if it received a reply to its
    Message_ReleaseEntity broadcast.
   Specified the appropriate switches to prevent the Norcroft C compiler
    from generating unaligned memory accesses incompatible with ARM v6 and
    later (for RISC OS on BeagleBoard).
   Improved modularity of code, guided by moving structure definitions from
    header to source files and providing accessor functions where
    unavoidable.
   Uses new type-safe SWI veneers provided by release 34 of CBLibrary.
   No longer so reliant on SWI Toolbox_GetClientHandle (more efficient
    access to data associated with UI objects) and Toolbox_ObjectDeleted
    events.
   Gave names to a huge number of 'magic' values (numeric constants).
   Use 'flex_ptr' more widely to reduce the number of casts to that type.
   Removed some superfluous casts from 'void *' to other pointer types.
   Removed references to CBLibrary header file "TboxBugs.h".
   Expunged references to type and function names deprecated in release 34
    of CBLibrary.
   Reworded the advice appended when reporting error messages to the user.

1.61 (09 Jan 2011) ----------------------------------------------------------
   Linked against release 40 of CBLibrary, in which the compression and
    decompression code have been rewritten from scratch.

1.62 (28 Jan 2011) ----------------------------------------------------------
   Linked against release 42 of CBLibrary, in which the speed of compression
    and error detection during decompression have been improved.

1.63 (13 Feb 2011) ----------------------------------------------------------
   The 'About this file' window now shows the compressed rather than in-
    memory size of the file (i.e. the size of the file had it been saved at
    the moment the window was opened).
   Updated the amount of free memory required to start the application from
    96K to 140K (of which 104K is assigned to the application memory slot).

1.64 (25 Sep 2013) ----------------------------------------------------------
   Widespread minor changes to avoid type-casting the result address passed
    to function toolbox_get_client_handle.

1.65 (27 Sep 2016) ----------------------------------------------------------
   Removed the feature of saving non-standard-length compressed colours
    files (using a 'Selection' button in the savebox) and loading such files
    (by dragging them to a window or the iconbar). Instead, an error is
    reported. CSV files should be used for that purpose.
   Fixed the confusing behaviour where static colours were imported when
    an object colours file was dragged to an editing window; the first 256
    colours are now skipped.
   Fixed a bug where DataRequest messages wrongly claimed that SFColours
    could handle data of type Fednet (&154). (Compressed data can only be
    loaded by dragging it into SFColours, not by pasting from the clipboard.)
   Fixed a bug where garbage colour values could be pasted if the clipboard
    owner sent compressed data to SFColours (which can happen whether or
    not SFColours wrongly requests clipboard contents in that format).
   Fixed a bug where DragClaim messages sent by SFColours were too large.
   Fixed a bug where PreQuit messages were always assumed to incorporate a
    flags word, making it unpredictable whether or not desktop shutdown was
    restarted if no flags were present. That had little practical effect
    because the extra word is always present from RISC OS 3 onward.
   Toolbox_ObjectDeleted event handlers are no longer registered for shared
    objects that are created upon application initialization and never
    deleted.
   If a drag terminates within a window belonging to the same instance of
    the application then it no longer sends itself a Dragging message with
    the 'do not claim' flag set.
   Removed reliance on calling the _kernel_setenv function with NULL to
    delete a variable because of a bug in early versions of the shared C
    library (including 3.75, the minimum required).
   Reduced usage of short-lived flex buffers for passing data between
    functions; where necessary, a temporary array of 64 ints is declared.
   The EditColmap_create function no longer creates empty files; it only
    wraps existing files in a user interface.
   Removed functions unconnected with editing windows (IO_make_CSV_from_cb,
    IO_claim_drag) from the ColsIO.h interface.
   Much code refactoring: reduced use of 'goto' and made more use of C99
    idioms for variable declaration.
   Simplified OS error handling. Most OS calls are very unlikely to fail or
    have few side-effects (e.g. redraw), and are therefore handled at the
    earliest opportunity instead of being passed up the callstack.
   Linked against release 53 of CBLibrary, which provides new string buffer
    and linked list implementations which are utilised. Failure of the
    standard library's fseek function is now detected and the code to handle
    drags has been made more robust.
   Created a set of unit tests that simulate event delivery.
   Created an alternative makefile for use with GNU Make and the GNU C
    compiler.
   Optimised the makefiles by using $(addprefix ) and suffix-based rules.

1.66 (22 Jul 2017) ----------------------------------------------------------
   Fixed a bug (introduced in version 1.60) where closing an object colours
    editing window whilst it contained the mouse pointer could provoke an
    'Invalid Object Id' error.

1.67 (09 Feb 2019) ----------------------------------------------------------
   Added 'const' qualifiers to event handler function arguments.
   Updated the Makefiles to share a common list of source files and link
    with separate C libraries instead of the old monolithic CBLibrary.
   Deleted the build configuration in which OLD_SCL_STUBS was not defined.

1.68 (24 Feb 2020) ----------------------------------------------------------
   Added support for multiple views of the same file.
   Changed the colour interpolation code to round to the nearest integer
    instead of towards zero.
   Added support for pasting compressed colours from the clipboard.
   Now broadcasts caret-claim messages in response to gain-caret events to
    integrate better with other applications that move the caret to windows
    belonging to SFColours.
   Uses abstract data streams for input and output as required by the
    'Entity2', 'Saver2' and 'Loader3' components in release 58 of CBLibrary.
   Separated more of the platform-independent code from the user interface
    code and wrote unit tests for it.
   Eliminated 'extern' linkage specifiers and pre-declaration of 'static'
    functions where possible.
   Tweaked the application icons to have an irregular outline as is normal.

1.69 (03 Mar 2020) ----------------------------------------------------------
   Added support for undo and redo.
   Moved a little more platform-independent code into the back-end.
   Optimised use of streams to do multi-byte reads and writes.

1.70 (28 Oct 2020) ----------------------------------------------------------
   Internally, undo and redo are now part of the editor interface instead
    of the file interface, for consistency with other edit operations.
   Downgraded the SaveAs object template version for compatibility with
    ROOL's ResEd.
   Specified a list of messages of interest upon task initialization for
    improved efficiency.
   Defined a custom Toolbox event number for bringing all windows to the
    front, to allow the user interface to be reconfigured using ResEd alone.
   Rely less on toolbox_get_object_state() to determine whether objects
    are showing, since some versions return unreliable results.

1.71 (30 Oct 2020) ----------------------------------------------------------
   Linked with RISCOS Ltd's generic C library stubs ('StubsG').

1.72 (02 Dec 2020) ----------------------------------------------------------
   Linked with a bugfixed version of my streams library that cannot become
    stuck in an infinite loop when writing to a compressed file.
   A new CBlibrary function, loader3_load_file(), is used to load files
    dragged from a directory display to the iconbar icon.

1.73 (09 Dec 2020) ----------------------------------------------------------
   Linked with a bugfixed version of my streams library that cannot produce
    truncated output when writing to a compressed file. (Previous attempted
    bugfix had this bad side-effect.)

1.74 (01 Aug 2022) ----------------------------------------------------------
   Intercept #include of library headers (for debugging purposes) using
    local files of the same name, which requires use of "" instead of <>.
   Assign compound literals to ensure full initialization of dynamically
    allocated objects.
   Declare objects with initializers where possible.
   No longer uses a different error message for the specific case of an
    unsupported file type pasted from the clipboard.
   Simplified I/O code so that it no longer has to track requests for
    whether or not it is possible to paste from the global clipboard.
   Use new library veneers to SWI Wimp_DragBox (for scrolling a window
    while drag-selecting) and Wimp_AutoScroll.
   Use a new library function to remove all event handlers and delete a
    Toolbox object.
   Use bit fields for a struct with many Boolean members.
   Prefer returning early if successful rather than conditional error
    clean-up.
   Fading of the 'Paste' menu entry now relies on about-to-be-shown events
    generated by the root menu. Sending a Wimp message to the owner of the
    global clipboard when the 'Edit' menu was about to be shown didn't work
    on RISC OS 5 (probably because it doesn't update open menus).
   All files are now explicitly discarded on quit even if all files are
    unchanged, to avoid the appearance of memory leaks.
   Changed some comparisons between unsigned and signed expressions, and
    deleted some redundant assertions to satisfy GCC warnings.

1.75 (02 Aug 2022) ----------------------------------------------------------
   Check the return value of fclose() for error before marking a file as
    having no unsaved changes.

-----------------------------------------------------------------------------
8   Compiling the program
    =====================

  If you did not receive source code with this program then you can download
it from http://starfighter.acornarcade.com

  This program incorporates code from several C libraries created by the same
author: CBLibrary, CBOSLib, CBUtilLib, SF3KLib and GKeyLib. Source code for
those libraries is available at http://starfighter.acornarcade.com/mysite/

  To compile and link the program you will also require ISO 'C' (9899:1999)
library headers, stubs for the shared C library, and the flex, toolbox, event
and wimp libraries supplied with the Acorn C/C++ Development Suite. You must
ensure that the library directories clib, tboxlibs and flexlib are on your
C$Path, otherwise the compiler won't be able to find the required headers.

  Two make files are supplied:

   'Makefile' is intended for use with Acorn Make Utility (AMU) and the
    Norcroft C compiler supplied with the Acorn C/C++ Development Suite.
   'GMakefile' is intended for use with GNU Make and the GNU C Compiler.
    I have used it experimentally to compile but not to link the program.

  The APCS variant specified for the Norcroft compiler is 32 bit for
compatibility with ARMv5 and fpe2 for compatibility with older versions of
the floating point emulator. Generation of unaligned data loads/stores is
disabled for compatibility with ARMv6. When building the code for release,
it is linked with RISCOS Ltd's generic C library stubs ('StubsG').

-----------------------------------------------------------------------------
9   Licence and Disclaimer
    ======================

  This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public Licence as published by the Free
Software Foundation; either version 2 of the Licence, 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 Licence for
more details.

  You should have received a copy of the GNU General Public Licence along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.

-----------------------------------------------------------------------------
10  Credits
    =======

  SFColours was designed and programmed by Christopher Bazley.

  Credit goes to David O'Shea and Keith McKillop for working out the
Fednet compression algorithm. David wrote a DeComp module for use with the
Stunt Racer track designer, which early versions of SFColours relied upon.

  Olaf Krumnow and Herbert zur Nedden of the German Archimedes Group wrote
the ResFind program I use to find the correct resources for different
languages.

  Thanks to the denizens of comp.sys.acorn.programmer for their advice - in
particular Kevin Bracey, Richard Murray and Stewart Brodie.

  The application name 'SFColours' (including associated sprites/system
variables) has been officially registered with RISCOS Ltd.

  The game Star Fighter 3000 is  FEDNET Software 1994, 1995.

-----------------------------------------------------------------------------
11  Contact details
    ===============

  Feel free to contact me with any bug reports, suggestions or anything else.

  Email: mailto:cs99cjb@gmail.com

  WWW:   http://starfighter.acornarcade.com
