Working with Resources in Palm OS Applications

Resource Types

Before diving into the Palm OS resource managemnent stuff, take a look at what you are going to manage. The following table describes the main resource types available in Palm OS:

Constant	Value	Description
strRsc	'tSTR'	String resource
ainRsc	'tAIN'	Application Icon Name resource
iconType	'tAIB'	Icon resource
bitmapRsc	'Tbmp'	Bitmap resource
bsBitmapRsc	'Tbsb'	Boot screen bitmap. This resource is system reserved
alertRscType	'Talt'	Alert resource
kbdRscType	'tkbd'	Keyboard resource. This resource is system reserved
MenuRscType	'MBAR'	Menu Bar resource
fontRscType	'NFNT'	Single density Font resource
fontExtRscType	'nfnt'	High density Font resource
verRsc	'tver'	Version resource
appInfoStringsRsc	'tAIS'	Application Categories are store here. This resource can be passed to the CategoryInitialize() API
fontIndexType	'fnti'	Represents the font index. This resource is system reserved
midiRsc	'MIDI'	Palm MIDI compliant resource
colorTableRsc	'tclt'	UI Color Table resource
constantRscType	'tint'	Integer constant resource. ResLoadConstant() API can be called to load the this type of resource
formRscType	'tFRM'	UI Form resource
strListRscType	'tSTL'	This is a string list resource
wrdListRscType	'wrdl'	List of WORD (2 bytes) values
defaultCategoryRscType	'taic'	Launcher Category ID. Your application will be placed under the appropriate category on the Palm device
binaryGeneralRscType	'tbin'	General binary resource. You may store any raw data here

After such a smart start, you can see how rich this game is. It's odd to say that, by using resources, you make all localization issues much easier. For custom launch codes, when you can't have global variables, a resource may be an ideal solution to work around it, and so forth. If you're already convinced, the next sections will guide you through the supporting API calls.

Searching Resource Databases

First of all, consider how to conduct a resources search. DataMgr.h defines the following functions for this purpose:

DmOpenRef  DmNextOpenResDatabase(DmOpenRef dbP);
UInt16     DmFindResourceType(DmOpenRef dbP, DmResType resType,
                              UInt16 typeIndex);
UInt16     DmFindResource(DmOpenRef dbP, DmResType resType,
                          DmResID resID, MemHandle resH);
UInt16     DmSearchResource(DmResType resType, DmResID resID,
                            MemHandle resH, DmOpenRef *dbPP);

These functions expose various ways to get the desired results. Usually, resources are stored in PDB on a Palm device. When you request a specific resource, the Palm OS will start from recently opened databases. The DmNextOpenResDatabase function controls which database will be searched for. The first one in the search chain will be returned, passing NULL as a parameter. Actually, it is the last loaded resource database; for example, your application. Note, that in case of using overlays, the returned pointer will reference the overlay, not the base resource.

DmFindResource and DmFindResourceType run over a given database for specified resource parameters such as type, index, ID, or memory handle. In turn, DmSearchResource does its job over all open resource databases and returns a reference to the appropriate database.

Although Palm OS 6 still supports a "search chain" notion for backward compatibility, new applications should not rely on this. To illustrate what was said above, take a look at the following code sample:

...
DmOpenRef dbP  = DmNextOpenResDatabase(NULL);
UInt16 nIdx    = DmFindResourceType(dbP,'tSTR',1);
MemHandle hMem = DmGetResourceIndex(dbP,nIdx);
Char *pData    = (Char*)MemHandleLock(hMem);
...
MemHandleUnlock(hMem);

This code snippet obtains a reference of the recent resource database (application itself in this case), searches for the string of index 1, and finally loads it by using a DmGetResourceIndex call. Here's a standard trick: First, obtain a resource index inside a database and then get it itself. Such a technique is useful when you need to enumerate some kind of resources and display them; for example, in some list.

Page 1 of 2