Creating icons and modifying them - Steve Mumford takes control

In the process of designing the colour selection tools last month, we came across the use of slider bars and nudge buttons to provide the user with a more intuitive method for choosing appropriate values. This month, I'm looking in greater detail at creating, displaying and modifying icons using the standard WIMP system calls.

Until now, we've made use of template editors to set up the general layout of a window, and any icons we wished to include have been created at that stage. Although this makes the initial process of producing a window a lot easier, it's not possible to rely solely on this technique - there will be times when you need a little more flexibility.

The two main SWI functions that we'll be making use of are Wimp_CreateIcon and Wimp_DeleteIcon, but in order to be able to modify an icon's attributes, we need to be able to quiz the icon itself and store the returned details somewhere - that's where Wimp_GetIconState comes in.

In order to describe an icon's attributes fully, we need to store several parameters. Every icon has a window handle and icon handle, a four-word bounding box specifying its minimum and maximum x and y sizes, a word of flags that store the icon's behaviour and colour, and three words of data that can hold pointers to blocks of memory, perhaps holding an indirected string of text or a sprite, depending on the nature of the icon. In order to create an icon, these values are stored in the above sequence in a memory block whose address is stored in register R1 and Wimp_CreateIcon is called. The icon itself has now been defined but still needs to be displayed. Wimp_ForceRedraw is the simplest way of achieving this.

Instead of creating all your icons from scratch, the easiest way of learning how to control them is to do all the hard design using a template editor, make a note of the icon numbers then use Wimp_GetIconState to read those details into data structures created in your program. Once you have the information, changing and recreating the icon is a simple matter as properties such as the icon flags and data can just be copied from the original template.

Wimp_GetIconState takes the address of a memory block in register R1, and when the SWI is called this block should contain a window handle and an icon handle in the first two words of the block. The function fills the data block with eight words of data, starting at address R1+8 the first four words give the bounding box of the icon, the next contains the icon's flags, and the last three hold the three words of icon data mentioned above.

Getting back to the construction of the slider itself, it's composed of three discrete icons. I use a template editor named TemplEd, written by Dick Alstein, and this program has a stock of prefabricated window objects to ease the task, but it's a simple enough operation for those who wish to build their own. Icons are displayed on the screen in sequence, the ones with the lowest icons numbers being drawn first. This means that icons with higher icon numbers are displayed over the top of any already on the screen and it's this behaviour that we need to make use of.

The slider consists of a rectangular 'well' to enclose the area of the movable slider bar, a white background strips that runs almost the entire length of the well, and finally the movable bar itself, drawn as a filled rectangle directly over the top of the slider background. Changing the maximum x extent alters the amount of coverage the bar takes up, and all that remains to be done is to allow the user to control it. This can be done with nudge buttons or more dynamically by capturing appropriate drag messages.

There's a small catch: once an icon has been created, there's very little that can be altered dynamically, it's limited to changing the icon's various flags (using the command Wimp_SetIconState) or altering any text it might contain. Therefore, if we want to change some other feature of an icon, such as its position or size, we must delete and recreate the icon in the same location with modified parameters.

One last thing to note when creating, changing or deleting icons, the modifications aren't immediately reflected on screen. In order to update the display, you must call Wimp_ForceRedraw to mark an area of the screen as being invalid at this stage, the WIMP takes over and contacts your task through the usual channels with a message to redraw the screen. There's much more to learn about icon manipulation including making use of icon validation strings and the varied types of icon available, and we'll be covering these features as our label application develops.