RISCOS.com

www.riscos.com Technical Support:
Toolbox

 


Introduction to the Toolbox


This chapter is intended to give the reader an overview of the RISC OS Toolbox, and to introduce the concepts used throughout the rest of this manual.

Introduction

The Toolbox was designed with the following goals:

  • to facilitate writing consistent, high-quality desktop applications under RISC OS 3.10 and later
  • to encourage the writing of applications whose user interface complies with the RISC OS 3 Style Guide
  • to be easy to learn
  • to be language-independent
  • to make it no harder to do operations which can currently be done using the Wimp.

The Toolbox has the following characteristics:

  • it is structured as a set of RISC OS relocatable modules
  • it will only run on RISC OS 3.10 or later
  • it does not directly call back to code in the client application
  • it is SWI-driven
  • it can be used from C, C++, BASIC or Assembler with equal ease
  • communication back to the client application is via events
  • the client application does not have direct access to data structures maintained by the Toolbox
  • it uses a new resource file format to hold templates for the user interface objects which the application will use at run-time.

Note: The Support for RISC OS 3.10 describes support for RISC OS 3.10 machines.

Installing C/C++

The instructions for installing Acorn C/C++ are in the Installing Acorn C/C++ of the Desktop Tools manual.

Terminology

The following terms are used throughout this manual:

Term Meaning
Class A data type, together with a definition of the operations which can be performed on that data type
Client application A piece of software which uses the Toolbox
Colours Refers either to desktop colours (in the range 0-15), or to an RGB colour (represented by one word as 0xBBGGRR00)
Dialogue box A window which contains gadgets, and which is typically used to carry out a 'dialogue' with the user, ending in the user either cancelling the dialogue, or confirming that they want to apply the options indicated by the current dialogue state
Method One of the operations defined for a class (it can be thought of as a 'function')
Persistent dialogue box One which remains on the screen even when the menu tree is closed down. It must be explicitly removed by cancelling it, or by pressing Escape.
Resource file Described in Resource File Formats. It is a file containing a sequence of templates from which to build objects.
String A NUL-terminated sequence of ASCII characters.
Textual name (name) Can be formed of any sequence of alphanumeric characters and underscores ('_'). It must begin with an alphabetic character. Special names used by the Toolbox can begin with the underscore character ('_').

A name cannot be longer than 12 characters, including the NUL terminator character.

Transient dialogue box One which appears on the screen, and is removed when the current menu tree is closed down
User The human user of a client application
User Interface Object (object) A fundamental building block for windowed applications (e.g. a menu). All objects share a set of common methods which can be applied to them. An object consists of a fixed size header followed immediately in memory by a variable size body.
Word A 4-byte entity, aligned at a 4-byte address.
General notes
  • Where a buffer holds a string, this string will be NUL-terminated on exit from a SWI or when delivered in an event block. Strings which are given as input parameters to a SWI should be terminated by a control character (i.e. in the range 0-31 inclusive).
  • Where the size of a buffer is specified, this includes any terminating character. If the size of buffer supplied for a string is not large enough an error is not returned; instead the buffer is filled (including a terminating NUL), and the returned number of bytes 'written to the buffer' will be the size of buffer which would be required. Thus you may wish to check that the number of bytes written to the buffer is less than or equal to the supplied buffer size.
  • Note that all SWIs have a flags word in R0. All undefined bits in this flags word should be 0.
  • Unless otherwise stated, changes to objects which are visible on the screen are immediate.

Toolbox Application Model

The Toolbox is intended to provide a layer of abstraction between an application and the Wimp. In a manner analogous to the use of High Level Programming Languages, the Toolbox allows the programmer to think more in terms of the problem to be solved rather than the detailed mechanics of how to achieve a solution.

Traditional desktop application

In a traditional desktop application, the programmer writes code which interfaces directly to the Window Manager (Wimp) through Wimp SWIs. Such an application uses a 'Templates' file to define templates from which it can create windows at run-time, but must create other user-interface objects from within its code (e.g. menus). The events which are delivered to a Wimp application refer to low-level Wimp operations like mouse clicks:

TOOLINTRO-2.GIF

Wimp application model

Toolbox application

In a Toolbox desktop application, the programmer writes code which interfaces mainly to the Toolbox through Toolbox 'methods', only occasionally resorting to making low-level Wimp SWI calls. A Toolbox application uses a 'Resources' file to define templates from which it can create a large number of user-interface objects including windows, menus and iconbar icons. Events which are delivered to a Toolbox application are at a higher level of abstraction than Wimp events.

TOOLINTRO-3.GIF

Toolbox application model

Wimp events

The application will generally see all Wimp events, with the following exceptions:

ColourDbox will not see redraw events.

Where it has input focus you will not see keypress events.

Window object will not see Open Window Request or Close Window Request events if the window is marked as being auto-open or auto-close respectively.

Toolbox objects

An object is essentially one part of the user interface of a desktop application; for example, a window or a menu or an icon on the icon bar.

At run-time, each object is identified by an object id which is allocated when the object is created. An object id is a 32-bit integer, which should not be interpreted by the client application. An object id of 0 is used to indicate 'no object'.

Object classes

