Steve Mumford looks at menu creation in this month's tutorial.

To recap - we've managed to create an application that installs itself on the desktop and pops up a window that displays the name of the task that's initialised itself most recently. Last month, I left the program with a rather ugly quit mechanism. This time round, I'll look at the functions necessary for menu creation and subsequent selection of entries, so that we can build an icon bar menu with a quit option.

There are three phases to the installation of a menu system - the first is to listen out for a Mouse_Click event, which indicates that the user has 'prodded' our application. If the position of the click and the button used are appropriate for a menu - in our case, a hit on the icon bar icon with the Menu button - a routine is called that creates the menu data block in memory and passes it to the WIMP for display. At that point, the program returns to the polling loop and thinks no more about the matter until it receives a Menu_Selection event (event code 9) which signifies that the user has clicked on an item in a menu.

The selection is returned as a series of numbers indicating which item in the menu tree was clicked on; if this is a little too abstract, there's the Wimp_DecodeMenu SWI call which converts that data into a textual representation. Once that's over, it's just a matter of performing the appropriate actions and continuing with the program - the menu is cleared away by the WIMP once it's no longet needed.

In order to create a menu, various pieces of information are required - a glimpse of the reference manuals might be handy at this point, but to give you an idea of what to expect, here's a rundown of the data block. The first 12 bytes contain the menu title string, terminated with a control character. The next four hold the colours used for the menu, describing the foreground and the background for the title bar and the work area in that order. The last three words of the header contain the width and the height of the menu items, as well as the gap between them.

From that point on, the rest of the data defines the entries that will make up the menu - these behave very much like text icons and share many of their attributes. Each item takes 24 bytes, and the first four of those bytes are used to hold a series of flags that govern its behaviour. The important ones are bits 0 and 1, which allow you to tick items and separate them with dotted lines, and bit 7 which marks an entry as being the last one in that particular menu.

The data word after that can contain a handle to a submenu or a window that will be displayed if necessary, or -1 if it's just a plain item with no branches attached to it. The next four bytes hold a set of menu icon flags - these are similar to those for normal icons, although some bits are ignored due to the specialised nature of menus. It's important to set the foreground and background colours of the icon by using bits 24-27 and 28-31 respectively, as well as determining the type of the icon by setting the text, sprite and indirected flags (bits 0, 1 and 8) respectively.

Finally, the last 12 bytes contain the actual text data for the entry, whether it's the indirection information or the text itself. Once the data block has been prepared, Wimp_CreateMenu is called with the address of the block in R1 and a pair of coordinates in R2 and R3 to specify where the menu is to be displayed - there are normally gleaned from the pointer position.

At the moment, the menus are hard-coded into the program, and changing information within them or building complex menu structures would be prohibitively difficult - altering the icon flags or the colour of the menu means recalculating the appropriate integer by hand, which isn't efficient.

Next month's task, therefore, is to write an on-the-spot menu builder that takes the data in a user-friendly format and returns a ready-to-use menu.