Wimp_LoadTemplate (load syntax)
Programmer's Reference Manuals
» Part 7 - The Desktop
» The Window Manager
» SWI Calls
» Wimp_LoadTemplate
» Wimp_LoadTemplate (load syntax)
Wimp_LoadTemplate (load syntax)
(SWI &400DB)
| Entry | |
|---|---|
| R1 | Pointer to buffer for template |
| R2 | Pointer to workspace for indirected data |
| R3 | Pointer to end of indirect data workspace +1 byte |
| R4 | Pointer to 256 byte array for font reference, or –1 for no fonts |
| R5 | Pointer to (wildcard) name to match (must be 12 bytes word-aligned) |
| R6 | Position to search from, or 0 for the first call |
| Exit | |
|---|---|
| R0 | Corrupt |
| R2 | Pointer to remaining workspace |
| R3 | Reserved |
| R4 | Reserved |
| R5 | Template name returned in block |
| R6 | Position of next entry, or 0 if template not found |
Use
This purpose of this call is to load a window template into memory so it can then be used.
Notes
This call should only be used after the template file has been opened using Wimp_OpenTemplate. The specific template window can then be loaded using this call.
Indirect data is then copied by the Wimp to the workspace as referenced by R2. The font reference array is also updated if fonts are used by the template window.
It is possible to load a template window by searching using a wildcarded name. e.g. ‘dialog*’ by setting R6 to 0. As there may be more than one match, R6 upon exit will point to the next match, or 0 if it is last template found. As R5 is overwritten, the task must re-initialise the wildcard string every time it called.
When loading a template file, all references to any fonts are updated to current font handles. The Wimp calls Font_FindFont and replaces the original font numbers with the new font handle. It then increments the entry for that handle in the reference array. Please note, that this array should be initialized to zero before the first call to Wimp_LoadTemplate.
When a window is deleted, references to any fonts with handles in the range of 1 to 255 should be removed. This is achieved by calling Font_LoseFont the number of times given by that font’s reference count in the array. An alternative method is to use a single reference array for all the windows, and only call Font_LoseFont the required number of times for each handle when the task terminates.
No errors are generated if a template could not be found. In this instance, R6 is simply set to 0.
When loading templates, the call checks that the available indirect workspace is large enough. If it is not, an error will be returned.
If an error does occur when trying to load a template, then it advisable to call Wimp_CloseTemplate and close the template file.
As pointers to memory blocks are used to return the template data, if is vital that enough memory is set aside. To calculate the size of buffer required to load a template file, the request size syntax form of this call should be used.