APIChanges
==========

This file documents the API changes for the Toolbox modules since the
publication of the User Interface Toolbox manual (0484,231 Issue 1 Dec 1994).
It should be viewed as a supplement to the Support Group's Application Note
280.


Toolbox (1.40)
-------

Extra service calls:

Service_ToolboxDying     &44EC4

On entry:  R1 = &44EC4
On exit :  All registers must be preserved.

This service call must not be claimed.

This service call is circulated by the Toolbox just before it dies.   It can
be used by object modules to keep track of whether they need to re-register
with Toolbox when they receive Service_ToolboxStarting.  Toolbox object
modules should only register with Toolbox when they first initialise and also
when they receive Service_ToolboxStarting having received
Service_ToolboxDying (or having got SWI not know errors during module init).



Extra SWIs:

Toolbox_Memory                  (SWI &44EF9)

On entry:
    R0 = bits (0-7) reason code
         bits (8-31) reserved - must be zero.
    R1,R2 depend on R0
    
On exit:
    R0 depends on R0 on entry.
    All other registers preserved.

This reason code is used to access the Toolbox's memory management
subsystems.  Currently three reason codes are provided to allocate,
deallocate and reallocate memory blocks.  The Toolbox's memory system
will store data allocated through its memory system in a dynamic area with
the title Toolbox.  If the OS does not provide Dynamic Area support (eg. RISC
OS 3.1), then the RMA will continue to be used.

Object module authors should note that they can no longer rely on the mapping
of object IDs to pointers to blocks of memory as the mapping now depends on
whether a dynamic area is being used or not.  No object modules should ever
have done this, but if any do, they'll suffer now on Risc PC and later.

Note that since the blocks returned will be in dynamic areas, code cannot be
placed in allocated blocks, and data pointers will need to be able to cope
with being at such high logical memory addresses.

Object modules should test the availability of the Toolbox_Memory SWI
during initialisation and fall back to using RMA all the time if that test
fails.  Object modules should not use a mixture of their own memory and
Toolbox allocated memory.

The memory system utilities OS_Heap to manage the data structures allocated
in the dynamic area, although this should not be relied upon.  The dynamic
area maximum logical size is limited to a maximum of 16MB or the machine's
available RAM whichever is smaller.



Toolbox_Memory_Alloc
On entry:
    R0 = 0
    R1 = amount of memory required

On exit:
    R0 = pointer to allocated block or NULL if unable to satisfy request


Toolbox_Memory_Free
On entry:
    R0 = 1
    R1 = pointer to block to be freed.
On exit:
    All registers preserved
    

Toolbox_Memory_Extend
On entry:
    R0 = 2
    R1 = pointer to already allocated block
    R2 = Size change for block (-ve to shrink it, +ve to enlarge it)
On exit:
    R0 = pointer to block (may have been moved), or -1 if block is
         now invalid (was shrunk to zero bytes or less)


--
Stewart Brodie
February 11th, 1998
