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

1    Creating XML Resource Files

Palm OS® Resource File Formats

Palm OS® Developer Suite

This chapter covers the following topics:

Introducing XML
Creating XRD Files
Understanding XML Resource Descriptions
Common Resource Attributes

Introducing XML ^TOP^

XML is a text format, similar to HTML in structure, although more powerful. An XML file represents a hierarchical data structure. The basic building blocks of an XML file are elements and attributes. An element is a named container. An element may have attributes, text data, and child elements. Attributes are named value tags.

Listing 1.1  XML File Elements and Attributes


<SAMPLE ID="1" NAME="my_samp"> 
	<BAR> 3 </BAR> 
</SAMPLE> 

In this example, shown in Listing 1.1, SAMPLE is the main element. It has two attributes, one named ID and one named NAME. It has one child element named BAR with text 3.

File Structure and Formatting Rules ^TOP^

  • Element and attribute names are case sensitive. For example, SAMPLE is not the same as Sample.
  • Attribute values must always be quoted.
  • White space (blanks, tabs, line endings) is not significant between tags.
  • The order of attributes is not significant.
  • The order of elements is significant.

XML Text Files ^TOP^

To minimize operating system differences, hardware differences, and language differences, Palm OS resource XML files are stored in Unicode format. (Unicode is a character encoding format that is becoming standard for text file interchange.) The Palm OS resource tools currently support UTF-16 and UTF-8 Unicode character encoding.


IMPORTANT: Palm OS resource tools work with XML files in either UTF-16 or UTF-8 Unicode character encoding. UTF-8 is recommended for compatibility with text editors and source control tools that may not handle the binary data in UTF-16 files correctly.

If you use a text editor that saves files in an encoding format other than UTF-16 or UTF-8 Unicode character encoding, such as a Windows native code page, you may have problems when compiling or editing the XRD file with Palm OS Resource Tools like PalmRC and PRCMerge.

Creating XRD Files ^TOP^

The source code for resources are stored in a platform-independent, XML text file format. This file format is called an XML resource description file, or XRD file. This XRD file is an XML implementation for defining application resources.

Palm OS XRD files use XML structure and text encoding. However, XRD files limit the use of XML in the following ways:

  • To add comments to your XRD files, you should use comment attributes and elements rather than XML-style comments. See "Comment Attribute" for information on comment attributes.

    Because comment attributes and elements are stored as logical attributes of the resource file, they can be retained in the memory representation of the resource file.


IMPORTANT: XML-style comments will be ignored by PalmRC, and they will be stripped out if you use other Palm OS resource tools to save or regenerate them.
  • External data files, such as bitmap files or MIDI files, are supported using content syntax rather than XML external entity references. See "External File Reference" for information on specifying external data files.

XRD File Content Structure ^TOP^

XRD files must follow the structure defined in Listing 1.2.

Listing 1.2  XRD File Content Structure


XML header  
PALMOS_RESOURCE_FILE element  
	optional DATABASE_HEADER element  
	0 or more resource elements  

XML Header
The XML header identifies the file as an XML file. The XML header may also specify that the document is using a DTD (document type definition). The DTD may be used to validate the structure of the comment by validating XML parsers, editors, and other processing tools. Listing 1.3 shows an example of an XML header.

Listing 1.3  XML Header Example


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>  

PALMOS_RESOURCE_FILE
The PALMOS_RESOURCE_FILE element is a standard element. There are no attributes defined for this element. For more information about this element, see "Palm OS Resource File".
DATABASE_HEADER element
The DATABASE_HEADER element stores the physical fields of a PRC database header. Normally, this element is not used in resource files because physical field attributes are set by the PRCMerge tool when a Palm OS executable is built. The main use for the DATABASE_HEADER element is to test conversion of PRC files.
If GenerateXRD is used on a PRC file with the "-d" option, the DATABASE_HEADER element is generated in the resulting XRD file.
When the XRD file is compiled by PalmRC, the resulting PRC file has the same database header as the original PRC file (with the exception of the creation and modification date and timestamp fields, which PalmRC updates).
Listing 1.4 shows and example of a DATABASE_HEADER element.

Listing 1.4  DATABASE_HEADER Example


