ResFool User Manual

	Preliminary Documentation
	This document contains preliminary documentation for the ResFool application. It has significant gaps and should not be taken as a complete overview of all functionality available in the program.

Decimal Long/Word/Byte The decimal long, word and byte type specify a signed integer value occupying four, two or one bytes, respectively. These types do not account for alignment (see Alignment types, below). Given this C struct:

struct {
	short int		left;
	short int		top;
	short int		right;
	short int		bottom;
} Rect;

a reasonable template would be:

RECT {
Left
DWRD
Top
DWRD
Right
DWRD
Bottom
DWRD
}

Values for the long type range from -2147483648 to 2147483647. Values for the word type from -32768 to 32767. Values for the byte type range from -128 to 127.

Unsigned Long/Word/Byte The unsigned long, word and byte type specify an unsigned integer value occupying four, two or one bytes, respectively. These types do not account for alignment (see Alignment types, below). Given this C struct:

struct {
	unsigned long int		time;
	unsigned short int		id;
	
} track;

a reasonable template would be:

TRCK {
Time
ULNG
ID
UWRD
}

Values for the long type range from 0 to 4294967295. Values for the word type from 0 to 65535. Values for the byte type range from 0 to 255.

Hex Long/Word/Byte The hex long, word and byte type specify an integer value in hex occupying four, two or one bytes, respectively. These types do not account for alignment (see Alignment types, below). This field is useful when specific hex values should be entered.

Values for the long type range from 0 to 0xFFFFFFFF. Values for the word type from 0 to 0xFFFF. Values for the byte type range from 0 to 0xFF.

Filler Long/Word/Byte The filler types specify four, two and one byte values that are used to fill a structure. These are invisible values that will not be shown in the template list, though they will appear in the hex data. Items marked as "unused" in structures are good candidates for these types. When combined with an appropriate "case" statement, they will default to the correct value.

struct {
	unsigned long int		version;
	unsigned long int		unused; //should be 0xDEADBEEF
	unsigned long int		flags;
} data;

could be represented as:

data {
Version
ULNG
unused
FLNG
default=DEADBEEF
CASE
flags
ULNG
}

The value of these items cannot be set from the template editor.

Real/DoubleThese fields represent four and eight byte floating point values. Data may be entered as simple numbers with a decimal, or using scientific notation (e.g. either .00000001 or 1.0e-9).

Pascal String/Even Pad/Odd Pad Pascal strings consist of a byte count followed by up to 255 single-byte characters. The minimum number of bytes used by this type is one with a value of zero. This field has a maximum size of 256 bytes (255 characters). Since the length of the string is variable and may cause alignment problems, the ESTR and OSTR types are provided to handle alignment issues without requiring a separate alignment value. Using an Even Pad pascal string, the field immediately following the string will be placed on an even boundary. An Odd Pad string will force the following field on an odd boundary. This is accomplished by inserting a single byte with a value of zero when necessary.

C String/Even Pad/Odd Pad C strings consist of a series of single-byte characters followed by a single-byte zero. The minimum number of bytes used by this type is one with a value of zero. There is no maximum size imposed by this type. Since the length of the string is variable and may cause alignment problems, the ECST and OCST types are provided to handle alignment issues without requiring a separate alignment value. Using an Even Pad C string, the field immediately following the string will be placed on an even boundary. An Odd Pad string will force the following field on an odd boundary. This is accomplished by inserting a single byte with a value of zero when necessary.

Byte/Word/Long Count String Counted strings consist of one, two or four bytes identifying the length of the string followed by the string data. The minimum number of bytes used by this type is a length field with a value of zero (one, two or four). This field has a maximum size of 256/65537/4294967299 bytes, including the length field. The BSTR type is functionally equivalent to the PSTR type. It is included here for symmetry.

Pascal/C/Text Fixed Width Fixed width text fields always use the amount of space specified in their type, from 0 to 2559 bytes (see note "Variable Size Template Items"). A string does not need to use all bytes assigned in this field - any excess bytes will be set to 0. So, the string "Hello" stored as a P020 will have a byte with the value '5', followed by the 5 bytes of 'Hello' followed by 26 bytes of zero. For example, this structure:

struct {
	unsigned long int      version;
	unsigned char          name[32];
	char                   address[512];
} IDCard;

