www.riscos.com Technical Support: Toolbox

Resource File Formats

This appendix describes the resource file format, which is intended to replace the Wimp Template file format, allowing you to specify the appearance of not only window definitions, but also menu definitions and dialogue boxes.

Terminology

The following terms are used throughout this appendix:

Term	Meaning
word	4 bytes stored in a file in 'little-endian' format; that is the least significant byte of the word is stored first.
resource file	consists of a fixed size header, followed by a contiguous set of user interface object templates or 'objects'. An object consists of a fixed size header followed by the variable size 'body' of the object, followed by 3 tables: string table message table relocations table All object headers are word-aligned. Unless otherwise explicitly stated, all occurrences of a 'word' in this appendix are assumed also to be aligned on a 4-byte address.
string	is a sequence of ASCII characters terminated by a NUL character. There is one table per object which holds all such strings. A 'string reference' is given by its byte offset from the start of the strings table. A null string reference is represented by -1. typedef int StringReference;
message	is some textual information which is visible to the user. All such messages for an object are held in its Messages Table. A null message reference is represented by -1. typedef int MsgReference;

Resource file format

Diagrammatic representation

Diagrammatically, a resource file is as follows:

where the file header is:

A resource file containing no objects has an objects Offset of -1 where an object template is:

A String Table Offset of -1 is used to denote an Object Template which has no String Table.

A Messages Table Offset of -1 is used to denote an Object Template which has no Messages Table.

A Relocation Table Offset of -1 is used to denote an Object Template which has no Relocation Table, and hence the nrelocs must always be > 0, if the Relocation Table exists.

When the Resource File is loaded by the Toolbox, the body offset field is always relocated to be a real pointer (but this is not specified as a relocation in the relocation table).

Resource File Format Description

A resource file begins with a standard fixed size header which has the format:

    'RESF'                  1 word 
    Version number          1 word   (* 100, e.g. 109 means 1.09) 
    Objects Offset          1 word

The current version number is 1.01

The objects Offset gives the byte offset from the beginning of the file where the object templates begin.

typedef struct 
{ 
    int        file_id; 
    int        version_number; 
    int        objects_offset;

} ResF_FileHeader;

The rest of the file starts with a contiguous sequence of object templates where each template has 3 words giving the byte offsets from the beginning of the template of each of the string, messages and relocations tables, followed by a standard fixed size header, followed by the body of the object, followed by its tables. All object headers are word-aligned.

Where the object header is:

Field	Type
Class of object	1 word
Flags	1 word
Version of the class module required	1 word
Object name	3 words
Total size of object in bytes	1 word
Offset of object body from start of object header	1 word
Total size of object body in bytes	1 word

Note that the name of an object is limited to 12 bytes including a terminating NUL character.

'Total size' of object refers to the total size of the object header, the object body and the string and message tables.

'Body size' refers only to the size of the object's body (i.e. without its string and message tables).

typedef struct 
{ 
    int                     class;
    int                     flags;
    int                     version;
    char                    name[12];
    int                     total_size;
    int                     body_offset;
    int                     body_size;

} ObjectTemplateHeader;

typedef struct
{ 
    int                     string_table_offset;
    int                     messages_table_offset;
    int                     relocations_table_offset;
    ObjectTemplateHeader    hdr;

} ResourceFileObjectTemplateHeader;

The use of a body_offset field is to allow expansion in the header, without losing backwards compatibility.

Relocations at Load Time

When the resource file is loaded into memory, the relocations table for each object is used to relocate any string, message, sprite area references and object offsets which appear in the object's body.

This means that the file can be loaded in one operation into memory, and when relocation has been done, the memory can be used directly to create an object.

Table Formats

There are three tables which optionally appear at the end of an object template: strings table, messages table, and relocations table.

Strings table

The string table contains all strings which are not visible to the user which are referenced elsewhere in the object. A string is a sequence of ASCII characters terminated by a NULL character.

Messages Table

The messages table contains a list of strings consisting of text strings which will be visible to the user at run-time, and which are referred to by the object template.

Relocations Table

The first word of the relocations table gives the number of relocations in the table.

The relocations table contains entries which give the byte offset of a word in the object which should be relocated at load time; this is an offset from the base of the object's body. Each entry is two words long: the byte offset, and a relocation directive. Possible relocation directives are:

Relocation Directive	Value	Meaning
StringReference	1	add the address of the base of the strings table to this word
MsgReference	2	add the address of the base of the messages table to this word
SpriteAreaReference	3	enter the address of the Sprite area into which the client's Sprites file has been loaded
ObjectOffset	4	add the address of the object's body to this word