The type of an object is called its 'class', which identifies its attributes and the set of operations which can be performed on it at run-time.

It is possible to determine the class of an object at run-time, using SWI Toolbox_GetObjectClass.

The set of classes which are supported in this release of the Toolbox are:

Class name Meaning page
Colour Menu a menu for selecting a desktop colour Colour Menu class
Colour Dbox a dialogue box for selecting any colour Colour Dialogue box class
DCS a dialogue box for discard/cancel/save for unsaved data Discard/Cancel/Save Dialogue box class
File Info a dialogue box showing information on a given file File Info Dialogue box class
Font Dbox a dialogue box for selecting font characteristics Font Dialogue box class
Font Menu a menu for selecting a font Font Menu class
Iconbar Icon an icon on the left or right of the iconbar Iconbar icon class
Menu a Wimp menu Menu class
Print Dbox a dialogue box for selecting print options Print Dialogue box class
Prog Info a dialogue box for showing program information Prog Info Dialogue box class
Quit a dialogue box for handling quit with unsaved data Quit Dialogue box class
SaveAs a dialogue box for saving data by icon drag SaveAs Dialogue box class
Scale View a dialogue box for selecting a scale factor Scale Dialogue box class
Window a Wimp window Window class

The Toolbox is designed to be extensible, so this set of classes will be increased in future releases, and can also be increased by third party developers.

Object components

An object 'component' defines one of a set of distinct parts which make up an object; for example a menu entry is a component of a Menu object, and a gadget (see later) is a component of a Window object. A component is allocated a component id by which to identify it uniquely within its containing object; this component id is chosen by the client application when the component is created. For menus it can have a value in the range 0 to 0xFFFFFFFD, and for windows a value in the range 0 to 0x7FFFFF. All higher component ids are reserved for internal Toolbox use. A component id of 0xFFFFFFFF is used to indicate 'no component'.

Object Methods

At run-time, the client application manipulates its objects by using 'methods', which are in fact implemented via Toolbox SWIs. The Toolbox will dispatch these methods to the appropriate module which implements the class of object to which the method is being applied.

Creating an object

An object is created using SWI Toolbox_CreateObject (see SWI Toolbox_CreateObject (0x44EC0)). The client application supplies either the name of a template for the object, or the address of a block of memory containing such a template. If a name is provided, then the Toolbox will look for the template in the application's Resource file (see later). The client application will be passed back an object id for the newly-created object if successful.

When an object which has 'attached' objects is created, then the attached objects are also created. See Attached objects for a fuller description of this process.

Given its object id, it is possible to find out the name of the template used to create an object using SWI Toolbox_GetTemplateName.

Deleting an object

An object is deleted using SWI Toolbox_DeleteObject (see SWI Toolbox_DeleteObject (0x44EC1)). If the object is visible on the screen and it is deleted, then the Toolbox first hides the object.

When an object which has attached objects is deleted, then unless the 'non-recursive' bit is set in this SWI's flags word, all its attached objects are also deleted. See Attached objects for a fuller description of this process.

Showing an object

An object is shown on the screen using SWI Toolbox_ShowObject (see SWI Toolbox_ShowObject (0x44EC3)).

By setting bits in the SWI's flags word, the client may choose to show the object with either SWI Wimp_CreateMenu semantics or SWI Wimp_CreateSubMenu semantics. This is generally referred to as showing the object 'transiently', and can be used, for example, to show transient dialogue boxes. By default, an object is shown 'persistently', in other words it must be explicitly dismissed from the screen. Not all objects support both sets of semantics.

When an object is shown, the client application chooses where the object will appear on the screen by specifying one of three 'show types'.

  • A 'default' show type means that the object will be shown at a place determined by the module which implements the object's class. For example, a Menu object will be shown by default at a place 64 OS units to the left of the mouse pointer's position, to comply with the RISC OS 3 Style Guide.
  • A 'top left' show type means that the client application supplies the coordinates of the top lefthand corner of where the object should be shown.
  • A 'full specification' show type means that the client application supplies a buffer which contains all the information needed to position the object on the screen; the contents of this buffer is separately defined for each object class.
Hiding an object

An object is hidden using SWI Toolbox_HideObject (SWI Toolbox_HideObject (0x44EC4)). If the object was not visible on the screen, then this method has no effect.

Object-specific methods

