RISC OS 64 Toolbox, full 32-bit set for RISC OS 5 (@DATE@)
==========================================================

UNTESTED ON REAL 32-BIT HARDWARE. These modules are built, header-checked
and relocation-checked on the build machine only. Keep a way back (see
"Undoing it") before you install.

What is in it
-------------

  !System.310.Modules.Toolbox     every Toolbox module, 32-bit (ARMv4 code)
    .Res32.<name>.Messages        Messages for the 8.x Toolbox, Window,
                                  Menu and TextGadgets
  Choices.Boot.PreDesk.UnplugTbox the start-up program (BASIC)
  RePlugTbox                      puts the ROM's modules back
  Apps.ResEd32                    ResEd 0.65 and ResTest, 32-bit
  Docs                            placeholder for the programmer's manuals

Versions
--------

@VERSIONS@

Toolbox, Window, Menu and TextGadgets are the Unified Toolbox (8.x);
the dialogue classes are this tree's own (1.00 / 2.x). ProgressBar 8.03
is the round-end redraw fix. ColourPicker is included but only replaces
the ROM's when you ask (below).

Installing
----------

1. Merge !System with Configure > System > Merge (!SysMerge), dragging
   this package's !System onto it. The modules go to
   !Boot.Resources.!System.310.Modules.Toolbox, where applications'
   "RMEnsure Toolbox ... RMLoad System:Modules.Toolbox.Toolbox" lines
   look.
2. Copy Choices.Boot.PreDesk.UnplugTbox into your own
   !Boot.Choices.Boot.PreDesk directory (the one Choices:Boot.PreDesk
   points at). Do not put it in the RO*Hook boot files: on a disc with
   its own !Choices those are never read.
3. Restart. Check with *Modules (or *Help Toolbox, *Help Window): the
   versions above should be the ones running.

How UnplugTbox works
--------------------

The ROM's Toolbox modules can be replaced, contrary to what is often said,
by killing them before any task uses them. UnplugTbox runs from PreDesk,
before the desktop starts, and:

  * does nothing if *Set UnplugTbox$Disable 1 is set (any value but 0);
  * does nothing if Wimp tasks are running (Wimp_ReadSysInfo 0), so it
    can never pull modules from under a running application;
  * checks every module file is present first, and changes nothing if
    one is missing;
  * RMKills (OS_Module 4) the users before what they use: the classes and
    gadgets, then Menu, Window and Toolbox last; a module that is not
    present is skipped;
  * points Toolbox$Path, Window$Path, Menu$Path and TextGadgets$Path at
    Res32 so the 8.x core finds its own Messages;
  * RMLoads (OS_Module 1) the disc set in the RISC OS 64 ROM's order:
    ColourMap, RedrawManager, Toolbox, Window, Menu, ToolAction,
    TextGadgets, the gadgets, Iconbar and the dialogue classes. If one
    fails to load it is RMReInit'ed from ROM (OS_Module 3) and named in a
    single line; otherwise it prints nothing.
  * ImageFileGadget is loaded only if ImageFileRender is present.
  * It records the ROM modules it killed in UnplugTbox$Killed.

Options (set before PreDesk runs, e.g. in Choices:Boot.PreDesktop):

  *Set UnplugTbox$Disable 1       skip it entirely
  *Set UnplugTbox$ColourPicker 1  replace the ROM's ColourPicker too
  *Set UnplugTbox$Dir <dir>       load from <dir> instead of
                                  System:Modules.Toolbox

Undoing it
----------

  * *Set UnplugTbox$Disable 1 and restart, or delete
    Choices:Boot.PreDesk.UnplugTbox and restart: the ROM's modules run.
  * RePlugTbox does the same without a restart, but refuses while any
    Wimp task is running; run it before the desktop starts (for example
    from PreDesk in place of UnplugTbox). It kills the disc copies,
    RMReInits the ROM's copies (*RMReInit reverses *RMKill) and resets
    the four $Path variables.
  * If the desktop will not start: hold Shift at power-on to skip !Boot,
    then remove UnplugTbox.

Known limits
------------

  * Not run on any 32-bit machine. Built with clang 22 for ARMv4, as the
    Paint32/Toolbox32 zips that did run on hardware.
  * The dialogue classes are version 1.00 (DCS 2.00, Iconbar 2.01). An
    application that RMEnsures a stock class at a version above that
    would refuse them.
  * The classes use the Res and Messages files in your ROM's ResourceFS
    (as they were tested against RISC OS 5's own); only the 8.x core
    brings its own Messages.
  * ProgressBar's capsule look needs Wimp 6.42 ("G" validation); a stock
    RISC OS 5 Wimp draws a plain bordered bar instead.
  * ResEd 0.65 does not yet have an editor for PartitionBar.
  * Applications that do not RMEnsure their classes still work, because
    UnplugTbox loads the whole set at start-up.

Licence: MIT for this tree's modules and tools; ResEd is Apache 2.0
(Acorn's). Built from the RISC OS 64 tree, branch
feature/toolbox32-full-20261016.
