www.riscos.com Technical Support: Programmer's Reference Manual

The Toolbox modules

Introduction and Overview

The Acorn C/C++ product introduced the RISC OS Toolbox, which makes it much easier to write consistent, high-quality desktop applications whose user interface complies with the RISC OS 3 Style Guide. The key parts of the Toolbox are:

• A number of object modules, each of which provides code that handles an object (ie a part of the user interface of a desktop application such as a window, or a menu, or an icon on the icon bar) and the components that make up that object (such as menu entries, buttons and sliders)
• ResEdit, which is an interactive editor for designing the different objects in the application's user interface, and saving them to a resource file
• ResTest, which is an application to check the appearance and behaviour of all the objects in a resource file
• The Toolbox module itself, which is at the core of the system; it provides a layer of abstraction between an application and the Wimp, loads objects from resource files, and calls the code in object modules

• The TinyStubs module, which provides TinySupport_... SWIs for internal use within the Toolbox.

Advantages of the Toolbox

Using the Toolbox has a number of advantages. In particular:

• The object modules provide much of the code needed to handle your user interface, so you don't need to write the code yourself
• ResEdit and ResTest provide a much quicker and easier way of designing user interfaces than the past method, which involved designing window templates and creating other components of your user interface (such as menus) in your application's code.

• The Toolbox modules support multiple applications, so their code can be shared, avoiding unnecessary duplication of code, and hence cutting down on memory usage.

Toolbox modules in RISC OS

To cut down still further on the memory requirement of applications written to use the Toolbox, the RISC OS 3.6 ROM contains all its modules (ie the Toolbox module itself, the TinyStubs module, and each of the object modules). Toolbox applications therefore don't need to load the modules into RAM, and much of their user interface is implemented by shared code that runs from ROM. The object modules supplied are:

Module	Provides
ColourMenu	a menu for selecting a desktop colour
ColourDbox	a dialogue box for selecting any colour
DCS	a dialogue box for discard/cancel/save for unsaved data, and a dialogue box for handling quit with unsaved data
FileInfo	a dialogue box showing information on a given file
FontDbox	a dialogue box for selecting font characteristics
FontMenu	a menu for selecting a font
Iconbar	an icon on the left or right of the iconbar
Menu	a Wimp menu
PrintDbox	a dialogue box for selecting print options
ProgInfo	a dialogue box for showing program information
SaveAs	a dialogue box for saving data by icon drag
Scale	a dialogue box for selecting a scale factor
Window	a Wimp window

Toolbox documentation

The Toolbox is documented in the User Interface Toolbox guide, supplied with Acorn C/C++.

Writing applications to use the Toolbox

To write applications that use the Toolbox, you will need to purchase Acorn C/C++, so that you have:

• documentation
• the means to create resource files (ie ResEdit)
• a binary distribution licence for the Toolbox modules so you can supply them with your application, and it can hence run on RISC OS 3.1 and 3.5.

Applications communicate with the Toolbox using standard RISC OS mechanisms such as SWIs (known as Toolbox methods) and Wimp events (known as Toolbox events). You therefore don't have to write Toolbox applications using the languages supplied with Acorn C/C++ (ie C, C++, and ARM assembler); you can use other languages such as BASIC.