Each object class provides a number of methods which are specific to that class (for example, a Window object's title can be set using the Window_SetTitle method). These methods are all accessed using SWI Toolbox_ObjectMiscOp (see SWI Toolbox_ObjectMiscOp (0x44EC6)), with an appropriate reason code.

Shared objects

It is often useful in an application for many objects to refer to one single instance of another object. A typical example is a multi-document editor, where a potentially large number of Windows all refer to a single shared Menu structure.

A shared object is specified as such in its template description. Whenever an attempt is made to create an object from such a template, the Toolbox first checks to see if there is already a copy of the object in existence, and in which case the id of this object is returned.

Reference counts are maintained for Shared objects. When the client tries to create such an object the reference count is incremented, and it is decremented when the client attempts to delete the object. The Shared object is only really deleted when its reference count reaches zero.

Shared objects can also be used effectively in conjunction with attached objects which are described on Attached objects.

Note: Sharedness is inherited by attached objects.

Client handles

Each object can have associated with it a one-word value called its client handle. The value of this handle is specified entirely by the client application and is not interpreted by the Toolbox. This mechanism is intended to allow a state to be associated with an object by the client application (e.g. in a multi-document editor a Window object's client handle might be a pointer to the data which must be displayed in the Window).

An object's Client Handle is set and read using SWIs Toolbox_SetClientHandle (see SWI Toolbox_SetClientHandle (0x44EC7)) and Toolbox_GetClientHandle (see SWI Toolbox_GetClientHandle (0x44EC8)) respectively.

Parent and ancestor objects

When an object is shown (using SWI Toolbox_ShowObject), there are two other objects which may be useful for the client application; these are the parent and ancestor objects.

Parent objects

The parent of an object is defined as the object (and optionally a component of that object) which caused the object to be shown. This is represented by the parent object id and parent component id. For example if a Window object has been displayed as the result of a Menu selection, then that Window object has a parent with an object id given by the Menu's id, and a parent component id given by the component id of the entry which was selected.

When SWI Toolbox_ShowObject is called explicitly by the client, the parent object and component ids must be specified. When this SWI is called on the client's behalf (for example, when a Menu is shown automatically for a Window), then the Toolbox fills this value in for the client.

Ancestor objects

It is always possible to trace the 'parentage' of an object by recursively requesting the Parent of that object, thus moving 'up' the invocation hierarchy of objects which have been displayed. Since this is a common operation, an object can be designated as a potential so-called 'Ancestor'. When an object is shown, it normally inherits the ancestor of its parent object; however, if the parent is marked as a potential ancestor, then the ancestor of the shown object is set to the id of the parent object.

Take the case where a multi-document editor has a document Window which has a Menu, which has a SaveAs dialogue box as a submenu. When an event occurs for the dialogue box, the client is probably most interested in getting the id of the document Window (to get at its data and save it). By designating the document Window as an ancestor, the client can ensure that its id is available when events occur on the SaveAs dialogue box.

TOOLINTRO-4.GIF

The processes in the above example are as follows:

  1. When the user presses Menu over the window, a Toolbox_ShowObject is raised on the Menu with the window as parent. As the window has been designated as ancestor, the Menu's ancestor will be the window.
  2. When the user moves the pointer over the Save submenu arrow, the Menu module will show the SaveAs dialogue with itself (i.e. the Menu) as the parent object, and the Save component as the parent component. The SaveAs dialogue will inherit the Menu's ancestor (in this case the window).
  3. Any event now raised on the SaveAs dialogue box will have the id block filled in with the Menu as the parent and the window as the ancestor.

The parent and ancestor of an object can be obtained by calling the SWIs Toolbox_GetParent and Toolbox_GetAncestor. Normally this will not be necessary, since (as shown in The id block) these values are made available on every return from Wimp_Poll.

Auto-create and Auto-show objects

In order to save on coding required, it is possible to get the Toolbox to create an object from its template as soon as the resource file containing the template is loaded by the application. This is achieved by setting the Auto-create bit in the object template's flags word (see the chapter entitled ResEd to see how to do this). When such an object is created, the Toolbox raises a Toolbox_ObjectAutoCreated event, to allow the application to ascertain and store the object id of the newly-created object; the name of the template used to create the object is reported in this event.

It is also possible to specify that as soon as an object is created, it should be 'shown' on the screen. This is achieved by setting the Auto-show bit in the object template's flags word (see the chapter entitled ResEd to see how to do this). When such an object is created, it is shown using SWI Toolbox_ShowObject in its default place, and with no parent given.

It is also possible for an object to be auto-show but not auto-create.

Attached objects

Certain objects allow other objects to be attached to them. When an object is created, all of its attached objects are also created, and a Toolbox_ObjectAutoCreated event is raised for each such attached object.

An example of an attached object is the object which will be shown when a user clicks the Select mouse button on an Iconbar Icon object. This attached object is created when the Iconbar Icon object is created.

Such side-effects of creating a given object are described in the Application Program Interface section in the chapter on each object class.

When an object with attached objects is deleted using SWI Toolbox_ObjectDelete, unless the non-recursive delete bit has been set, all attached objects are also deleted.

Attached objects can also usefully be combined with Shared objects. For example, if an application wishes the same Window to be displayed when the use clicks Select and Adjust on an Iconbar object, this can be achieved by specifying the same Window template name as the attached object to show for each of these mouse clicks, and marking the Window object as shared, so that the same object id is used for both cases.

It is important to note this side-effect of creating an object. For example, a Window object which has a complex menu tree attached to it, with many submenus and dialogue boxes, will have considerable side-effects when it is created.

Thus, in many cases, it is only necessary to create explicitly the 'topmost' object, and to allow the Toolbox to create the entire tree of attached objects.

Event handling

An important part of managing the user interface using the Toolbox is the concept of a Toolbox event.

A Toolbox event is a Wimp event (not a message) which is delivered to the client application with an event code of Wimp_ToolboxEvent (0x200). Each Toolbox event has its own event code, which is a 32-bit integer defined in a similar manner to Wimp message numbers.

Toolbox events are essentially an abstraction on Wimp events, and are generated by the Toolbox modules in response to user interaction with Toolbox objects, and also in response to client application operations. Toolbox events are also used to warn the client application that a particular action has been taken by the Toolbox.

For example, if a client application creates and shows a Print Dialogue Box, when the user clicks on the Print button, a Toolbox event will be delivered to the application indicating that a Print operation has been requested, and giving the number of pages to be printed, the scale factor to use during printing etc.

Note that underlying events will also be received by the client.

Toolbox event Codes

Event codes are allocated by Acorn. Events which are delivered by a Toolbox module will have codes which start at the SWI chunk base of the module.

The allocations are as follows; event codes are in the range 0 - 0x9FFFFs:

Event codes Use
0x00001 - 0X0FFFF Available for use by the client
0x10000 - 0x3FFFF Reserved for inter-application protocols
0x40000 - 0x9FFFF Reserved for Toolbox module events
Format of a Toolbox event

When a Toolbox event is delivered to an application, the Wimp Poll block has the following format:

Offset Contents
+ 0 size of Toolbox event block
(16 - 236 in a multiple of four bytes; i.e. words)
+ 4 unique reference number
+ 8 Toolbox event code
+ 12 flags
+ 16... Event-specific data

Unless otherwise stated flags will be zero.

The id block

Whenever the client application calls SWI Wimp_Poll, the Toolbox fills in a 6-word block of memory known as the id block, to indicate which object an event has occurred on. However, as Wimp messages do not typically occur on an object the id block will not be updated for a Wimp message.

This block is laid out as follows:

TOOLINTRO-5.GIF

When a Toolbox event occurs, the object id of the object on which this event occurred is placed in the 'self id' field of the id block, and the 'self component' field is also filled in if the event has occurred for a particular component of that object. For example, a mouse click on an action button gadget within a Window object will result in an ActionButton_Selected Toolbox event being raised, with the Window object's id in the self id field of the id block, and the component id of the action button in the self component field.

The 'parent id' and 'parent component' fields are filled in by the Toolbox using the values which were last passed to SWI Toolbox_ShowObject. The 'ancestor id' and 'ancestor component' fields are filled in accordingly (being the ancestor of the parent).

The Toolbox uses a value of 0 as an object id to indicate 'no object', and a value of -1 as a component id to indicate 'no component'.

When a Wimp event happens on an object, then the setting of the contents of the id block is object-specific, and is described in the object events section in the chapter on each object class.

The address of the 6-word block of client memory used as the application's id Block is passed to the Toolbox when the application registers itself using SWI Toolbox_Initialise (see SWI Toolbox_Initialise (0x44ECF)).

Note that Toolbox events are delivered to the object to which they are most appropriate, so for example a SaveAs object will receive SaveAs_DialogueCompleted events, whereas mouse clicks on a SaveAs object's underlying Window will be seen as being delivered to the Window object.

This behaviour can best be seen by taking some example Resource Files and dragging them to !ResTest, and monitoring the contents of the id Block as shown in !ResTest's log window, as events occur on the objects created from the Resource File.

Raising a Toolbox event

A Toolbox event is raised using SWI Toolbox_RaiseToolboxEvent. Normally a client application will not need to use this SWI directly; the client simply quotes the Toolbox event code (or number), and associates it with a particular user action in its description of an object in the resource file. For example, one of the attributes of a Menu object, is the Toolbox event which is raised when a particular Menu entry is selected by the user. The Toolbox will raise this Toolbox event on the application's behalf, whenever a Menu Selection event is returned for that menu entry.

Resource files

A resource file contains templates for the objects which a client application will create at run-time.

Loading resource files

An application can load a resource file at run-time using SWI Toolbox_LoadResources. This is done on the application's behalf for a file called 'res' when the application calls SWI Toolbox_Initialise as described in Task initialisation and run-time information. SWI Toolbox_LoadResources could then be called after task start-up to load any further Resource Files which it needs to use.

Resource file format

Resource files replace Wimp template files as the means to define templates for the user interface objects which an application will create at run-time. Whereas Wimp template files only allowed window descriptions to be given, a resource file will contain templates for any kind of Toolbox object.

A resource file consists of a fixed size header, followed by a contiguous sequence of object templates, where each template has a fixed size header, followed by an object body.

A resource file format is similar to a Drawfile, and can be represented diagrammatically as follows:

TOOLINTRO-6.GIF

Each template has a textual name which can have no more than 12 characters (including the terminating NUL). This name is used by the application when using a template in a call to SWI Toolbox_CreateObject.

If a resource file is loaded which has named templates whose names clash with earlier loaded templates, the latest loaded template will be used, and the earlier template will no longer be accessible.

For a full description of the resource file format see the chapter entitled Resource File Formats.

Task initialisation and run-time information

Before it can use the Toolbox, a client application must first call SWI Toolbox_Initialise to register itself as a Toolbox task. This has several side-effects:

  • If there is a file called res in the application's resource directory then it is loaded using SWI Toolbox_LoadResources; if such a file is not found, then the Toolbox tries a file called res<n>, where n is the currently configured country number, to allow for national variants.
  • The application directory is searched for a Sprites file called Sprites, Sprites22, Sprites23 or Sprites24 depending on the current screen mode. This file is then loaded into a block of memory and will be used as the application's sprite area.
  • The application directory is searched for a file called Messages, which is then loaded and registered with MessageTrans. If no such file is found, then a file called Message<n> is searched for, where n is the currently configured country number. The minimum requirement is that the Messages file should contain a message whose tag is _TaskName, giving the name of the application.
  • SWI Wimp_Initialise is then called on behalf of the application.

When a Toolbox task has been registered with the Toolbox, the client application can obtain the following information by calling SWI Toolbox_GetSysInfo:

  • the task's name (as given by the _TaskName message in the Messages file).
  • the 4-word message file descriptor returned when the task was initialised.
  • the application's directory name.
  • the application's Wimp task handle.
  • a pointer to the sprite area used to load the application's Sprites file.

Important: Since the Toolbox uses Wimp messages, a client aplication should not call SWI Wimp_AddMessages or SWI Wimp_RemoveMessages.

Message texts and nationalisation

When using the Toolbox, the writer of a client application should be aware of where textual messages are held, which will need translating if the client is to be 'nationalised' for a particular RISC OS territory.

All of the modules contained in the Toolbox have a default set of messages and object templates which they will use when displaying windows, reporting errors, displaying menus etc. These are registered with ResourceFS, and are looked up using MessageTrans. So in order to produce a nationalised Toolbox, these messages and templates will need replacing.

In a resource file, textual messages are held in Messages Tables, and objects created at run-time will contain pointers to these messages. These messages are the ones which have been specified by the client of the Toolbox to be used when creating objects, and will often consist of alternative text to use instead of the defaults provided by the Toolbox modules themselves. These messages are not tagged messages looked up using MessageTrans, but are actual strings.

The client application will also have a file called Messages in its application directory. This file is automatically loaded by the Toolbox when the client calls SWI Toolbox_Initialise. The Messages file will contain at least the name of the application (in a message whose tag is _TaskName), and any other messages which the application wishes to look up using MessageTrans at run-time. This will typically contain error messages, and ones which are not associated with objects. After calling SWI Toolbox_Initialise, the client will have a MessageTrans file descriptor to use when looking up these Messages.

This means that in order to nationalise an application, the writer will need to provide new Messages and new resource file messages (using Export messages in ResEd).

An Example object

Let us look at an example of a Toolbox object, to illustrate some of the features detailed in earlier sections.

An Iconbar Icon object is used to place an application icon sprite (and optionally some text) on the RISC OS icon bar. The template for such an object has the following fields, which can be set using !ResEd (the Resource Editor):

Field Meaning
position a negative integer giving the position of the Icon on the Iconbar (as specified in SWI Wimp_CreateIcon)
priority the priority of this Icon on the Iconbar (as specified in SWI Wimp_CreateIcon)
sprite name the name of the sprite to use for this Iconbar Icon
max sprite name the maximum length of sprite name to be used
text an optional string which will be used for a Text&Sprite Iconbar Icon (ie the text that will appear underneath the Icon on the Iconbar)
max text length if the Iconbar Icon has text, then this field gives the maximum length of a text string which will be used for it
menu the name of the template to use to create a Menu object for this Iconbar Icon
select event the Toolbox event code to be raised when the user clicks Select on the Iconbar Icon (if 0 then Iconbar_Clicked is raised)
adjust event the Toolbox event code to be raised when the user clicks Adjust on the Iconbar Icon (if 0 then Iconbar_Clicked is raised)
select show the name of a template to use to show an object when the user clicks Select on the Iconbar Icon
adjust show the name of a template to use to show an object when the user clicks Adjust on the Iconbar Icon
help message the message to respond to a help request with, instead of the default
max help the maximum length of help message to be used

The client application will create an Iconbar Icon object by calling SWI Toolbox_CreateObject, supplying a template which gives values for all of the above fields.

As a side-effect of this creation, the Iconbar Icon's attached objects are also created (if their templates have been provided) i.e. menu, select show and adjust show. The object ids of these attached objects are then held within the Toolbox internal data structure which represents the Iconbar Icon.

When the application calls SWI Toolbox_ShowObject on an Iconbar Icon, it will be shown in a Style Guide compliant place on the Iconbar. When SWI Toolbox_HideObject is called, the Icon will be removed from the Iconbar.

When a HelpRequest message is received, the supplied help message will automatically be returned to the sender of the message.

When the user clicks the Select or Adjust mouse buttons on the Iconbar Icon, then if the names of suitable object Templates have been supplied, these objects will be shown automatically by the Toolbox.

When the user clicks the Menu button on the Iconbar Icon, then if the name of a suitable Menu object Template has been supplied, it will be shown in a RISC OS 3 Style Guide compliant place (i.e. 96 OS units above the bottom of the screen).

There are a number of methods which have been defined for an Iconbar Icon to allow the client application to manipulate it at run-time; for example if it wishes to change the sprite used on the Iconbar for this Icon, then the Iconbar_SetSprite method will be used; if it wishes to provide a new Menu object which will be displayed when the Menu button is clicked on the Iconbar Icon, then the Iconbar_SetMenu method will be used.

Toolbox SWIs

Toolbox_CreateObject (SWI 0x44EC0)

On entry
R0 = flags (bit 0 set means create from memory)
R1 = pointer to name of template
(R1 = pointer to description block if bit 0 of flags word set)
On exit
R0 = id of created object
R1-R9 preserved
Use

This SWI creates an object either from a named template description which has been loaded from the resources file or from a template description block in memory. The exact format of the description block depends on the class of the object.

If the client application wishes to use the description block form of this SWI, then the block should begin with a standard object header, and the body of the object should be as specified in the Templates section of the chapter for that object. Any StringReferences, MsgReferences, and SpriteAreaReferences should hold 'real' pointers, and should not require relocation; also the 'body offset' field should contain a real pointer to the object body.

C veneer

extern _kernel_oserror *toolbox_create_object ( unsigned int flags,
                                                void *name_or_template,
                                                ObjectId *id
                                              );


Toolbox_DeleteObject (SWI 0x44EC1)

On entry
R0 = flags (bit 0 set means do not delete recursively)
R1 = object id
On exit
R1 - R9 preserved
Use

This SWI deletes a given object.

By default, any objects 'attached' to this object are also deleted. If bit 0 of the flags word is set, then this does not happen.

If it is a Shared object, this will result in its reference count being decremented, and it will only be really deleted when this reaches 0.

The Toolbox raises a Toolbox_ObjectDeleted event when the object's reference count reaches zero.

C veneer

extern _kernel_oserror *toolbox_delete_object ( unsigned int flags,
                                                ObjectId id
                                              ); 


Toolbox_ShowObject (SWI 0x44EC3)

On entry
R0 = flags
bit 0 set means show using the semantics of Wimp_CreateMenu
bit 1 set means show using the semantics of Wimp_CreateSubMenu
R1 = object id
R2 = show 'type':
Type value Meaning
0 show in the 'default' place. This has a different meaning depending on the type of object shown
1 R3 points to a buffer giving full details of how to show the object
2 R3 points to a 2-word buffer giving the screen coordinates of the top left corner of the object to be displayed
R3 = 0
or pointer to buffer giving object-specific data for showing this object
or pointer to 2-word buffer giving coordinates of top left corner of object
R4 = Parent object id
R5 = Parent component id
On exit
R1-R9 preserved
Use

This SWI shows the given object on the screen.

R2 gives the type of 'show' operation which is being performed. Not all types of show operation will be appropriate to all objects.

The buffer pointed at by R3 may hold data specific to this class of object, including information as to where the object should appear on the screen. The exact format of the buffer is specified separately for each object class. For example for a Window object, the buffer will hold a block of data which can be passed to SWI Wimp_OpenWindow.

Note: some objects support a bit in their flags word specifying that a warning should be raised before the object is shown. In this case, the SWI Toolbox_ShowObject will return, but the object will not yet be visible on the screen. The object will be visible (at the earliest) after the next call to Wimp_Poll after the warning is delivered.

C veneer

extern _kernel_oserror *toolbox_show_object ( unsigned int flags,
                                              ObjectId id,
                                              int show_type,
                                              void *type,
                                              ObjectId parent,
                                              ComponentId parent_component
                                            );


Toolbox_HideObject (SWI 0x44EC4)

On entry
R0 = flags
R1 = object id
On exit
R1-R9 preserved
Use

This SWI removes the given object from the screen, if it is currently being shown.

C veneer

extern _kernel_oserror *toolbox_hide_object ( unsigned int flags,
                                              ObjectId id
                                            );


Toolbox_GetObjectState (SWI 0x44EC5)

On entry
R0 = flags
R1 = object id
On exit
R0 = object state
Use

This SWI returns information regarding the current state of an object. The state is indicated by bits in the value returned in R0. Bits 0-7 refer to all objects and bits 8-31 are used to indicate object-specific state.

The generic state bits are:

Bit Meaning when set
0 object is currently showing
C veneer

extern _kernel_oserror *toolbox_get_object_state ( unsigned int flags,
                                                   ObjectId id,
                                                   unsigned int *state
                                                 );


Toolbox_ObjectMiscOp (SWI 0x44EC6)

On entry
R0 = flags
R1 = object id
R2 = method code
R3-R9 contain method-specific data.
On exit
R1-R9 preserved
Use

The exact operation of this SWI depends on the class of the object being manipulated, and on the reason code supplied.

Each object class implements a number of methods which are specific to that object (e.g. a Window class may implement a method for adding/removing keyboard short-cuts for a Window object).


Toolbox_SetClientHandle (SWI 0x44EC7)

On entry
R0 = flags
R1 = object id
R2 = client handle
On exit
R1-R9 preserved
Use

This SWI sets the value of the client handle for this object.

C veneer

extern _kernel_oserror *toolbox_set_client_handle ( unsigned int flags,
                                                    ObjectId id,
                                                    void *client_handle
                                                  );


Toolbox_GetClientHandle (SWI 0x44EC8)

On entry
R0 = flags
R1 = object id
On exit
R0 = client handle for this object
Use

This SWI returns the value of the client handle for this object.

C veneer

extern _kernel_oserror *toolbox_get_client_handle ( unsigned int flags,
                                                    ObjectId id,
                                                    void *client_handle
                                                  );


Toolbox_GetObjectClass (SWI 0x44EC9)

On entry
R0 = flags
R1 = object id
On exit
R0 = object class
Use

This SWI returns the class of the specified object. This is a 32-bit integer, which identifies a given class; allocation of class identifiers is handled by Acorn.

C veneer

extern _kernel_oserror *toolbox_get_object_class ( unsigned int flags,
                                                   ObjectId id,
                                                   ObjectClass *object_class
                                                 );


Toolbox_GetParent (SWI 0x44ECA)

On entry
R0 = flags
R1 = object id
On exit
R0 = Parent id
R1 = Parent component id
Use

This returns the value of the object id which was passed as the parent in a SWI Toolbox_ShowObject call (even if the parent has subsequently been deleted). The component id is for cases where the parent has a subcomponent like a Menu with a Menu entry. An object which has not yet been shown will have a parent object id of 0 and a component id of -1.

C veneer

extern _kernel_oserror *toolbox_get_parent ( unsigned int flags,
                                             ObjectId id,
                                             ObjectId *parent,
                                             ComponentId *parent_component
                                           );


Toolbox_GetAncestor (SWI 0x44ECB)

On entry
R0 = flags
R1 = object id
On exit
R0 = Ancestor id
R1 = Ancestor component id
Use

This returns the id of the Ancestor of the given object (and its component id, in the case of an ancestor which has subcomponents like a Menu with a Menu entry). Note that the Ancestor may have been deleted, since this object was shown. An object which has not yet been shown will have an ancestor object id of 0 and a component id of -1.

C veneer

extern _kernel_oserror *toolbox_get_ancestor ( unsigned int flags,
                                               ObjectId id,
                                               ObjectId *ancestor,
                                               ComponentId *ancestor_component
                                             );


Toolbox_GetTemplateName (SWI 0x44ECC)

On entry
R0 = flags
R1 = object id
R2 = pointer to buffer to hold template name
R3 = length of buffer
On exit
R3 = length of buffer required (if R2 was zero)
else buffer pointed at by R2 holds template name
R3 holds number of bytes written to buffer
Use

This SWI returns the name of the template used to create the object whose id is passed in R1.

C veneer

extern _kernel_oserror *toolbox_get_template_name ( unsigned int flags,
                                                    ObjectId id,
                                                    char *buffer,
                                                    int  buff_size,
                                                    int *nbytes
                                                  );


Toolbox_RaiseToolboxEvent (SWI 0x44ECD)

On entry
R0 = flags
R1 = object id
R2 = component id
R3 = pointer to Toolbox event block
On exit
R1-R9 preserved
Use

This SWI raises the given Toolbox event. The block pointed at by R3 should have the format described in Format of a Toolbox event. The Toolbox will put the unique reference number into the block before exit from this SWI. The object id and (optional) component id will be those filled in on return from Wimp_Poll; they refer to the object on which the Toolbox event is being raised; the Toolbox does not check the validity of these values.

C veneer

extern _kernel_oserror *toolbox_raise_toolbox_event ( unsigned int flags,
                                                      ObjectId id,
                                                      ComponentId component,
                                                      ToolboxEvent *event
                                                    );


Toolbox_GetSysInfo (SWI 0x44ECE)

On entry
R0 = flags
R0 Value Meaning
0 return task name
1 return 4-word messages file descriptor
2 return name of directory passed to Toolbox_Initialise
3 return task's Wimp task handle
4 return pointer to sprite area used
R1, R2 depends on entry value of R0 (see below)
On exit
R0  
On entry On exit
0 R2 holds size of buffer required (if R1 was 0)
else buffer pointed at by R1 holds task name
1 buffer pointed at by R1 contains a 4-word messages file descriptor
2 R2 holds size of buffer required (if R1 was 0)
else buffer pointed at by R1 holds directory name passed to Toolbox_Initialise
3 R0 contains task handle
4 R0 contains sprite area pointer
Use

This SWI is used to get information for the client application. The nature of the information required is indicated by R0.

C veneer

extern _kernel_oserror *toolbox_get_sys_info ( unsigned int reason_code,
                                               _kernel_swi_regs *regs
                                              );


Toolbox_Initialise (SWI 0x44ECF)

On entry
R0 = flags
R1 = last Wimp version number known to task * 100 (must be >=310)
R2 = pointer to list of Wimp message numbers which the client wishes to receive, terminated by a 0 word
If R2 points to just a 0 word, then all messages are delivered
If R2 = 0, then no messages are delivered (apart from the Quit message).
R3 = pointer to list of Toolbox event codes which the client wishes to receive, terminated by a 0 word
If R3 points to just a 0 word, then all Toolbox events are delivered
If R3 = 0, then no Toolbox events are delivered
R4 = pointer to Directory name in which to find resources
R5 = pointer to 4-word buffer to receive messages file descriptor
R6 = pointer to buffer to hold object ids on return from Wimp_Poll (the id block)
On exit
R0 = current Wimp version number * 100
R1 = Wimp task handle for this client
R2 = Pointer to Sprite area used
Buffer pointed to by R5 is filled in with a MessageTrans file descriptor for the messages file to be used
Use

This SWI is used by the client application before any other Toolbox SWIs.

First the Toolbox tries to load a file called res in the directory given by the string pointed to by R4; this is done by calling SWI Toolbox_LoadResources.

If a file called res is not found, then the Toolbox tries res<n> where n is the currently configured country number.

The application directory is searched for a Sprites file appropriate for the current mode (i.e. called Sprites, Sprites22, or Sprites23) and if such a file exists, a sprite area is allocated, and the file loaded into this area. A pointer to the area is returned in R2 (or 1 is returned if there was no such file found, and so the Wimp Sprite pool is used for Sprite references in the client application).

This SWI registers a file called 'Messages' found in the given directory with MessageTrans and passes back a 4-word MessageTrans file descriptor for use by the client. SWI Wimp_Initialise is called on the client's behalf, using the Wimp version number passed in R1, and the messages list pointed at by R2.

If a file called Messages is not found, then the Toolbox tries Message<n> where n is the currently configured country number.

The task name passed to SWI Wimp_Initialise must be given in the client's messages file; it should be an entry with tag '_TaskName'.

The buffer pointed at by R6 will be used on each call to Wimp_Poll to inform the client which object an event occurred on, and that object's parent and ancestor objects. On return from Wimp_Poll this block will be filled in as follows:

R6 + 0 ancestor object id
R6 + 4 ancestor component id
R6 + 8 parent object id
R6 + 12 parent component id
R6 + 16 'self' object id
R6 + 20 'self' component id
C veneer

extern _kernel_oserror *toolbox_initialise ( unsigned int flags,
                                             int wimp_version,
                                             int *wimp_messages,
                                             int *toolbox_events,
                                             char *directory,
                                             MessagesFD *mfd,
                                             IdBlock *idb,
                                             int *current_wimp_version,
                                             int *task,
                                             int *sprite_area
                                           );


Toolbox_LoadResources (SWI 0x44ED0)

On entry
R0 = flags
R1 = pointer to resource filename
On exit

R1 - R9 preserved

Use

This SWI loads the given resource file, and creates any objects which have the auto-create bit set. When such an object is created, the Toolbox raises a Toolbox_ObjectAutoCreated Toolbox event.

The filename of the resource file should be a full pathname.

After this SWI has been called, any templates from the resource file can be used to create objects, by quoting the template name.

C veneer

extern _kernel_oserror *toolbox_load_resources ( unsigned int flags,
                                                 char *resources
                                               );


Toolbox_TemplateLookUp (SWI 0x44EFB)

On entry
R0 = flags
R1 = pointer to template name (Ctrl terminated)
On exit
R0 = pointer to description block
Use

This SWI returns a pointer to a block suitable to pass to Toolbox_CreateObject or Window_ExtractGadget.

C veneer

extern _kernel_oserror *toolbox_template_lookup    ( unsigned int flags,
                                                     char *name,
                                                     void **id,
                                                    );


Toolbox events

Toolbox_Error (Event 0x44EC0)

Block
+ 8 0x44EC0
+ 16 error number
+ 20... error text
Use

All Toolbox SWIs may return direct errors, with the V bit set. If any part of the Toolbox detects an error, whilst it is not processing a SWI, it will raise a Toolbox_Error event which the client can report when he next calls Wimp_Poll.

For example, if a client uses Toolbox_ShowObject on an object which has the bit set to warn the client before the object is shown, the Toolbox will wait until the next call to Wimp_Poll before actually showing the object; if there is an error when it tries to do the show, then this will be reported through a Toolbox_Error event, since the SWI Toolbox_ShowObject will have already returned with no error indicated.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  int                errnum;
  char               errmess [256-20-sizeof(ToolboxEventHeader)
                             -sizeof(ObjectId)
                             -sizeof(ComponentId)
                             -sizeof(int)];
} ToolboxErrorEvent;


Toolbox_ObjectAutoCreated (Event 0x44EC1)

Block
+ 8 0x44EC1
+ 16... Name of template from which object was created
Use

This Toolbox event is raised by the Toolbox after it creates objects from templates which have their auto-create bit set, when the application's resource file is loaded. This allows the client application to get the ids of such objects for later use.

This event is also raised when an attached object is created as a side-effect of creating the object to which it is atached.

The client can establish the object's id by looking at the 'self' field of the id block which it passed to Toolbox_Initialise (see later).

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  char               template_name [256-20-sizeof(ToolboxEventHeader)-sizeof(ObjectId)-sizeof(ComponentId)];
} ToolboxObjectAutoCreatedEvent;


Toolbox_ObjectDeleted (Event 0x44EC2)

Block
+ 8 0x44EC2
Use

This Toolbox event is raised by the Toolbox after it deletes an object. It is useful when a 'recursive' delete is done, resulting in other objects being deleted.

The client can establish the object's id by looking at the 'self' field of the id block which it passed to Toolbox_Initialise.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
} ToolboxObjectDeletedEvent;

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015