Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

2    Specifying XRD Data Types

Palm OS® Resource File Formats

Palm OS® Developer Suite

This chapter describes the Palm OS resource descriptions for the following basic data types:

Binary Data
Boolean
Enum (Enumerated Value-Label)
External File Reference
Four-Character Code
Integer Number
Quoted Text

The Palm OS resource file structure allows data to be specified only in leaf elements. The data is specified as the XML text content of the element.

As defined by XML, white space is not significant in the text content, but it may be interpreted by the XML application. To avoid any possible misinterpretation of white space (when it is necessary to preserve text content accurately, such as in string resources), you should use the Quoted Text syntax that explicitly preserves the white space regardless of the XML text formatting.

Binary Data ^TOP^

Binary data values are specified as a sequence of bytes encoded as hexadecimal. The canonical format is two characters per byte with a space between bytes.

Example

<DATA> 48 65 6C 6C 6F </DATA> 
<DATA> 
	00 00 00 30 00 00 00 08 00 00 00 08 00 00 00 20 
	00 00 3F 3C 00 01 A9 F0 
</DATA> 

Boolean ^TOP^

A boolean value is a specific case of an enumerated type. The text labels accepted are FALSE and TRUE.

Examples

<HAS_COLOR_TABLE> FALSE </HAS_COLOR_TABLE> 
<HAS_TRANSPARENCY> TRUE </HAS_TRANSPARENCY> 

Enum (Enumerated Value-Label) ^TOP^

Palm OS defines some fields with a specific set of logical values, and assigns text labels to these logical values. Generally, you should use the text labels in the XRD file; but in most contexts, the integer number value of the enum is also accepted. Text labels are not case sensitive, but it is best to use the canonical uppercase form.

Examples

<COMPRESSION> NONE </COMPRESSION> 
<COMPRESSION> SCANLINE </COMPRESSION> 

External File Reference ^TOP^

An external file reference is a quoted string with a path to an external file. Normally, paths should be specified as relative to the location of the XRD file. Paths use a syntax similar to URL syntax.

For cross platform considerations, file and directory names should be 31 characters or less and should use a restricted character set. For example, use only Roman alphanumeric characters and underscore characters ('_'). Refrain from using special characters. In particular, colon (':'), backslash ('\'), and question mark ('?') characters should not be used in file or directory names.

Examples

<DATA_FILE> "mydata.bin" </DATA_FILE> 
<DATA_FILE> "./mydata.bin" </DATA_FILE> 
<DATA_FILE> "./datafiles/mydata.bin" </DATA_FILE> 
<DATA_FILE> "../../datafiles/mydata.bin" </DATA_FILE> 

Four-Character Code ^TOP^

A four-character code is used as a type code for physical resource types, PRC database types and creators, and similarly defined Palm OS constructs. A four-character code is denoted by single quote marks surrounding exactly 4 characters. Each character must be alphanumeric in low ASCII; that is, either lower case letters ('a' through 'z'), uppercase letters ('A' through 'Z') or numbers ('0' through '9'). In some contexts, four-character codes may also be specified as integer values (typically specified in hexadecimal format).

Examples

<DB_TYPE> 'appl' </DB_TYPE> 
<DB_CREATOR> 'MyAp' </DB_CREATOR> 

Integer Number ^TOP^

Integer number values may be specified as decimal or hexadecimal. Hexadecimal values are prefixed with the characters "0x". In some contexts, integers may also be specified as four-character codes.

Examples

<ID> 255 </ID>  
<ID> 0xFF </ID> 
<DWORD> 0x6170706C </DWORD>  

Quoted Text ^TOP^

A quoted text value is a string value. The string is specified with one or more segments which are concatenated together. A segment starts and ends with a double quotation mark ("). All text between the quotes is considered part of the string.

To avoid corruption of the string during XML processing, segments should never contain embedded line endings (for example, line feed or carriage return). That is, segments should never span lines in the XML file.

Special Characters ^TOP^

You can use XML character reference syntax to enter special characters in quoted text, especially for characters that would otherwise be interpreted as XML description characters.

You may use either predefined character references or numeric character references. For more information on XML character references, see this URL: http://www.w3.org/TR/REC-xml.

Examples of special characters

&amp;					Ampersand (&)  
&lt; 					Less than (<)  
&gt; 					Greater than (>)  
&apos; 					Apostrophe (')  
&quot; 					Double quote (")  
&#x2026;	 				Unicode code point hex 2026, an ellipsis (...)  


IMPORTANT: Numeric character references specify the Unicode code point of the character, not the Palm OS code point. PalmRC transliterates the character to the Palm OS code point depending on the target text encoding.

Using Escape Sequences ^TOP^

To include some special characters in quoted text, you may need to use an escape sequence.

  • To embed a line feed in a string, use the escape sequence \n.
  • To embed a double quotation mark in a string, use the escape sequence \".
  • To embed a backslash character itself, use the escape sequence \\.

It is also possible to embed control characters using the escape sequence \xHH where HH is the hexadecimal code of the character.


IMPORTANT: The embedded control character is interpreted as part of a Unicode string and is subject to transliteration, as usual, when compiling.

Listing 2.1  Escape Sequences


\n		Line feed 
\r		Carriage return (not normally used by Palm OS!) 
\t		Tab 
\\		Backslash 
\"		Double quotation mark 
\xHH		Control character as hexadecimal character code 

Examples

<TEXT> "OK" </TEXT> 
 
<TEXT> 
	"Use this application as a\n" 
	"starting point for your own\n" 
	"exciting Palm applications!" 
</TEXT>