Last time, I alluded to icons have something called a validation string. Basically, this tells the WIMP what to expect from an icon. For example, is we had a writable icon, by setting a validation string, we can tell the WIMP which characters the icon will accept and which the Wimp_Poll function will need to deal with via it's key function.
In !Part5f we can see this in practice. Looking at the c.main file, we see the following lines
char some_text[20];
int main(void)
{
char *valid="A~0-9";
make_icon(whandle,8,-400,384,48,0x700f13d,"",some_text,valid,21,4);
some_text is just a small text buffer for data to be stored in.
The line we are interested in here is char *valid = "A~0-9"; Explaining this is quite involved, even though it looks easy.
The first character A indicates the type of command to follow. In this case, it is a set of allowed characters. The tilde (~) tells the application that whatever follows is not allowed, in this case the number range 0-9. The full interpretation of this simple string means Allow all normal characters except for those in the number range 0 to 9. Suppose though we wanted all numbers, question marks and all letters to be uppercase. The validation string would become
char *valid = "A0-9A-Z?";
and if we only wanted letters (and nothing else)
char *valid = "AA-Za-z";
RISC OS 3 and above has 7 of these command type letters
D is used to conceal characters typed into an icon (most useful for the likes of passwords).
F supplies colours for anti-aliased fonts
L informs the WIMP that the text may cover a number of lines should it overflow the first.
S permits sprite names to be supplied for text and sprite icons.
R allows the use of the 3D borders.
A further example of a validation string is to use the D command type letter.
The first consideration is to know which characters to accept and which to ignore, followed by the character to replace the letter by (for instance, would you use a * or a -). We will accept all letters (upper or lower case) and replace the letter with a hash (I like to be different!). The validation would be
As with C, the ; denotes that a new command type letter is to be expected.
3D icons are very simple to implement via a validation string. Okay, it may not seem to be of much use, but if (say) part way through your program you have feel the need to change the border around an icon, the you can using the R command type letter. For instance, if we wanted to the writable icon in !Part5f to be a raised slab, we would pass in the validation string R1 (as well as everything else, remembering to separate the last command type letter with this one using a ;).
Buttons 5 and 6 highlight when the icon is in use. By default, this is orange (colour 14) but this can be changed by specifying a second parameter. For instance, if we wanted a light green highlight with action button 5, we would have R5,10 in the validation string.
IMPORTANT : if bit 2 of the icon flags is not set, the 3D icons will not work.
Okay, that's enough for this episode. Tune in next time when I'll back peddle a bit to explain some more about icons.