WindowManager Template Files

WindowManager

» Technical Details

» Template Files

Overview

Besides Wimp_CreateWindow, the Wimp also provides a much simpler and easier approach.

Template files are used to store the definitions of windows and any font or icon data associated with each. By using a template editor application, a user 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) is deemed separate and needs to be defined individually. This is because window nesting information is not held within template files.

Usage

To use a template file within an application, the Wimp provides several calls.

Operating System Templates

Many of the system-templates used by RISC OS are stored in the Resource Filing System. 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.

Issues

Template files use references to indirect data and to fonts. They must both be handled with care.

Indirect Data

When a template file is created and then saved, all references to the indirect data must point to a location within the file itself. Before loading a template file, the application must set aside memory to be used for window definitions and any indirect data. The pointers to indirect data are then changed to the new locations in memory.

Note: If there is not enough memory to load a template, Wimp_LoadTemplate will return an error.

Fonts

Template-files reference fonts by name and size. For applications to know which font handles these are 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.

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:

1. Applications can obtain the actual font handles by examining the returning window block from Wimp_LoadTemplate
2. Each window can use a different 256 byte data array, which may make handling of the fonts easier, however, it does increase the memory requirements slightly
3. Windows within a template file known not to have any references to specific fonts, can safely be loaded with no 256 byte data array. The Wimp will, however, report an error if any font references are found
4. If references to fonts are used, applications must also rescan its fonts upon receiving Message_ModeChange? by the Wimp. By Calling Font_ReadDefn for each relevant font handle, changing the correct x and y resolution and calling Font_FindFont again. The new font handle can be assigned to the applicable window by using Wimp_SetIconState

See also

• Wimp_CreateWindow
• Wimp_OpenWindow
• Wimp_OpenTemplate
• Wimp_LoadTemplate
• Wimp_CloseTemplate
• Wimp_SetIconState
• Font_FindFont
• Font_LoseFont
• Font_ReadDefn
• Message_ModeChange?