Communicating with the user - Steve Mumford continues to build a simple database

Last month, I announced my intention to write a small database application to demonstrate some of the techniques behind WIMP coding. Before we go any further, you might like to take a look at the latest incarnation of the parachute jump logger on the cover disc. It's progressed nicely and although it's not fully functional yet (you can't save or load files), it demonstrates how easy it is to create the basics of a working database.

If you've been following the progress of the Acorn User WIMP library, you'll be able to understand the shell of the program without any trouble. As before, I initialised the task, loaded in the templates and provided a basic menu. The next stage was to design the window and note down the icon handles from the template editor - I defined these at the beginning og the sourcecode for ease of use. As well as the fields you can see in the window, there are three other elements in the jump_data structure; a unique jump number held in an integer, and two pointers to structures of the same type, allowing use to build a two-way linked list.

When the program starts, a jump_data structure is created and both next and previous pointers set to NULL, indicating that the list ends in both directions. The address of this structure is stored in a global pointer; in this way, we can hold onto the start of the list, and we know where to begin with any operations that need to work through the whole dataset. As records are added, the pointers within the first structure are altered to reflect the shape of the new data tree.

At the simplest level, a user must be able to move between records already in the database as well as add new ones, so I designed the window with the icons to perform these functions gathered at the top. Whenever the user clicks on these icons, our program is sent a Mouse_Click message, so it's a simple task to listen for that and move backwards or forwards in the database as appropriate - all we need to do is check the next or previous records of the current record. If they're not equal to NULL, it means that there's another record at the end of the pointer, and we can move along one step. Otherwise, the request is refused - however, if we're at the end of the list, the user can add another record there and so propagate the chain.

How do we input data? Well, the WIMP handles most of the hard work in this case; the user simply clicks in an icon and types away. The text is held along with the icon information, and we don't have to worry about a thing. This pleasant situation has to end eventualy - we need to read the user's entries and store them somewhere more permanent. I've handled this by waiting until the user clicks on the Add or Update button before interrogating the icons one by one and writing the information into the current structure. As a consequence, this means that any changes are lost if the user alters a record then moves away before clicking Update, but a check could be added to the click routines of the appropriate icons to prevent this.

This brings us to an important point; icons contain text and text alone, and you'll have to do some data conversion within the program to translate between the string passed back by the au_icon_get_text function and the type of variable you want to store. In this example, the altitude and delay are both stored internally as integers, so a quick call to the atoi() function in stdlib.h sorts this problem out. In case you're interested, the name atoi() in a truncation of the phrase ASCII to integer.

The two functions that allow you to read and write text icons are au_icon_get_text and au_icon_change_text respectively.

They both take three parameters; the first parameter in au_icon_get_text is a pointer to an array of characters to which the icon string is copied. Conversely, the first parameter of au_icon_change_text is the string that you wish to place in the icon. After that, the parameters of the commands are identical - the second parameter is the handle of the window that contains the icon, and the third is the icon handle itself - easily determined if you've used a template editor to create your windows. For instance:

au_icon_get_text(
    CURRENT_RECORD_POINTER->dropzone,
    win_data[0].win_handle,
    DROPZONE_ICON);
    
au_icon_text_change("Update", win_data[0].win_handle, UPDATE_ICON);

That's all I've got space for this month; next time around we'll deal with drag and drop loading and saving - bye for now.