--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-D65D1EDC-5CB4-58C1-99B5-4495B6DA511F.dita	Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,192 @@
+<?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>
\ No newline at end of file