String Loader API: Technical Specification

Type of the Interface

• A method call. All interface methods are static, so there is no need to explicitly allocate memory for the interface class.

Interface Class Structure

All functionality is accessed through exported methods of the StringLoader class.

Usage

Applications load and format resource strings from normal resources with static methods of the StringLoader 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>).

Protocol

Since all the exported methods are static, they can be used without explicitly creating an actual instance of the interface class. Thus, the calling sequence is very simple; just call directly the interface operations.

Scalable UI support

Different size displays can handle different length strings. To take full advantage of this fact, StringLoader 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). StringLoader returns all strings, it is responsibility of the caller to parse the result and choose the proper string to display.

See the example in the Example section.

Setting the Maximum Sub String 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, i.e. 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 of the Symbian OS environment is used to handle memory exhaustion. Errors in application programming are handled with the panic mechanism of the Symbian OS environment. 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).

Extensions to the API

None.

Example

The following example describes the usage of the String Loader component:

/*  Using examples: */
#include <stringloader.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 = StringLoader::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 = StringLoader::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 = StringLoader::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

Detailed Description

StringLoader

StringLoader exports a static interface for the user.

Static void Load(TDes& aDest, TInt aResourceId, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string without memory allocation. The loaded string is stored in the destination TDes&. The destination descriptor must be long enough to hold the return value, or a panic occurs. Also, if CCoeEnv is not initialized, i.e. CCoeEnv::Static() returns NULL, panic will occur.

Parameters:

Static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, TInt aSubs)

This formats a resource string without memory allocation. The formatted string is stored in the destination TDes&. The destination descriptor must be long enough to hold the return value. Otherwise a panic occurs. In aPosition, -1 means that there is no index in the key string.

Parameters:

Static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, const TDesC& aSubs)

This formats a resource string without memory allocation. The formatted string is stored in the destination TDes&. The destination descriptor must be long enough to hold the return value. Otherwise a panic occurs. In aPosition, -1 means that there is no index in the key string.

Parameters:

Static HBufC* LoadL(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation. The calling program must destroy the heap descriptor when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the resource string.

Static HBufC* LoadLC(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation and pushes the string onto the cleanup stack. The calling program must destroy the heap descriptor, and remember to pop it from the cleanup stack when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the resource string. This pointer is in the cleanup stack.

Static HBufC* LoadL(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation and replaces all %N strings in it with a replacement TInt. The calling program must destroy the heap descriptor when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string.

Static HBufC* LoadLC(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL)

Reads a resource string with memory allocation, replaces all %N strings in it with a replacement TInt and pushes the string onto the cleanup stack. The calling program must destroy the heap descriptor, and remember to pop it from the cleanup stack when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string. This pointer is in the cleanup stack.

Static HBufC* LoadL(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation and replaces all %N strings in it with a replacement TDesC. The calling program must destroy the heap descriptor when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string.

Static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation, replaces all %N strings in it with a replacement TDesC and pushes the string onto the cleanup stack. The calling program must destroy the heap descriptor, and remember to pop it from the cleanup stack when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string. This pointer is in the cleanup stack.

Static HBufC* LoadL(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation, replaces all %N strings in it with a replacement TInt and all %U strings in it with a replacement string. The calling program must destroy the heap descriptor when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string.

Static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation, replaces all %N strings in it with a replacement TInt and all %U strings in it with a replacement string. Then it pushes the string onto the cleanup stack. The calling program must destroy the heap descriptor, and remember to pop it from the cleanup stack when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string. This pointer is in the cleanup stack.

Static HBufC* LoadL(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation and replaces the %(index)N strings in it with replacement TInts from an array. The calling program must destroy the heap descriptor when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string.

Static HBufC* LoadLC(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation, replaces the %(index)N strings in it with replacement TInts from an array and pushes the string onto the cleanup stack. The calling program must destroy the heap descriptor, and remember to pop it from the cleanup stack when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string. This pointer is in the cleanup stack.

Static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation and replaces the %(index)U strings in it with replacement strings from an array. The calling program must destroy the heap descriptor when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string.

Static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation, replaces the %(index)U strings in it with replacement strings from an array and pushes the string onto the cleanup stack. The calling program must destroy the heap descriptor, and remember to pop it from the cleanup stack when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string. This pointer is in the cleanup stack.

Static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation, replaces the %(index)U strings in it with replacement strings from an array and the %(index)N strings in it with replacement TInts from another array. The calling program must destroy the heap descriptor when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string.

Static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL)

This reads a resource string with memory allocation, replaces the %(index)U strings in it with replacement strings from an array and the %(index)N strings in it with replacement TInts from another array and pushes the string onto the cleanup stack. The calling program must destroy the heap descriptor and remember to pop it from the cleanup stack when it is no longer needed.

Parameters:

Return value:

The operation returns a pointer to the heap descriptor holding the formatted resource string. This pointer is in the cleanup stack.

Code Architecture

The interface is accessed through the StringLoader.H header file. Binaries are linked to the commonengine.DLL library.