<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-D65D1EDC-5CB4-58C1-99B5-4495B6DA511F" xml:lang="en"><title>Text

resource utility overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-C6857C66-B599-4AA0-9ABE-469ADDE4BA5D"><title>Purpose</title> <p>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. </p> <p>Text Resource Utility provides

resource string loading and formatting methods for other subsystems. Through

simple <codeph>Load()</codeph> and <codeph>Format()</codeph> operation calls,

the user can access resource strings which may contain formatting parameters

(<codeph>%U</codeph> for text or <codeph>%N</codeph> for numerical). Strings

can contain multiple instances of the same parameter. The <codeph>0x0001</codeph> character

has special meaning in strings; it is used to delimit different options for

displayable string. The client of <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>TulTextResourceUtils</apiname></xref> is

responsible for choosing the proper string to display from given options. </p> </section>

<section id="GUID-BAEBDD2B-2A9D-4BE6-9078-7835CF9B4E05"><title>Architectural Relationships</title> <p>The implementation

requires a <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>CCoeEnv</apiname></xref> instance

(given as reference by the user or <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>CCoeEnv::Static</apiname></xref>)

to access the resource files. </p> <p>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 <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>TulTextResourceUtils</apiname></xref> class. </p> <p>The

interface is accessed through the <codeph>tultextresourceutils.h</codeph> header

file. Binaries are linked to the <codeph>etul.dll</codeph> library. </p> </section>

<section id="GUID-3694DAEC-D25F-4E28-87EA-E1D230571003"><title>Description</title> <p><b>Usage</b> </p> <p>Applications load

and format resource strings from normal resources with static methods of the <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>TulTextResourceUtils</apiname></xref> class. The loading

is done with the <codeph>LoadL()</codeph> and <codeph>LoadLC()</codeph> methods

and with the <codeph>Load()</codeph> method in situations where memory allocation

from the heap is not possible. Formatting is done automatically after loading

in the <codeph>LoadL()</codeph> and <codeph>LoadLC() </codeph> methods, but

it can also be done separately with the <codeph>Format() </codeph> method

in situations where memory allocation from the heap is not possible. </p> <p>For

reading the resource strings with the<codeph> Load()</codeph>, <codeph>LoadL()</codeph> and <codeph>LoadLC()</codeph> methods,

the user should provide a pointer to <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>CCoeEnv</apiname></xref> for

efficiency reasons. If the pointer is not provided, the implementation uses

the <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>CCoeEnv::Static</apiname></xref> method

internally to get it. The user can get a pointer to <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>CCoeEnv</apiname></xref>,

for example, via the <codeph>iEikonEnv</codeph> macro (for which see <codeph>&lt;eikdef.h&gt;</codeph>). </p> <p><b>Scalable

UI Support</b> </p> <p>Different size displays can handle different length

strings. To take full advantage of this fact, <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>TulTextResourceUtils</apiname></xref> supports

resource strings with multiple options for string separated by <codeph>0x0001</codeph> character.

Each such string can contain same or different sub string keys (<codeph>%U</codeph> and <codeph>%N</codeph>). <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>TulTextResourceUtils</apiname></xref> returns all strings,

it is the responsibility of the caller to parse the result and choose the

proper string to display. </p> <p><b>Setting the Maximum Substring Length</b> </p> <p>This

may be done in the text resources. Sub string maximum lengths can be localized

separately for every language. </p> <p>The maximum sub string length is of

the format: </p> <codeblock id="GUID-AA1192AA-292D-59B4-9235-178AD1CC6681" xml:space="preserve">%U[NN] </codeblock> <p>where <codeph>NN</codeph> is

a number <codeph>[01..99]</codeph>. Please note that <codeph>NN</codeph> must

always consist of two characters, in other words, if the sub string maximum

length is eight characters, the value to be used is <codeph>08</codeph>, not

plain <codeph>8</codeph>. </p> <p>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. </p> <p><b>Error Handling</b> </p> <p>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: </p> <table id="GUID-3320467E-C326-523F-9B44-EB8BC916BFA5">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p><codeph>ETooFewArguments</codeph> </p> </entry>

<entry><p>= 0: Unsolved parameters in the resource string. </p> </entry>

</row>

<row>

<entry><p><codeph>ETooManyArguments</codeph> </p> </entry>

<entry><p>= 1: Already solved all parameters in the resource string. </p> </entry>

</row>

<row>

<entry><p><codeph>EKeyStringNotFound</codeph> </p> </entry>

<entry><p>= 2: The key string was not found in formatting. </p> </entry>

</row>

<row>

<entry><p><codeph>EInvalidIndex</codeph> </p> </entry>

<entry><p>= 3: Invalid index in the Format method. </p> </entry>

</row>

<row>

<entry><p><codeph>EDescriptorTooSmall</codeph> </p> </entry>

<entry><p>= 4: Too small destination descriptor. </p> </entry>

</row>

<row>

<entry><p><codeph>ECCoeEnvNotInitialized</codeph> </p> </entry>

<entry><p>= 5: <codeph>CCoeEnv</codeph> not initialized. </p> </entry>

</row>

<row>

<entry><p><codeph>EInvalidSubstitute</codeph> </p> </entry>

<entry><p>= 6: Substituted string contains substring separator (i.e. 0x0001). </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Example</b> </p> <p>The following example describes the usage

of the Text Resource Utility component: </p> <codeblock id="GUID-6B0C9F3E-DC2C-511B-B58B-03CF363B794D" xml:space="preserve">/*  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

</codeblock> <p>For more information on individual methods, please see the

reference API for <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>TulTextResourceUtils</apiname></xref>. </p> </section>

</conbody></concept>