Text resource +utility overview

Description

Usage

Applications +load and format resource strings from normal resources with static methods +of the 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 CCoeEnv for +efficiency reasons. If the pointer is not provided, the implementation uses +the CCoeEnv::Static method +internally to get it. The user can get a pointer to 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, 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). 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 TulTextResourceUtils.