<DATABASE_HEADER>  
	<DB_NAME> "Starter" </DB_NAME>  
	<DB_FLAG_RESET> FALSE </DB_FLAG_RESET>  
	<DB_FLAG_BACKUP> TRUE </DB_FLAG_BACKUP>  
	<DB_FLAG_HIDDEN> FALSE </DB_FLAG_HIDDEN>  
	<DB_FLAG_COPY_PROTECT> FALSE </DB_FLAG_COPY_PROTECT>  
	<DB_VERSION> 2 </DB_VERSION>  
	<DB_MOD_NUM> 0 </DB_MOD_NUM>  
	<DB_TYPE> 'appl' </DB_TYPE>  
	<DB_CREATOR> 'STRT' </DB_CREATOR>  
	<DB_UNIQUE_ID> 0x00000000 </DB_UNIQUE_ID>  
	<DB_APP_INFO>  </DB_APP_INFO>  
	<DB_SORT_INFO>  </DB_SORT_INFO>  
</DATABASE_HEADER>  

resource elements
The main content of the resource file is a set of resource element descriptions. The resource descriptions may be defined in any order, but it is best if you keep them in a canonical order and format. Canonical order helps when you use text comparison and source control tools to track resource changes during development.
The canonical order of resources is alphabetical by resource element name, then in numerical order by resource ID, then in order by locale. In addition, RAW_RESOURCE elements are sorted by their RES_TYPE element values before being sorted by resource ID.
For information about specific resource elements, see "Resource Element Reference".

Listing 1.5  Example of a Valid XRD File


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>  
 
<PALMOS_RESOURCE_FILE>  
 
	<STRING_RESOURCE RESOURCE_ID="1000">  
		<TEXT> "Palm OS" </TEXT>  
	</STRING_RESOURCE>  
 
</PALMOS_RESOURCE_FILE>  

Understanding XML Resource Descriptions ^TOP^

There is a one-to-one correspondence between XML resource descriptions and Palm OS resources in the PRC file. In general, the XML resource element name should match the logical resource type name.

For example, a Palm OS "string" resource, which is a Palm OS 'tSTR' resource, is a STRING_RESOURCE resource in the XML resource description file.

Listing 1.6  Example of a Resource Description File


<STRING_RESOURCE 
	RESOURCE_ID="1000"  
	LOCALE="enUS"  
	COMMENT="Language Name"> 
	<TEXT> "English" </TEXT> 
</STRING_RESOURCE> 

Common Resource Attributes ^TOP^

The following resource attributes are common to most of the XML resource descriptions.

Resource ID Attribute ^TOP^

RESOURCE_ID="resource_id"
Every resource element in the Palm OS resource file must have a RESOURCE_ID attribute. Developer-assigned resource IDs must be an unsigned integer in the range 0 to 9999.

Locale Attribute ^TOP^

LOCALE="llCC"
Each resource may optionally have a LOCALE attribute. This is used in conjunction with the parameters to PalmRC to strip resources into locale independent base resources, which are stored in BPRC files, and localized resources, which are stored in locale specific overlay resource files (OPRC files).
If the resource LOCALE attribute is not specified, or specified as the empty string (""), the resource is not locale specific and is placed in the base PRC file. If the resource LOCALE is specified, it indicates that the resource goes into the overlay PRC file for the specified locale.
Locales are indicated using 4-character codes specified by ISO 639 Language and ISO 3166 Country Codes. The locale values used by Palm OS currently are:
enUS
English
frFR
French
itIT
Italian
deDE
German
esES
Spanish
jaJP
Japanese. Note: For Palm OS Cobalt, you should use jaJP; for earlier versions of Palm OS, you should use jpJP instead.
zhCN
Simplified Chinese.
For more information, see the following web pages:
http://www.loc.gov/standards/iso639-2/englangn.html
See 639-1 alpha-2.
http://www.niso.org/3166.html
See 3166-1.

Overlay Status Attribute ^TOP^

OVERLAY_STATUS="overlay_info"
Each resource may optionally have an OVERLAY_STATUS attribute. The only explicit value currently supported is "ADD". If the attribute is not specified, or is specified as the empty string (""), the resource is treated as a REPLACE overlay.
The OVERLAY_STATUS attribute is used to validate that overlay resource files are correct. If a resource is present in a specific locale, but not in the base locale, it should specify the attribute as ADD.

Comment Attribute ^TOP^

COMMENT="comment_text"
Each resource may optionally have an COMMENT attribute. This should typically be a short string (that is, a few words at most) which describes the resource or its usage. For larger amounts of text, such as instructions for localization, use the COMMENT_TEXT element.