Overview
Wimp Template files and Toolbox Resource files are the main binary resource formats used for desktop user interfaces. This appendix describes the Wimp Template binary file structure at a level useful for inspection, conversion, and build tooling.
The PRM describes a template file as a sequence of window blocks, each preceded by a name and length. The Wimp loads entries from this file through Wimp_OpenTemplate and Wimp_LoadTemplate, copying the fixed window and icon definitions first and then fixing up any indirected text or sprite data into a separate workspace area.
Template file structure
Overall file structure
At the highest level, a template file contains:
- a header that identifies the file as a template file;
- an index of named template entries;
- a terminator for that index;
- the template entry data blocks themselves;
- optional font data used by the templates.
The exact window and icon layouts are the standard Wimp window and icon definitions. The template file wraps those structures with a lookup layer so that a template can be loaded by name at runtime.
Index and entry organisation
Each named template entry has an index record that identifies the template name and where its data block is stored in the file. The data block then contains the window definition, icon definitions, and any indirected strings or sprite names referenced by the window title and icons.
This organisation is why template-oriented tools can either:
- search the index for one template by name; or
- convert the entire file into a text form that preserves the named-entry structure.
The optional font data named in the overall file structure is identified by a single word at offset 0 of the whole file, before the index begins. A value of &FFFFFFFF means no font data is present. The internal layout of the font data block itself is not documented here; fonts in templates are an uncommon case, and tooling in this environment does not currently support them.
Template data block
The template data block holds the window's in-memory definition, in the same layout the Wimp uses internally:
| Offset | Size | Contents |
|---|---|---|
| 0 | 4 | Visible area minimum x coordinate (inclusive). |
| 4 | 4 | Visible area minimum y coordinate (inclusive). |
| 8 | 4 | Visible area maximum x coordinate (exclusive). |
| 12 | 4 | Visible area maximum y coordinate (exclusive). |
| 16 | 4 | Scroll x offset relative to the work area origin. |
| 20 | 4 | Scroll y offset relative to the work area origin. |
| 24 | 4 | Handle of the window to open behind, or -3 (iconised), -2 (bottom of stack), -1 (top of stack). |
| 28 | 4 | Window flags. |
| 32 | 1 | Title foreground colour (0-254), or 255 if the window has no frame. |
| 33 | 1 | Title background colour. |
| 34 | 1 | Work area foreground colour. |
| 35 | 1 | Work area background colour (0-254), or 255 if redraw rectangles should not be cleared by the Wimp. |
| 36 | 1 | Scroll bar outer colour. |
| 37 | 1 | Scroll bar inner (slider) colour. |
| 38 | 1 | Title background colour when the window has input focus. |
| 39 | 1 | Extra window flags. |
| 40 | 4 | Work area minimum x coordinate. |
| 44 | 4 | Work area minimum y coordinate. |
| 48 | 4 | Work area maximum x coordinate. |
| 52 | 4 | Work area maximum y coordinate. |
| 56 | 4 | Title bar flags. |
| 60 | 4 | Window button type. |
| 64 | 4 | Pointer to a sprite area control block, or 1 to use the Wimp sprite pool. |
| 68 | 2 | Minimum width of the window. |
| 70 | 2 | Minimum height of the window. |
| 72 | 12 | Title data (inline title text, or an indirected title pointer/validation/length triple, depending on the title bar flags at offset 56). |
| 84 | 4 | Number of icons in the template, completing the 88-byte window definition block. |
| 88 | 32 × icon count | Icon definition blocks. |
| after icons | variable | Indirected title text, validation strings, sprite names, and other workspace-copied data. |
Each icon definition block is 32 bytes, made up of a 16-byte bounding box (four signed words: x0, y0, x1, y1), a 4-byte icon flags word at offset 16, and a 12-byte icon data field at offset 20 whose interpretation (inline text/sprite, or an indirected pointer/validation/length triple) depends on the icon flags.
The window-definition fields occupy the first 84 bytes, followed by the icon count at bytes 84-87 (completing an 88-byte window definition block in total), then 32 bytes for each icon definition. This matches the way Wimp_LoadTemplate first fills the user block with fixed structures and then copies indirected data into the separate work area supplied by the caller.
Indirected title and icon data
Template entries often contain indirected text or sprite references rather than fixed inline strings. During loading, the Wimp or a compatible loader rewrites those references so that the title text, validation strings, and indirected icon contents point into the workspace buffer supplied by the caller.
The relevant fields are:
| Location | Use |
|---|---|
| Window bytes 56-59 | Title bar flags (offset 56 in the window definition block above) used to determine whether the title is indirected text or sprite data. |
| Window bytes 72-83 | Title data (offset 72, 12 bytes), which may contain indirected title pointers and length information. |
| Icon bytes 16-19 | Icon flags (offset 16 in the 32-byte icon definition block above) that describe whether the icon data is text, sprite, and/or indirected. |
| Icon bytes 20-31 | Icon data field (offset 20, 12 bytes), which may contain indirected text pointer, validation pointer, and length values. |
This is the main reason that template files are easier to maintain through riscos-ccres than through manual binary editing: the text form preserves the logical resource structure without forcing you to maintain raw offsets by hand. The text syntax itself is described in Appendix P: CCres textual file formats.
Working with template files
Use riscos-ccres to convert template files to text and back again. This gives a source-controlled form that can be reviewed, diffed, and regenerated as needed.
For the editable text representation used by that workflow, including window, icon, and font block syntax, see Appendix P: CCres textual file formats.
For projects that need programmatic access to resources, a template file may also be combined with tools such as riscos-templateheader and riscos-fixuptemplate.
Conversion workflow
Converting a template file to text and back
This is the normal inspection and editing workflow for template resources.
riscos-ccres Templates,fec Templates.txt
riscos-ccres Templates.txt Templates,fec