Steve Mumford takes a closer look at events and messages.

Last month, we looked at the basic procedures behind initialising a WIMP application, using the SWI calls Wimp_Initialise, Wimp_Poll and Wimp_CloseDown. I was hoping to move on to look at how these would fit into a C application; however, due to a few technical difficulties, I've had to leave that for next month. Instead, I'll cover Wimp_Poll in a little more detail - due to space restrictions, I was unable to describe it fully last time.

WIMP applications communicate by two main methods - using events and messages. Events generally cover occurrences arising from user interaction such as requests for opening and closing windows, key presses, menu selections and mouse pointers moving in and out of windows.

There's also a null event that's returned to your application even though nothing has happened - however, in the interests of speed it's best to mask this one out so that the WIMP doesn't waste time communicating with your program when it's got nothing to say. This is done by setting bit 1 of the mask passed in R0 when Wimp_Poll is called.

Messages are a subset of events, and embrace a wider range of topics. As well as the rather complex subject of data transfer protocol, other messages that can be passed include Message_PreQuit, informing your application that the WIMP is shutting down and allowing it to ask if you wish to save your data.

Message_Quit on the other hand is an order to clean up and cease execution immediately; by this stage, you should have received a PreQuit message so there should be no reason for hanging on.

The interactive help system created by Acorn is implemented by use of messages - there's one that's passed to the appropriate application in order to determine whether is possesses any help text on the subject. If so, the program replies with another message, passing the help text back along with it.

How are these communication systems implemented? Last month, I mentioned that on calling Wimp_Poll, you needed to supply a 256-byte data block. On returning, the application is passed an event code that indicates its nature - this allows you to filter out particular events and pass them on to the appropriate handler functions within your code. Each handler then takes a look at the information within the data block and acts upon it accordingly.

Each event returns a different pattern of data; for instance, the Redraw_Window_Request event simply returns a window handle at an offset of 0 in the data block whereas Mouse_Click responds with the x and y coordinates of the mouse as well as its button state and identities of the window and icon it was over at the time. The data block for a message is similar to that of an event, but a few extra pieces of information are tacked on, including the task handle of the application that sent the message and a couple of references to trace its history.

There are in fact three types of message:

• User_Message
• User_Message_Recorded and
• User_Message_Acknowledge

The format of the data blocks is the same in each case, although they differ slightly in their function - the first doesn't require the application to reply to it so if the message is ignored, no further action is taken. If you receive a Recorded message and you fail to reply to it for some reason, the originator is returned a copy with its type set to User_Message_Acknowledge so that it knows the first transmission was unsuccessful.

Finally, a quick word about Wimp_PollIdle. If you've written an application that needs to make use of the null event code but you're performing a task that doesn't need to run at the full speed of the WIMP, it's possible to let your program snooze for a period. It's only bothered by the WIMP again after a specified time, or if a particular event requires its attention. If your application can make use of this - for instamce, you might have written a desktop clock which only needs to update once a second - it reduces the workload on the WIMP and avoids any other active programs from being slowed down unnecessarily.