OPaC:Documents: Resources

Introduction

A resource is specified by an id of type OPResID. This id is to be viewed as a handle to the real resource. You get resource ids by querying a resource bundle for a specific resource, defined by its index :

 
OPResID id1 = bundle->RetResID (index);
 

A bundle is a collection of related resources, stored within the same resource file. A bundle is loaded into memory by the resource manager :

 
OPResBundleRef bundle = manager->LoadBundle ("name");
 

The resource manager is usually a unique instance of class OPResMan, which can be obtained through OPResMan::Current.

The resource manager looks for the resource file in the following directories :

• %OPaC%/Resources/fr-CH-Windows
• %OPaC%/Resources/fr-CH
• %OPaC%/Resources/fr
• %OPaC%/fr-CH-Windows
• %OPaC%/fr-CH
• %OPaC%/fr

until it finds a matching file.

Using a resource

A textual resource is best handled through the automatic conversion mechanisms provided by class OPString. You can simply convert or initialise a string with a resource id :

 
OPStringRef text1 = id1;
OPStringRef text2 = bundle->RetResID (some_resource_index);
 

The corresponding resource bundle will be queried and the real data will be copied into the string buffer, which will serve as a cache, the first time the data is accessed. The cache can be explicitely flushed by calling method OPString::Invalidate.

Other resources not fitting into a string must be manipulated through the class manager's member functions :

 
void*     data = 0;
Size      size = 0;
OPResType type = OP_BRT_INVALID;
 
if (OPResMan::LockResource (id1, data, size, type)) {
    ...
    OPResMan::UnlockResource (id1);
}
 
if (OPResMan::QueryResource (id2, size, type)) {
    
    //  Create a temporary buffer for the resource   
    Card8* buffer = stack_alloc (Card8*, size);
    
    //  Copy the data from the resource to the buffer 
    OPResMan::CopyResource (id2, buffer, size);
    ...
}
 

where the LockResource/UnlockResource pair is the preferred way to access the data directly in memory, without requiring a copy. If the data must be copied anyway, use QueryResource to determine the size of the data and then CopyResource to copy it.