could be represented as:

IDCD {
Version
ULNG
Name
P020
Address
C200
}

Single-byte Character A character that occupies exactly a single byte. Equivalent to T001.

Text Dump A text dump indicates uncounted, unterminated text to the end of the enclosing structure. Typically, this means all data until the end of the resource should be considered text. In such cases, 'TXTS' must appear as the last item in the template and may be the only item. These fields may also appear in more complex structures (e.g. keyed lists). They must appear at the end of a structure, and it must be possible to calculate the size of the structure, or it must appear as the last element of the template. A common use would be a structure like this, where the structure will be created with enough storage for variable length text:

struct {
	unsigned long int      version;
	unsigned char          name[32];
	char                   address[1];
} IDCard;

This might be represented as:

IDCD {
Version
ULNG
Name
P020
Address
TXTS
}

Byte/Word/Long Hex Dump Hex dumps consist of one, two or four bytes identifying the length of the data followed by the hex data. The minimum number of bytes used by this type is a length field with a value of zero (one, two or four). This field has a maximum size of 256/65537/4294967299 bytes, including the length field. The data must be edited in hex. These types are useful to represent unknown data whose length is available.

Byte/Word/Long Hex (Count Included) Dump Hex dumps consist of one, two or four bytes identifying the length of the data followed by the hex data. The minimum number of bytes used by this type is a length field with a value of one, two or four (one, two or four bytes long). This field has a maximum size of 255/65535/4294967295 bytes, including the length field. The data must be edited in hex. These types are useful to represent unknown data whose length is available and includes the length field itself.

Fixed-width Hex Dump/Filler Specifies a fixed-width field that contains unknown data. The hex dump may be edited as hex when viewing a template, the filler is not editable or visible when viewing the template.

Type Name A four byte field used to identify a Mac type, typically an applications creator code or file type.

Date/Modification Date A four byte date field. It is the number of seconds that have passed since January 1, 1904, the traditional Mac epoch. The Modification Date field automatically updates to the current date and time when the resource is opened.

Begin Indefinite List This item introduces an indefinite list of items. All data found in a resource after this item is interpreted as elements of the list. Since there is no count or end condition for this type of list, the list must be the final element of a template. For instance, if you wanted to represent a resource that consisted of a list of a two byte key and a Pascal string, you might define this template:

PLST {
Keyword List
LSTB
Key
DWRD
Name
PSTR
List End
LSTE
}

Begin Counted List This item introduces a list of items with an associated count field. This item simply indicates the start of the list, it does not represent the count. The closest list count type at the same nesting level as the list above this item is used as the count (see the various list count types in this section). Since the number of elements in a counted list can be determined, these lists may appear anywhere in a resource template, at any nesting level (even inside other lists) as many times as needed. This template could be used to define a list of Pascal strings preceded by a two byte count:

STR# {
String Count
OCNT
Strings
LSTC
String
PSTR
List End
LSTE
}

Begin Zero-Terminated List This item introduces a list of items which is terminated by a single byte with a value of 0x00. This item simply indicates the start of the list. The list will have as many items as can fit until the first zero byte is encountered. Since the number of elements in a zero-terminated list can be determined, these lists may appear anywhere in a resource template, at any nesting level (even inside other lists) as many times as needed. In general, use of this type should be avoided.

	First Element Must be Non-zero
	The first data field of a LSTZ list must not be zero. If it is, processing of the list will terminate prematurely causing unpredictable behavior.

Begin Sized List This item introduces a list of items whose entire size in bytes is known. This item simply indicates the start of the list, it does not represent the size of the list. This list type must be surrounded by a SKIP (or related field) and SKPE pair. The SKIP field will automatically update a byte count indicating the total size of the list. Since the number of elements in a sized list can be determined, these lists may appear anywhere in a resource template, at any nesting level (even inside other lists) as many times as needed, though they must obey the nesting requirements of SKIP/SKPE pairs.

This list type is useful when you wish to be able to quickly jump over a list of variable length data, without examining the contents of every list entry. For example, imagine a list of where each entry is a name and phone number pair (two Pascal strings). After the list data is a single byte which gives a dialing prefix used for all phone calls. This could be represented with a counted list, but getting the dialing prefix (in your code) requires examination of both strings in every list entry. Instead, you could place a single, four byte field at the beginning of the resource which contains the size, in bytes, of the list data. To get the dialing prefix would then be accomplished by jumping to the offset specified in that field. This would be specified like this (ResFool will calculate the size field for you):

