Steve Mumford persuades his application to appear on the icon bar.

Last month, I tackled the job of coaxing our minimalist program to cooperate with the WIMP environment - we ended up with an application that loaded without crashing everything else and leaving when you asked it to. However, it couldn't really do much else and although we've won a technical victory, there's still a long way to go.

For this month's example, I've taken the existing code and added several new functions to enable it to reveal itself to the outside world. The application initialises itself in the same way as before, making use of the _kernel_swi() call suppled in the kernel.h library, but it continues by installing an icon on the icon bar and providing a function to deal with a new event.

As before, the greatest hurdle is arranging the data in a format the kernel calls will understand - if you own a set of Programmer's Reference Manuals, now would be a good time to dig them out. The data blocks required contain a mixture of words, bitfields and text and although they can be made neater by sine clever use of structures, the rather simplistic techniques I'm introducing here need separate routines to convert the data from one format to another.

Wimp_CreateIcon takes data in two registers - R1 points to a data block and the value in R0 is used in conjunction with the first word in that block to calculate where the icon should be placed on the bar. Values of R0 = 0 and R1 = -1 will make the application appear on the right hand side of the bar towards the middle. The next four words in the data block define a bounding box for the icon to indicate how much space it will take up once on the bar.

Following that are the icon flags that determine the behaviour of the icon, and finally we specify the name of the sprite we wish to use - this is normally resting in the WIMP sprite pool after having been loaded with an IconSprites command. The data conversion between the four-byte integers and the single bytes used in the array is performed by wtob() and is essentially the opposite of btow(), introduced last month.

After creating the icon we enter Wimp_Poll as normal, and in order to determine when the user clicks on it, we need to listen out for the Mouse_Click event. In more complex cases, the data block it returns would be interrogated for the mouse position and the handle of the icon it was over at the time, but all the program does here is to record the number of the mouse button that was pressed.

However, it's a good opportunity to investigate the method of reporting errors - one of the simpler methods of providing output to the user - and the mouseclick() function has been coded so that when the user clicks on the icon, an error box pops up. As well as revealing which mouse button had been pressed, it gives the user the choice of quitting the program.

The function report_error was written to make this task easier. It takes three parameters - the first is the appropriate error number, the second is the string that the error box is to display and the third contains the flags that control the way the box responds. In our example, the message is built up using the standard string functions, and setting the first two bits in the flag produces an error box with the familiar OK and Cancel buttons. A click on Cancel returns a value of 2 in this case, and the program continues. However, clicking on OK gives a value of 1, triggering the QUIT_FLAG variable to be set to 1 and forcing the program to terminate.

The example program can be found on the cover disc, and the source code, liberally scattered with comments, is included within the application. Due to the fact that it uses the standard kernel calls, it will compile happily using either Acorn's or Beebug's compilers. Next month, we'll progress onwards and upwards to look at windows and menus - see you then.