<?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 is used to handle memory exhaustion. Errors in application programming
are handled with the panic mechanism. 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 &lt;tultextresourceutils.h&gt;

// 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-&gt;AppendL( _L("orking") ); //First string

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

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

strings-&gt;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."&lt;0x0001&gt;"Missed %N msgs from %U."&lt;0x0001&gt;"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>