Beginner's Guide to WIMP Programming
Everything you need to know to start writing your own applications.
Chapter 1: Multi-tasking Programs
An important aspect of Wimp-based applications is that they are multi-tasking, which means that they can run at the same time as other programs. At its simplest, this means that you can load and use a program without having to shut down one which is already running. It also makes it easy to transfer data between programs and to use several programs at the same time.
A One-line Multi-tasking ProgramIt's actually very easy to write a simple and very short multi-tasking program, even one with only one line of Basic. You can find one in the Apps directory which accompanies this guide, with the filename OneLine. If you'd like to try typing it in yourself, it looks like this:
Note that this should all be typed in as one line. If you press Return after "SYS", the program won't work.
You won't be able to run it from the command line. Typing it in inside a task window would prove nothing because programs in a task window multi-task anyway. You'll have to type it into your text editor, save it as a Basic file and run it by double-clicking on the file icon.
Before we run it, let's examine how it works. The easiest way to do this is by splitting it up into separate lines, so that it looks like this:
10 DIM b% 255 20 SYS "Wimp_Initialise",200,&4B534154,"MyApp" 30 t%=TIME 40 REPEAT 50 SYS "Wimp_Poll",,b% 60 WHILE TIME>t%+100 70 VDU 7 80 t%+=100 90 ENDWHILE 100 UNTIL FALSE
The line numbers have been shown purely to make it easier to explain how the program works. We'll be doing this with all the listings in this guide. If you type in your own listings and find that your line numbering is a little different from the numbering in the guide, it could be because you tried your own modification to the program and left an extra line in; alternatively, it might be because you left a line out! Depending on the editor that you use to type in programs, you may even find that your own lines are numbered consecutively in 1s rather than in 10s (assuming the numbers are even displayed by default). Line numbers are present in this guide so that the text can refer to specific lines in the listings, but you don't actually need to type in the line numbers yourself.
Telling RISC OS About Our ProgramThe first instruction, in line 10, sets up a block of memory, 256 bytes in size, for SWI Wimp_Poll to use later. Variable b% contains the address of the start of the block. We'll find out more about this later.
The operating system has to be told to run our program at the same time as other multi-tasking programs. This is the job of the instruction in line 20; it's also our first use of a software interrupt for real. The SWI "Wimp_Initialise" adds our program to a list of those which the machine runs in turn. Before we call it, though, we have to pass certain numbers to various registers.
The first of these, in R0, is 200. This is the number of the earliest version of RISC OS which the program will run under, multiplied by 100. As there is nothing particularly advanced in this program, it could be run on the earliest version of RISC OS that was produced, which was v2.00 (in an Acorn Archimedes, from 1988 onwards); hence the number 200.
Next, in R1, we put the four-byte hexadecimal number &4B534154, which is the ASCII codes for the word "TASK" (reading from right to left). This is a kind of "magic number" which tells the machine that the program was written to run under RISC OS, rather than the earlier "Arthur" operating system, fitted to the first Archimedes computers in 1987.
Note, by the way, that a multi-byte hexadecimal number is stored in memory with the least significant byte having the lowest address and the most significant byte having the highest, but we write it high byte first, low byte last. The lowest byte, &54, is the code for 'T', the highest byte, &4B, the code for 'K'.
The string in R2 is the name of the application for use in the Task display window. Obviously, the register cannot store a whole string; in this case the number which the SYS command puts into the register is the address where Basic has stored the string.
These numbers, in their respective registers, tell the operating system what we're doing when we call Wimp_Initialise.
Round and Round the PollLines 40 to 100 form a polling loop, which is the heart of all multi-tasking programs running under RISC OS. It is very important to understand this. Each time the program goes round the loop, it calls Wimp_Poll. As far as our program is concerned, control comes straight back again, but, in fact, the system has returned control to other applications running in the meantime. Each of these has done whatever it has had to do, then called Wimp_Poll again, which has caused control to be passed on to the next task. By the time control returns to us, the Wimp may have called all the other tasks that are running, but our program is blissfully unaware of this.
When we call Wimp_Poll, we pass the address of a block of memory that we set up earlier in R1. This is a very common practice in Wimp SWIs.
The WHILE ... ENDWHILE structure between lines 60 and 90 is used here because, you will remember, this program started out as a one-line program. Normally, we would use an IF ... THEN ... ENDIF structure, but that would have presented difficulties in a one-line program.
What actually happens is that we set variable t% to the current TIME count before we start running the polling loop. Each time we go round the loop, we check the current value of TIME to see if has exceeded its old value, t%, by 100. Because TIME is a count of centiseconds, this happens after one second. If this has occurred, we increment t% to make it the new value of TIME, then make the machine beep with a VDU 7 command. In short, this program produces a beep once a second.
If you now run the file, you'll find that the computer will start beeping once a second. It's also possible, though, to do word-processing and run other programs at the same time. These programs are running and behaving normally but our program is also running, making the machine beep once a second. In other words, all these programs, including our own, are multi-tasking.
If you open the Tasks display window, you will see the program listed as "MyApp", the result of the string which was passed in R2 in line 20. You'll also notice that the program has a surprisingly large amount of memory allocated to it, probably 640K. We'll find out how to limit this to a more reasonable figure in the next section.
What you won't be able to do, though, is shut down the program. With properly-written applications, you can click the Menu button over their name in the Task display window and go to a sub-menu with a Quit option. This option won't work with our program because there's no provision written into it to make it shut down. Lines 40 to 100 keep REPEATing the loop until FALSE changes to TRUE and nothing's going to make that happen.
Even if you shut down the machine, you'll find that it will still beep until you reboot it or, of course, switch it off. If you have RISC OS 3.5 or later, you can press Alt-Break and look for the message, "Press Stop to terminate MyApp", but otherwise, you will have to reboot.
So much for our one-line program. Now to make a start on writing an application properly...