Overview
riscos-ccres converts two RISC OS binary resource formats into a stable textual form and can rebuild the binary files from that text. The supported binary formats are Toolbox Resource files with filetype ,fae and Wimp Template files with filetype ,fec.
The textual form is intended for editing, comparison, searching, translation, and bulk maintenance. It names object classes, field names, symbolic flags, and string contents explicitly, so changes that are awkward in binary editors can be made with ordinary text tools.
This appendix documents the editable text formats themselves. For the underlying binary Wimp Template structure, see Appendix K: Template File Format.
Conversion rules
Input recognition and headers
The command-line tool takes exactly two positional arguments: an input file and an output file. It decides the conversion direction from the input file contents, not from the filename.
| Detected form | Recognition rule | Result |
|---|---|---|
| Toolbox Resource binary | First word is RESF and version is 101 | Converted to text. The generated text begins with RESF:1.01. |
| Wimp Template binary | Second, third, and fourth header words are zero | Converted to text. The generated text begins with Template:. |
| Text file | First sixteen bytes contain no control characters other than LF | The first line selects the output binary format. RESF:1.01 selects Toolbox Resource output; Template: selects Wimp Template output. |
Only two text headers are recognised on import: RESF:1.01 and Template:. Although older descriptions mention RESF version 1.00, the current tool accepts and writes only RESF version 1.01.
Numbers, strings, and comments
CCres text is line-oriented. Entry names are followed by a colon, and the remainder of that line becomes the value. A number sign introduces a comment that runs to the end of the line.
| Feature | Examples | Behaviour |
|---|---|---|
| Numbers | 123, &80, 0x80, 16_FF, 2_1010 | Numeric fields accept decimal, RISC OS hexadecimal, C-style hexadecimal, and explicit radix-prefixed forms. |
| Expressions | cmp:, bbox:, coord fields | Arithmetic expressions support (), +, -, *, and / with integer division. |
| Flags and enums | window.flags:, title_flags: | Flag fields accept symbolic names separated by |. Enumeration fields accept one symbolic name. Residual unknown bits are written as 0x.... |
| Strings | title:, text:, object_name: | Export always uses double quotes. Import also accepts unquoted strings that run to the end of the line. |
| Comments | # note | The comment marker applies only outside values; the rest of the line is ignored. |
Resource string limit fields and Template string size fields may use * to mean "use the minimum size required for the current string and terminator". When a supplied Template size is too small, the tool increases it and emits a warning rather than truncating the data silently.
Toolbox Resource text format
Overall structure
A Resource text file begins with RESF:1.01 followed by zero or more top-level Toolbox objects. Each object uses a class-specific object name and contains a common object header followed by class-specific entries.
RESF:1.01
window_object {
header_flags:
version:102
object_name:"Main"
...
}
| Top-level object name | Purpose | Notes |
|---|---|---|
| window_object | Toolbox Window object | May contain nested keyboardshortcut_object blocks and gadget blocks. |
| menu_object | Toolbox Menu object | Contains nested Entry blocks. |
| saveas_object | SaveAs dialogue | Standalone Toolbox object. |
| iconbar_object | Iconbar icon | Standalone Toolbox object. |
| scale_object | Scale dialogue | Standalone Toolbox object. |
| colourdbox_object | ColourDbox dialogue | Standalone Toolbox object. |
| colourmenu_object | ColourMenu object | Standalone Toolbox object. |
| dcs_object | DCS dialogue | Standalone Toolbox object. |
| fileinfo_object | FileInfo dialogue | Standalone Toolbox object. |
| fontdbox_object | FontDbox dialogue | Standalone Toolbox object. |
| fontmenu_object | FontMenu object | Standalone Toolbox object. |
| printdbox_object | PrintDbox dialogue | Standalone Toolbox object. |
| proginfo_object | ProgInfo dialogue | Version-dependent fields exist for version 1.01 objects. |
| quit_object | Quit dialogue | Standalone Toolbox object. |
Common and nested object fields
Every top-level Resource object begins with the same three fields.
| Entry | Type | Meaning |
|---|---|---|
| header_flags: | flags | Zero or more of toolbox_OBJECT_CREATE_ON_LOAD, toolbox_OBJECT_SHOW_ON_CREATE, toolbox_OBJECT_SHARED, and toolbox_OBJECT_ANCESTOR. |
| version: | integer | Object format version stored in the Resource object header. |
| object_name: | string | Object name used for Toolbox references. |
Window objects also carry Toolbox window metadata, an embedded Wimp window definition, zero or more nested keyboardshortcut_object blocks, and zero or more gadget blocks. Every gadget block begins with these common entries:
| Common entry | Type | Meaning |
|---|---|---|
| cmp: | expression or component value | Component id. Expressions are allowed. |
| bbox: | box expression | Bounding box in work-area coordinates. |
| help_message: | message string | Help text for the gadget. |
| help_limit: | limit | Allocation for the help text. |
The supported gadget object names are actionbutton_object, adjuster_object, button_object, displayfield_object, draggable_object, label_object, labelledbox_object, numberrange_object, optionbutton_object, popup_object, radiobutton_object, scrolllist_object, slider_object, stringset_object, tabs_object, textarea_object, treeview_object, toolaction_object, and writablefield_object.
Menu objects contain one or more nested Entry blocks. Standalone objects such as saveas_object, iconbar_object, and quit_object contain only their fixed field sets.
Wimp Template text format
Overall structure
A Template text file begins with the literal line Template:. The canonical order is one or more top-level wimp_window blocks followed by zero or more top-level template_font_data blocks.
Template:
wimp_window {
template_name:"Main"
visible:0,0,640,480
...
}
CCres counts top-level brace blocks before conversion, then consumes only the leading wimp_window blocks on its first pass. For that reason, Template text should keep all window blocks before any template_font_data blocks and should not introduce other top-level object names.
Window, icon, and font entries
Each wimp_window block begins with template_name: and then carries the embedded Wimp window definition.
| Entry group | Examples | Meaning |
|---|---|---|
| Window geometry and state | visible:, xscroll:, yscroll:, next:, extent:, xmin:, ymin: | The basic Wimp window position, scroll state, stack position, work-area extent, and minimum size. |
| Window appearance | window_flags:, title_fg:, title_bg:, work_fg:, work_bg:, scroll_outer:, scroll_inner:, highlight_bg:, extra_flags:, work_flags:, sprite_area: | The standard Wimp window flags, colours, button-type bits, and sprite-area reference. |
| Title payload | text_only:, sprite_only:, text_and_sprite:, text.text:, text.size:, text.validation:, sprite.id:, sprite.size:, sprite.area: | The title form depends on the title_flags: combination and follows the same icon-data rules as ordinary icons. |
Each nested wimp_icon block uses common entries extent:, icon_flags:, icon_esg:, icon_fg:, icon_bg:, and font_handle: before one of the same six payload forms used by window titles: text only, sprite only, text and sprite, indirected text, indirected sprite, or indirected text and sprite.
Optional template_font_data blocks represent entries from the Template font table. Each block accepts exactly these entries:
| Entry | Type | Meaning |
|---|---|---|
| x_point_size: | bits | Horizontal point size. |
| y_point_size: | bits | Vertical point size. |
| font_name: | fixed-size string | Font name stored in the forty-byte binary field. |
Round-tripping and validation
CCres does not attempt byte-for-byte recreation of files created by other tools. It recreates equivalent Resource or Template content in its own normal serialisation.
Important consequences of that normalisation are:
- Resource relocation entries are written in ascending offset order.
- Superfluous fields that some GUI editors save are omitted when CCres does not use them.
- Template text is truncated at the first control-character terminator; stray bytes after a terminator are ignored when exporting to text.
- Strings are re-emitted in quoted canonical form, and size fields may be normalised to * when they already match the minimum required allocation.
The reliable validation loop is therefore binary-to-text conversion, editing, text-to-binary conversion, then binary-to-text conversion again and comparison of the textual forms.