Although the Wimp provides a method for a developer to create new windows using Wimp_CreateWindow, it also provides a much simpler and easier approach.
Template files are used to store the definitions of multiple windows and any font and icon data associated with each. By using a template editor application, a window can easily specify windows attributes such as size, position, title text and icons.
Although template editors make creating windows easier, they cannot handle windows which are child windows of other windows. Each window (parent and child) are deemed a separate window that needs to be defined individually. This is because window nesting information is not held within template files.
To use a template file within an application, the Wimp provides several calls.
SWI | Description |
---|---|
Wimp_OpenTemplate | Used to open a template file |
Wimp_LoadTemplate | Used to load a particular window within the template file |
Wimp_CloseTemplate | Used to close the template file |
Wimp_OpenWindow | Used to display a window |
Many of the templates used by RISC OS are stored within a specific location. The pathname of these files are: Resource:$.Resources.
It is possible to load these templates into a template editor application and use them as a foundation to build application specific template files.
It is also possible to over-ride the use of the system template files by setting App$Path
where App
is the name of the application. These variables contain comma-separated list of prefixes, in which the Wimp will search for the template file to open.
Template files use references to indirect data and to any fonts used. They must both be handled with care to ensure problems do not occur.
When a template file is created and then save, all references to the indirect data must point to a location within the file itself. Upon loading a template file, the application must set aside some memory to be used for window definitions along with any indirect data. The pointers to indirect data are then changed accordingly to this new temporary location in memory.
Note: If there is not enough memory to load a template, Wimp_LoadTemplate will return an error.
Template files references fonts by its name and sizes. For applications to know which font handle this is mapped to, the application must provide an array of data where each reference to a font used, is given a specific font handle. The Wimp provides several calls for managing fonts.
SWI | Description |
---|---|
Font_FindFont | Used to generate a font handle based on a fonts name and size (specified in the template file) |
Font_LoseFont | Used to remove the reference to a specific font handle |
Font_ReadDefn | Used to obtain new font information based using the font handle |
The array of data used for referencing fonts is 256 bytes in size, and must be used when calling Wimp_LoadTemplate. Each element within the 256 byte array should be initialized to zero in advance of the first call. Font handles are received each time the Wimp calls Font_FindFont. The font handles themselves are indices into the 256 bytes array.
Element i is increased each time font handle i is returned.
The end result is that when Wimp_LoadTemplate returns, the array contains a count of how many times each font handle was allocated. On closing a window or indeed quitting an application, it should scan the array and call Font_LoseFont the given number of times for non-zero entries.
Notes:
]