How to read a simple string resource

The simplest use of a resource file involves reading string resources.

Resources are defined in terms of structs. In general, structs need to be defined, assuming that pre-defined structs are not being used. In the following code fragments, a struct of type STRING is defined that has a single member of type LTEXT.

The resource file can contain just the following text:

// define structures

STRUCT STRING
    {
    LTEXT text;
    }

// define resources

RESOURCE STRING hello
    {
    text=Bonjour tout le monde!;
    }

From this, the resource compiler generates two files:

• the .rsc file containing the resource data; this is the resource file that must be referred to at run-time by the RResourceFile class in the C++ code.

• the .rsg file is a generated header file that contains #define statements for each resource defined in the source file. In the resource file generated here, the only resource is called hello and the generated header file contains:

  #define HELLO 1

  Note that the name in the generated header file is converted to upper case.

The file containing the C++ code must #include the .rsg file in order to have access to the resource ids generated by the resource compiler. For example, for a project called ReadText, this might be:

#include ReadText.rsg

The C++ program initialises the RResourceFile object, specifying the filename of the resource file:

    RResourceFile resourceFile;
    resourceFile.OpenL(fsSession,_L(Z:\\system\\data\\ReadText.rsc));

Because the resource file contains an RFile, it must use a session to the file server for its operations - this is the fsSession parameter to OpenL().

RResourceFile::AllocReadLC() is one of three functions that can be used to read a resource. It allocates a heap descriptor of sufficient length to contain the resource, reads in the binary data for the resource and pushes the heap descriptors address onto the cleanup stack. If a leave occurs while this heap descriptor is still on the cleanup stack, it is automatically popped off the cleanup stack and destroyed.

HBufC8* dataBuffer = resourceFile.AllocReadLC(HELLO);

The HELLO symbol is #defined to 1 by the statement in the #included .rsg file. This statement therefore reads resource number 1 from the .rsc file.

The resource data must be interpreted using a TResourceReader object. This provides access to the text string through a pointer descriptor, as the following code fragment shows:

TResourceReader theReader;
...
theReader.SetBuffer(datafBuffer);
TPtrC textdata = reader.ReadTPtrC();

In this example, once the resource data is no longer needed, the heap descriptor, dataBuffer, can be popped off the cleanup stack and destroyed:

CleanupStack::PopAndDestroy();

When all operations on the resource file are complete, the resource file can be closed:

resourceFile.Close();

Another example: consider a resource constructed from the following definition.

RESOURCE ARRAY anarray
{
items=
    {
    LBUF { txt="Esc"; },
    LBUF { txt="Enter"; },
    LBUF { txt="Tab"; },
    LBUF { txt="Del"; },
    LBUF { txt="Space"; }
    };
}

A TPtrC representing the second item can be constructed using the ReadTPtrC() function. The example simply takes the length of the text Enter:

// open the resource file
...
HBufC8* res = resourceFile.AllocReadLC(ANARRAY);
TResourceReader theReader;
...
TInt len;
len = (theReader.ReadTPtrC(1,res)).Length(); // len == 5
...

Resource file format

Resource compilation