Introduction

Do you enjoy writing programs for your RISC OS computer? Would you like to be able to write professional-looking software applications that will run under the desktop, using windows and menus, and operate at the same time as other multi-tasking software? This guide will show you how to get to grips with the Wimp system - Windows, Icons, Menus and Pointers.

This is not a tutorial on Basic programming from the beginning, nor does it aim to make you a complete expert on the Wimp system. It's for you if you like to experiment. Your own curiosity and inventiveness should help you along the road to expert ability, given the starting push that this guide can provide.

We will be learning how to use the operating system commands to create windows and menus and how to load and save data to and from your application. We will do everything in a step-by-step manner and, wherever possible, run our program to see the effect of the latest step.

A major step in our exercises will be the creation of a Wimp shell program. This will contain all the routines needed to create windows and menus and deal with mouse clicks. You can then add to it to make a working application of your own creation. It's actually quite a quick process to create a simple application for experimental purposes, and you may find that you end up writing a number of useful applications, all based on the same Wimp shell.

All the software in this guide will run on its own, without any additional library programs or interpreters, apart, of course, from the machine's operating system, RISC OS, and its built-in Basic interpreter.

You will not need to know anything about machine code or any other language to follow this guide; everything is in Basic. We're starting, though, on the assumption that you've had experience of writing Basic procedures, and know about passing variables to them, handling strings, FOR ... NEXT loops and similar operations. It will also help if you know something about binary and hexadecimal numbers. If you are new to programming in general, you can learn about Basic in First Steps in Programming RISC OS Computers.

By the way, all the software in this guide should run on any RISC OS computer, from the original Acorn Archimedes A300 and A400 series onwards.

During the later stages, we'll be exploring window templates. This is a very convenient way of designing windows and saving them in a special file, using a window template editor. We'll be using a utility called WinEd for this purpose, though there are various alternative template editors.

Getting to Grips With SWIs

The Programmer's Reference Manual is no longer in print and may be difficult to find in paper format. However, an updated electronic version can be obtained on an inexpensive CD from RISCOS Ltd, and the very latest edition is included in the Acorn C/C++ Development Suite, published by Castle Technology Ltd.

It is not the intention of this guide to try to replace the Programmer's Reference Manual. For this reason, there is no formal list of SWIs and their parameters. Instead, each one is explained when it is used and every reference to it is listed in the index.

Each SWI has a number, and also a name, which is in two parts. The first refers to the section of the operating system that handles the call - 'OS' for the kernel or main part, 'Wimp' for the window manager etc. The second part is the name of the call itself. The two parts are separated by an underline symbol (_).

It is very important to get this name exactly right, or the operating system will not recognise it. All the words in the second part of the name are strung together, and each begins with a capital letter, as does the word in the first part. All the rest of the name is in lower case, except where part of the name comprises initials, as in 'OS' or 'CLI', which stand for 'Operating System' and 'Command Line Interpreter'. An example is 'Wimp_GetPointerInfo'.

The machine's processor (ARM, StrongARM or XScale) has 16 registers, each of which can hold 32 bits, or four bytes. These are known as R0 to R15. We will never be concerned with more than about the first six, but we do have to know how to pass numbers to and from them, so let's try a little exercise.

Start up Basic in its immediate mode, which can be done either at the command line (press F12 to get there) or in a task window (press Ctrl-F12), by typing:

*Basic

Now type:

SYS "OS_WriteC",65

The SYS command calls the SWI named 'OS_WriteC', which is the equivalent of the Basic 'VDU' command. Before doing so, it puts the number after the comma, 65, into register R0. OS_WriteC is a system call that takes the number in R0 and sends it to the screen. When you press Return, you should see the letter 'A' appear on the screen, because 65 is the ASCII code for 'A'. If you had an error message saying 'SWI name not known', it means that you mistyped the name.

Now try typing:

SYS "OS_ReadC" TO a%

When you press Return, the Basic prompt does not reappear until you press another key. If you now type:

PRINT CHR$a%

you will see the character whose key you pressed.

As you may have guessed, 'OS_ReadC' is the equivalent of the Basic GET command. It waits for a key to be pressed, then puts the ASCII code for the key into R0. The SYS command takes the number from R0 and puts it into Basic variable a%.

We might have a command such as:

SYS "Xxx_XxxxXxxx",x% y%,z% TO a%,b%,c%

This takes the variables x%, y% and z% and puts them into registers R0, R1 and R2 respectively. It then calls the SWI and, on return, puts the numbers from R0, R1 and R2 into the variables that come after the TO keyword, in this case a%, b% and c%.

A typical command used by the Wimp is:

SYS "Wimp_CreateIcon",,b% TO i%

Because there are two commas after the SWI name, this instruction takes the value of b% and puts it into R1 (it also puts a zero in R0, but that does not matter). On return from the SWI it sets variable i% to the number in R0.

To avoid repetition, we will refer to a command of this sort as 'a call to Wimp_CreateIcon'.

With all that in mind, we are now ready to find out how to create real, multi-tasking applications, so let's proceed to Section 1...