C for Yourself - part 58

Steve Mumford looks at validation strings in more detail

Having looked at the principles used when creating slider bars last time around, in this month's column I'll be explaining the properties an icon may have in more detail - including the use of icon validation strings, which can come in handy for improving the appearance of your application or using features that the WIMP implements automatically, such as password concealment.

Icon validation strings are arrangements of characters that are passed, almost as an extra parameter, to the icon generation function. These strings of characters can encode a variety of different commands which range in function from changing the appearance of the icon to altering the way it behaves. The beauty is that some of these features can be used to increase the functionality of an application without having to write pages of extra code; they also help standardise the interface presented to the user between different applications, something conspicuously lacking in certain other operating systems.

Validation strings aren't automatically used, and won't even be considered if the icon's properties don't indicate that one is required. One word of memory is used to store the flags that govern the properties of an icon, and when set, bits 0, 1 and 8 indicate to the WIMP that the icon contains text, a sprite, or has indirected data. Indirected icons store extra pointers in their three-word data block so that the space restrictions of the usual icon definition can be worked around.

Depending on the combination of the Text, Sprite and Indirected flags, the three icon data words change their meaning, and validation strings are only appropriate for indirected text-only or indirected text-and- sprite icons. In these cases, the first word of the data block holds a pointer to a suitable text buffer, the second word points to a validation string and the third gives the length of the text buffer provided.

The most common use of a validation string is probably in the construction of a combination text/sprite icon - placed on the iconbar, for instance. In this case, the validation string is used to contain the name of the desired sprite, and is given in the form 'Smysprite', where the first letter S indicates to the WIMP that the following characters form an appropriate sprite name. It's also possible to supply a second sprite name to be used when the icon is highlighted - this is done by including the second name after the first, with a comma between them. This is an example of a validation string command, and several of these can be included in one string by separating them with a semicolon.

When requesting input from the user via a writable icon, it's particularly useful to be able to limit the range of characters that the icon will accept, so that the programmer doesn't have to write checking routines to analyse the string and filter out any unsuitable input. This might be used to make sure the user enters a valid number or filename, for instance. The Allow command lets the WIMP automate this task; all the programmer has to do is decide which characters are to be inserted into the writable icon - the rest are sent to the task via a Key_Pressed event, so that they can still be dealt with.

To specify a set of characters to allow, you can either include them individually, or as a group. For instance, Aaeiou would produce an icon that would only accept the five vowels as input, whereas Aa-zA-Z would accept lower or upper case alphabetic characters. When it's not convenient to explicitly include every character you want to accept, it's possible to exclude individual characters and groups, too - this is done by preceding the group or character with the tilde character ~. Aa-z~aeiou would include all lower case letters except the five vowels, and A~0-9 would allow anything to be typed as long as it wasn't a digit. Four special characters are used in validation strings - these are ~ - ; and \. We've just met the first two; the semicolon is used to separate validation commands and the backslash allows you to refer to the special characters within the allow command - Aa-z\;\- would include all lower case letters as well as the semicolon and hyphen.

There are several other useful validation commands; Display masks the contents of a text icon with an appropriate number of. symbols, so the command D* would display a text icon containing the word 'hidden' with '******'. The Keys command is also rather handy as it can be used to add extra editing functionality to an icon set free-of-charge - if you want the user to be able to navigate between several writable text icons using the arrow or tab keys, you can use the validation commands KA or KT.

That's all we have time for this month - I'll see you soon.

Source: Acorn User - 204 - February 1999
Publication: Acorn User
Contributor: Steve Mumford