Steve Mumford starts to look at the initialisation of a WIMP application.

In this month's tutorial we start looking at the SWI calls needed to register a task with the WIMP. We concentrate on the WIMP's polling mechanism and the syntax associated with the various calls. Once we've got that under our belts, we can move on to their implementation.

Firstly, our prospective WIMP program must have been designed with a main loop at its core, so that when multi-tasking we can listen out for events we're interested in and call the appropriate functions from within that loop. Before we can actually start to multi-task, we have to inform the Task Manager that the code is both ready and suitable. On the same theme, we must remember to tell the Manager when the program is about to terminate.

So, how does the WIMP communicate with our prospective application? At the start of the main loop, we interrogate the WIMP to determine whether we have recived any events since the program was last active. For instance, there might be due to a mouse click or a pointer entering our window. If so, a data block is passed back to the code including all the relevant information, and we can then act on it by calling separate functions as appropriate.

When we've dealt with all the events that have arisen, we pass control back to the WIMP. If there have been no events relevant to our program, we can return immediately and so minimise on the system time taken up.

In brief then, we need three functions to far - an initialisation, a poll and a finalisation routine. These are supplied as Acorn SWIs with the names Wimp_Initialise, Wimp_Poll and Wimp_CloseDown. Now we know what the system calls are, here's the information we need to pass to each of them.

Wimp_Initialise is the SWI that registers our task with the WIMP, and it takes values in the registers from 0 to 3. In register 0, we must pass a number equal to the earliest WIMP we can use, multiplied by 100 to convert it into an integer. This is to prevent compatability problems when programs making use of the newer versions of RISC OS are loaded on older machines.

Next, we need to introduce ourselves as a program which can cooperate with the Desktop, and this is done by passing a particular value back in register 1 - 0x4B534154. This value might look a little cryptic at first, but it's the hexadecimal equivalent of the word 'TASK'.

The last vital piece of information to supply is an address in register 2 that points to a short string - to be used by the Task Manager in its application display. It's possible to pass another value in register 3 informing the WIMP as to which messages interest us - however, at this stage we're still interested in them all, so we can set register 3 to 0.

If all goes well, Wimp_Initialise should return two values - the current WIMP version number multiplied by 100 in register 0 and a unique task handle in register 1. This is just an individual numeric name that's been allocated to us for the duration of our execution.

To interrogate the WIMP about any events we've received, we need to call Wimp_Poll with the address of a prepared 256-byte data block passed in register 1.

Again, it's possible to make things more efficient by passing an event mask in register 0, but for now no mask is required. After thw SWI returns, register 0 contains the code of the event that's just occurred. We can then deal with that by examining the data placed in our poll block and calling other parts of our program as appropriate.

Finall, the Wimp_CloseDown call informs the WIMP that our program will be terminating - we simply pass our task handle in register 0 and the 'TASK' hexadecimal value mentioned earlier in register 1.

That's all I've got space for but for next time we'll start to fit these calls into the skeleton of a C program and take a quick look at how the various WIMP libraries available deal with the problem. See you soon.