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.