Reading a String Resource

The simplest use of a resource file involves reading string resources and interpreting the source data.

Context

Resources are defined in terms of structs which are accessed and read by the RResourceFile class, and interpreted by the TResourceReader. An application may also use resources from multiple files simultaneously. See Resource File examples for more information.

Consider a sample resource file where a struct of STRING is defined having a single member of type LTEXT:

// define structures
STRUCT STRING
    {
    LTEXT text;
    }
// define resources
RESOURCE STRING hello
    {
    text=Bonjour tout le monde!;
    }

Steps

Compile the resource file using the resource compiler (rcomp) to generate an .rsc file and an .rsg file.
For information on resource compiler, see Symbian^3 Tools Guide > Building.
1. .rsc file contains the resource data; this is the resource file that must be referred to at run-time by the RResourceFile class in the C++ code.
2. .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.
#include the .rsg file in the file containing the C++ code, to access the resource IDs generated by the resource compiler. For example, for a project refered as ReadText, this might be:
```
#include ReadText.rsg
```
Initialize the RResourceFile object in the C++ program, specifying the name of the resource file:
```
    
RResourceFile resourceFile;
resourceFile.OpenL( fsSession,_L( Z:\\system\\data\\ReadText.rsc ) );
```
Note: To access the resource file contents, a session with the file server must be started using an instance of RFs class.
Use one of the three functions (RResourceFile::AllocReadLC(), RResourceFile::AllocReadL() or RResourceFile::ReadL() to read a resource as shown in the following code fragment:
```
HBufC8* dataBuffer = resourceFile.AllocReadLC( HELLO );
```
Interpret the resource data using a TResourceReader object. This provides access to the text string through a pointer descriptor as shown in the following code fragment:
```
TResourceReader theReader;
...
theReader.SetBuffer( datafBuffer );
TPtrC textdata = reader.ReadTPtrC();
```

Results

In this example, once the resource data is no longer needed, the heap descriptor, dataBuffer, can be removed from the cleanup stack and destroyed as shown in the code fragment:

CleanupStack::PopAndDestroy();

When all operations on the resource file are complete, the resource file can be closed using the RResourceFile::close() function as:

resourceFile.Close();

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
...

Related concepts

Resource files