|
www.riscos.com Technical Support: |
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.
The Toolbox was designed with the following goals:
The Toolbox has the following characteristics:
Note: The Support for RISC OS 3.10 describes support for RISC OS 3.10 machines.
The instructions for installing Acorn C/C++ are in the Installing Acorn C/C++ of the Desktop Tools manual.
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. |
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.
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:
Wimp application model
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.
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. |
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'.
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.
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'.
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.
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.
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.
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'.
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.
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.
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.
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.
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.
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.
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.
The processes in the above example are as follows:
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.
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.
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.
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.
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 |
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.
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:
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.
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.
A resource file contains templates for the objects which a client application will create at run-time.
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 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:
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.
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:
When a Toolbox task has been registered with the Toolbox, the client application can obtain the following information by calling SWI Toolbox_GetSysInfo:
Important: Since the Toolbox uses Wimp messages, a client aplication should not call SWI Wimp_AddMessages or SWI Wimp_RemoveMessages.
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).
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.
| 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) |
| R0 | = | id of created object |
| R1-R9 preserved | ||
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.
extern _kernel_oserror *toolbox_create_object ( unsigned int flags,
void *name_or_template,
ObjectId *id
);
| R0 | = | flags (bit 0 set means do not delete recursively) |
| R1 | = | object id |
| R1 - R9 preserved |
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.
extern _kernel_oserror *toolbox_delete_object ( unsigned int flags,
ObjectId id
);
| 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 | ||
| R1-R9 preserved |
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.
extern _kernel_oserror *toolbox_show_object ( unsigned int flags,
ObjectId id,
int show_type,
void *type,
ObjectId parent,
ComponentId parent_component
);
| R0 | = | flags |
| R1 | = | object id |
| R0 | = | object state |
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 |
extern _kernel_oserror *toolbox_get_object_state ( unsigned int flags,
ObjectId id,
unsigned int *state
);
| R0 | = | flags |
| R1 | = | object id |
| R2 | = | method code |
| R3-R9 | contain method-specific data. | |
| R1-R9 preserved |
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).
| R0 | = | flags |
| R1 | = | object id |
| R2 | = | client handle |
| R1-R9 preserved |
This SWI sets the value of the client handle for this object.
extern _kernel_oserror *toolbox_set_client_handle ( unsigned int flags,
ObjectId id,
void *client_handle
);
| R0 | = | flags |
| R1 | = | object id |
| R0 | = | client handle for this object |
This SWI returns the value of the client handle for this object.
extern _kernel_oserror *toolbox_get_client_handle ( unsigned int flags,
ObjectId id,
void *client_handle
);
| R0 | = | flags |
| R1 | = | object id |
| R0 | = | object class |
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.
extern _kernel_oserror *toolbox_get_object_class ( unsigned int flags,
ObjectId id,
ObjectClass *object_class
);
| R0 | = | flags |
| R1 | = | object id |
| R0 | = | Parent id |
| R1 | = | Parent component id |
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.
extern _kernel_oserror *toolbox_get_parent ( unsigned int flags,
ObjectId id,
ObjectId *parent,
ComponentId *parent_component
);
| R0 | = | flags |
| R1 | = | object id |
| R0 | = | Ancestor id |
| R1 | = | Ancestor component id |
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.
extern _kernel_oserror *toolbox_get_ancestor ( unsigned int flags,
ObjectId id,
ObjectId *ancestor,
ComponentId *ancestor_component
);
| R0 | = | flags |
| R1 | = | object id |
| R2 | = | pointer to buffer to hold template name |
| R3 | = | length of buffer |
| 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 |
This SWI returns the name of the template used to create the object whose id is passed in R1.
extern _kernel_oserror *toolbox_get_template_name ( unsigned int flags,
ObjectId id,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | object id |
| R2 | = | component id |
| R3 | = | pointer to Toolbox event block |
| R1-R9 preserved |
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.
extern _kernel_oserror *toolbox_raise_toolbox_event ( unsigned int flags,
ObjectId id,
ComponentId component,
ToolboxEvent *event
);
| 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) | |||
| 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 | |
This SWI is used to get information for the client application. The nature of the information required is indicated by R0.
extern _kernel_oserror *toolbox_get_sys_info ( unsigned int reason_code,
_kernel_swi_regs *regs
);
| 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) |
| 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 | ||
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 |
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
);
| R0 | = | flags |
| R1 | = | pointer to resource filename |
R1 - R9 preserved
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.
extern _kernel_oserror *toolbox_load_resources ( unsigned int flags,
char *resources
);
| R0 | = | flags |
| R1 | = | pointer to template name (Ctrl terminated) |
| R0 | = | pointer to description block |
This SWI returns a pointer to a block suitable to pass to Toolbox_CreateObject or Window_ExtractGadget.
extern _kernel_oserror *toolbox_template_lookup ( unsigned int flags,
char *name,
void **id,
);
| + 8 | 0x44EC0 |
| + 16 | error number |
| + 20... | error text |
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.
typedef struct
{
ToolboxEventHeader hdr;
int errnum;
char errmess [256-20-sizeof(ToolboxEventHeader)
-sizeof(ObjectId)
-sizeof(ComponentId)
-sizeof(int)];
} ToolboxErrorEvent;
| + 8 | 0x44EC1 |
| + 16... | Name of template from which object was created |
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).
typedef struct
{
ToolboxEventHeader hdr;
char template_name [256-20-sizeof(ToolboxEventHeader)-sizeof(ObjectId)-sizeof(ComponentId)];
} ToolboxObjectAutoCreatedEvent;
| + 8 | 0x44EC2 |
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.
typedef struct
{
ToolboxEventHeader hdr;
} ToolboxObjectDeletedEvent;