PhNm {
Skip field
LSKP
Numbers
LSTS
Name
PSTR
Phone Number
PSTR
List End
LSTE
End Skip
SKPE
Dialing Prefix
DBYT
}

For more information on SKIP/SKPE pairs, see the section on Skip Offsets and Sizeof values.

End List Marks the end of a list structure started with LSTB, LSTC, LSTZ or LSTS. Represents no data in the resource. This item simply identifies the end of a group of template items which will be used to define a single entry in a list.

Byte/Word/Long List Count These types represent one, two or four byte list count values. They must appear at the same level and somewhere before a counted list (LSTC) entry. Their value is automatically set by ResFool when entries are added to or removed from the associated counted list. Their value is the number of items stored in the list.

Zero-based List Count/Long Zero-based List Count These types are two- or four-byte signed integers. They must appear at the same level and somewhere before a counted list (LSTC) entry. Their value is automatically set by ResFool when entries are added to or removed from the associated counted list. Their value is the number of items stored in the list minus 1. So, a ZCNT with a value of 0 indicates a list with 1 entry while a value of -1 indicates an empty list.

Fixed-width List Count Unlike other list count fields, the fixed-width count does not represent any data in the resource. Instead, it uses the first numeric value found in the template name to determine the number of list elements. It must appear at the same level and somewhere before a counted list (LSTC) entry. The list will always have exactly the number of elements listed in the label for the field.

Bit in a Byte/Word/Long/Bits in a Byte/Word/Long These fields represent a bit (or bits) in a one, two or four byte set of flags. The 'xxIT' versions identify a single bit. The 'xxmm' versions must specify the number of bits (in decimal) used by the field. The 'mm' should be replaced with a value of 02-08, 02-16 or 02-32, depending on the field width (byte/word/long). When one of these fields is encountered there must be an adequate number of following, same type fields to make a complete flag set. For instance, a BBIT must be followed by seven more BBIT fields or a BB07 field. Bit order starts with the most significant bit first. To create a template with a single byte of flag data, where only the least-significant 4 bits are used:

Bits {
Unused
BB04
Bold
BBIT
Underline
BBIT
Italic
BBIT
Shadow
BBIT
}

Byte/Word/Long Flag These fields specify a single boolean value occupying one, two or four bytes. Their value can be either zero (false) or one (true).

Boolean This field is a two byte boolean flag. If either byte contains a non-zero value, it is considered true. ResFool uses the hex value 0x0100 to represent true when the flags checkbox is toggled to the on setting.

Keyed List Item Begin/End These fields surround a single entry in a keyed list. They do not represent actual data in the resource. They identify which set of template fields should be used to process the resource data. There must be as many pairs of these fields as there are CASE statements for the key type of this list (or one more, in certain circumstances).

Byte/Word/Long Key Type One, two and four byte signed fields that introduce a keyed list. When parsing the resource data, this value is read and a CASE statement with a matching value is found. The index of that case statement is then used to find the correct KEYB field that starts the enclosed data, which is then used to represent the stored information.

Unsigned Byte/Word/Long Key Type One, two and four byte unsigned fields that introduce a keyed list. When parsing the resource data, this value is read and a CASE statement with a matching value is found. The index of that case statement is then used to find the correct KEYB field that starts the enclosed data, which is then used to represent the stored information.

Hex Byte/Word/Long Key Type One, two and four byte fields that introduce a keyed list. The values in the CASE statements should be specified in hexadecimal. When parsing the resource data, this value is read and a CASE statement with a matching value is found. The index of that case statement is then used to find the correct KEYB field that starts the enclosed data, which is then used to represent the stored information.

Type Name Key Type Four byte field that introduces a keyed list. The values in the CASE statements should be specified as four characters (a mac type). When parsing the resource data, this value is read and a CASE statement with a matching value is found. The index of that case statement is then used to find the correct KEYB field that starts the enclosed data, which is then used to represent the stored information.

