Text resource utility overview

Purpose

Text Resource Utility is part of the Symbian Text Utilities. It is an API class, which provides static methods for loading and formatting resource strings. The purpose of Text Resource Utility is to make localization of the software easier by allowing variable order in indexing of the key strings in the resource string.

Text Resource Utility provides resource string loading and formatting methods for other subsystems. Through simple Load() and Format() operation calls, the user can access resource strings which may contain formatting parameters (%U for text or %N for numerical). Strings can contain multiple instances of the same parameter. The 0x0001 character has special meaning in strings; it is used to delimit different options for displayable string. The client of [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TulTextResourceUtils']]]TulTextResourceUtils is responsible for choosing the proper string to display from given options.

Architectural Relationships

The implementation requires a [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TulTextResourceUtils']]]CCoeEnv instance (given as reference by the user or [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TulTextResourceUtils']]]CCoeEnv::Static) to access the resource files.

All interface methods are static, so there is no need to explicitly allocate memory for the interface class. All functionality is accessed through exported methods of the [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TulTextResourceUtils']]]TulTextResourceUtils class.

The interface is accessed through the tultextresourceutils.h header file. Binaries are linked to the etul.dll library.

Description

Usage

Applications load and format resource strings from normal resources with static methods of the [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TulTextResourceUtils']]]TulTextResourceUtils class. The loading is done with the LoadL() and LoadLC() methods and with the Load() method in situations where memory allocation from the heap is not possible. Formatting is done automatically after loading in the LoadL() and LoadLC() methods, but it can also be done separately with the Format() method in situations where memory allocation from the heap is not possible.

For reading the resource strings with the Load(), LoadL() and LoadLC() methods, the user should provide a pointer to [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TulTextResourceUtils']]]CCoeEnv for efficiency reasons. If the pointer is not provided, the implementation uses the [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TulTextResourceUtils']]]CCoeEnv::Static method internally to get it. The user can get a pointer to [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TulTextResourceUtils']]]CCoeEnv, for example, via the iEikonEnv macro (for which see <eikdef.h>).

Scalable UI Support

Different size displays can handle different length strings. To take full advantage of this fact, [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TulTextResourceUtils']]]TulTextResourceUtils supports resource strings with multiple options for string separated by 0x0001 character. Each such string can contain same or different sub string keys (%U and %N). [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TulTextResourceUtils']]]TulTextResourceUtils returns all strings, it is the responsibility of the caller to parse the result and choose the proper string to display.

Setting the Maximum Substring Length

This may be done in the text resources. Sub string maximum lengths can be localized separately for every language.

The maximum sub string length is of the format:

%U[NN]

where NN is a number [01..99]. Please note that NN must always consist of two characters, in other words, if the sub string maximum length is eight characters, the value to be used is 08, not plain 8.

If the number of characters exceeds the maximum length, the sub string is cut to fit and the last character is replaced with an ellipsis character.

Error Handling

The leave mechanism is used to handle memory exhaustion. Errors in application programming are handled with the panic mechanism. The error codes used are as follows:

`ETooFewArguments`	= 0: Unsolved parameters in the resource string.
`ETooManyArguments`	= 1: Already solved all parameters in the resource string.
`EKeyStringNotFound`	= 2: The key string was not found in formatting.
`EInvalidIndex`	= 3: Invalid index in the Format method.
`EDescriptorTooSmall`	= 4: Too small destination descriptor.
`ECCoeEnvNotInitialized`	= 5: `CCoeEnv` not initialized.
`EInvalidSubstitute`	= 6: Substituted string contains substring separator (i.e. 0x0001).

Example

The following example describes the usage of the Text Resource Utility component:

/*  Using examples: */

#include <tultextresourceutils.h>

// Get CCoeEnv instance
CEikonEnv* iEikonEnv = CEikonEnv::Static();

/*
*   One TInt to add:
*/

//(In .loc -file)
#define TEXT_EXAMPLE "You have %N undone tasks."

//(In .rss -file)
RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; }

//(In the .cpp -file)
TInt number( 324 );

//
//iEikonEnv is needed for loading the resource string.
//
HBufC* stringholder = TulTextResourceUtils::LoadL( R_TEXT_EXAMPLE, number, iEikonEnv );

//
//The TInt in number is added to the resource string. The result is
//that stringholder points to a heap descriptor containing string:
//"You have 324 undone tasks."
//

/*
*   Several strings to add:
*/

//(In a .loc -file)
#define TEXT_EXAMPLE "I'm %2U%1U %3U%0U fine." 

//(In an .rss -file)
RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; }

//(In the .cpp -file)
CDesCArrayFlat* strings = new CDesCArrayFlat( 4 );
CleanupStack::PushL( strings );

strings->AppendL( _L("orking") ); //First string

strings->AppendL( _L("ll") ); //Second string

strings->AppendL( _L("sti") ); //Third string

strings->AppendL( _L("w") ); //Fourth string

//
//iEikonEnv is needed for loading the resource string.
//
HBufC* stringholder = TulTextResourceUtils::LoadL( R_TEXT_EXAMPLE, *strings, iEikonEnv );

//
//The strings in strings are added to the resource string. The result is
//that stringholder points to a heap descriptor containing string:
//"I'm still working fine."
//

/*
* Scalable UI support
*/
//(In .loc -file)
#define TEXT_EXAMPLE "You have missed %N messages from %U."<0x0001>"Missed %N msgs from %U."<0x0001>"Missed %N msgs."

//(In .rss -file)
RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; }

//(In the .cpp -file)
TInt number( 12 );
_LIT(name, “John Doe”);

//
//iEikonEnv is needed for loading the resource string.
//
HBufC* stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE,name,number,iEikonEnv);

//
//The number and name are added to the resource string. The result is
//that stringholder points to a heap descriptor containing string:
//"You have missed 12 messages from John Doe.\001Missed 12 msgs from John
// Doe.\001Missed 12 msgs."
//

CleanupStack::PopAndDestroy(); //strings

For more information on individual methods, please see the reference API for [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TulTextResourceUtils']]]TulTextResourceUtils.