Okay, we've created a writable icon. It's on the window and you can type into it. What next though? The application does nothing with it as all text entry, deletions and movement is done by the WIMP. We need someway of the application doing something with the data.
In the example last time (!Part5e) we use a global variable (char *text[20] in main.c) which is passed into the icon creation routine as an indirected text buffer. We can just read the contents once return is pressed. Pretty simple, but not of much use in a real application.
It is possible there will be situations whereby you don't know the address of the buffer being used for the icon's contents. You may also wish to look at the icon's flags with a view to changing them (or even to actually change the icon itself). RISC OS provides us with two SWI calls; Wimp_GetIconState and Wimp_SetIconState.
Wimp_GetIconState
This returns the complete definition block for a given icon which has been updated to reflect the current state of the icon. There are two easy ways to call this SWI. Either create another instance of the normal icon structure, allocate enough memory to it (malloc) and pass that into the SWI. Failing that, create a memory area (using malloc again) of 10 * sizeof(int) and pass that into the SWI. The advantage of using the struct is that you know what you're dealing with as you are accessing memory via a name rather than an offset.
As you can see, the SWI provides a large amount of information. However, for us, we are interested with the text at offset + 28. This is a pointer to where the text is stored, not the text itself. It has to be handled differently.
In BASIC, you would have
icon_text$ = $(block%!28)
In C, this would translate to (assuming you have used the structure supplied with the C the WIMP series and using the names supplied in the source)
strcpy(icon_text,icons.redirected->indirected.pointer_text);
As you can see, it's quite simple to get the icon text contents. The line of code in C assumes that icon_text is large enough.
Wimp_SetIconState.
As I've said, you can also change the icon after it has been created. Just about every facet of the icon can be changed (the exception being the indirection which isn't actually part of the definition itself). However, in most circumstances, only the icon flags will normally be altered. This facility is provided via Wimp_SetIconState. Once called, the WIMP will perform the alterations without any application input.
The SWI is pretty self explanitory. The only aspect which requires explanation are the values at r1 + 8 and r1 + 12 as these two words tell the WIMP exactly what to do with the icon. Anything flag which is to remain unchanged must remain as zero in both words with any to be set need to be one in both words. To confuse matters here (sorry!) any flags which need to be cleared should be 1 in the clear word and 0 in the EOR.
Let's clarify that with some examples!
Suppose I have an icon which needs to be shaded (bit 22). This means bit 22 has to be 1 with all others set at zero. In code this would be
icon->eor_bit = 1 << 22; icon->clear_bit = 1 << 22; _swi(Wimp_SetIconBlock,_IN(1),icon);
If in the example from !Part5f we wanted to unset the bit 9 (text is right justified)...
icon->eor_bit = 0; icon->clear_bit = 1 << 9; _swi(Wimp_SetIconBlock,_IN(1),icon);
Making it all valid
Back in a prior C the WIMP, I briefly talked about validation. I'll expound upon it here. With a writable icon, you can tell the WIMP what characters the icon is allowed to take and what characters the WIMP must ignore for that icon. These ignored characters are passed to the application for disposal via the unprocessed keys inside of the Wimp_Poll routine. This is performed with a validation string which is passed into the icon creation routine when it is first set up. !Part5f demonstrates this in int main(void) inside main.c.
int main(void)
{
char *valid="A~0-9";
make_icon(whandle,8,
-400,384,48,0x700f13d,"",some_text,valid,21,4);
(I have removed some of the code for brevity)
In !Part5e, the validation was set as -1; in other words, everything was allowed. With this new validation string being passed over, we have told the WIMP that the icon should take all characters except for those after the tilde (~) - in this case, numbers from 0 to 9.
The syntax for validation strings is quite involved. The first character in the string indicates the type of command it is to follow. In !Part5f, the command is A. This means allow. If there is nothing after the A, it means allow everything. A tilde means that what follows is disallowed.
Other validation commands
D Display command (conceals text entries, used for passwords)
F Font command (font colours)
L Line command (split text over lines)
S Sprite name command
R allows 3D icon borders
K enables you to specify actions for certain keys
P specify sprite to be used for pointer over an icon.
C 24 bit colours (RISC OS 4 and up only)
If you change the line in main() which sets up the validation string to Aa-zA-Z;D- you can see the use of the validation string (this allows all letters and replaces the text entered with dashes). More details on validation strings can be found on the PRM CD from RISCOS Ltd or the StrongHelp WIMP manual..
That's enough for this time. I've deliberately left something out of the !Part5f code. Spot what it is and fix it. The software will run with out the fix though, so it may not be obvious. Answers next time.