Resource ID Key Type This field does not represent any data. Instead, it uses the ID of the resource as the value for the keyed list. So, a resource whose ID is 128 would match a CASE statement whose value was set to 128. When parsing the resource data, this value is read and a CASE statement with a matching value is found. The index of that case statement is then used to find the correct KEYB field that starts the enclosed data, which is then used to represent the stored information.

Byte/Word/Long Sizeof One, two and four byte fields that introduce a skip offset section. The value stored here is the size of the data found between this field and the next SKPE at the same nesting level. It does not include its own size. These values are calculated automatically by ResFool and cannot be edited directly.

Byte/Word/Long Skip One, two and four byte fields that introduce a skip offset section. The value stored here is the size of the data from this field to the next SKPE at the same nesting level. It includes its own size. These values are calculated automatically by ResFool and cannot be edited directly.

Skip Two byte field that introduces a skip offset section. The value stored here is the size of the data from this field to the next SKPE at the same nesting level. It includes its own size. These values are calculated automatically by ResFool and cannot be edited directly. Identical to a WSKP field.

End Skip This field does not represent any actual data in the resource. It marks the last field in the template that is to be included in the size of a skip start entry.

Word/Long Alignment The word align field may insert a single byte. The long field may insert up to three bytes. Either field may be zero bytes. The smallest number of bytes will be added to make the next field in the template appear on a byte offset that is evenly divisible by two or four. As the data in the template changes, the alignment fields will expand or contract to keep the following field on a legal offset. The value of inserted bytes will be set to zero.

Arbitrary Alignment The arbitrary align field may insert up to mm-1 bytes (or none). The smallest number of bytes will be added to make the next field in the template appear on a byte offset that is evenly divisible by mm. As the data in the template changes, the alignment field will expand or contract to keep the following field on a legal offset. The value of inserted bytes will be set to zero. For instance, to keep the following field on a 32-byte offset, set this field to AL32.

Case The case field identifies a known value for a particular template field. It does not represent any actual data in the resource. The label of a case should have an identifying text string, an equal sign ("=") and a value consistent with the field it is being used for. When presented in the hex editor, a popup listing all the label names will be shown. Picking one will set the data of the associated field to whatever was specified after the equal sign. A template field may be followed by any number of CASE fields. The first CASE immediately following a template item will be used as the default value when creating the data for the resource (when an empty resource is opened). This makes a single CASE useful, even if the popup is not used. If you were creating a resource for a graphic object that had a name, height and width, where values of -1 for height and width meant using a default size, you might construct a template like this:

VIEW {
Name
PSTR
None=Untitled
CASE
Height
DWRD
Default=-1
CASE
Short=480
CASE
Tall=1024
CASE
Width
DWRD
Default=-1
CASE
Narrow=640
CASE
Wide=1280
CASE
}

A CASE field whose label is a single hyphen ("-") will create a separator in the popup displayed while editing a resource.

Resource ID This is a signed, two byte value that represents the ID of a resource. It is functionally equivalent to a DWRD type. Future versions of ResFool may provide additional functionality when a number is identified as a resource ID.

Divider Ignored. It is provided to support templates created for other resource editing applications. Future versions of ResFool may use this field to provide visual division of fields while editing a resource.

Rectangle Identifies a rectangle consisting of signed, two byte values for a top, left, bottom and right. It is functionally equivalent to having four DWRD fields, though it is displayed as a collapsible entry when editing the resource.

Region Code This is a signed, two byte value that represents an Apple region code. It is functionally equivalent to a DWRD type. Future versions of ResFool may provide additional functionality when a number is identified as a region code.

Point This is a pair of signed, two byte values that represents an x,y coordinate. It is functionally equivalent to two DWRD types, though it is displayed as a collapsible entry when editing the resource. Note this type is specified as 'PNT ' where the fourth character is a space.

RGB Color This is a tuple of unsigned, two byte values that represents an RGB color. It is functionally equivalent to 3 UWRD types, though it is displayed as a collapsible entry when editing the resource. Future versions of ResFool may provide additional functionality when a tuple is identified as a color.

Hex/Code Dump Marks the remainder of the data in the resource as either unknown and uneditable hex data, or as machine code. In either case, the data cannot be edited from the template. Future versions of ResFool may provide additional functionality when editing data marked as CODE.