--- a/Symbian3/SDK/Source/GUID-D65D1EDC-5CB4-58C1-99B5-4495B6DA511F-GENID-1-8-1-3-1-1-8-1-5-1.dita	Wed Mar 31 11:11:55 2010 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,192 +0,0 @@
-<?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-GENID-1-8-1-3-1-1-8-1-5-1" xml:lang="en"><title>Text resource
-utility overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<section id="GUID-C6857C66-B599-4AA0-9ABE-469ADDE4BA5D-GENID-1-8-1-3-1-1-8-1-5-1-2-1"><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-GENID-1-8-1-3-1-1-8-1-5-1-2-2"><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-GENID-1-8-1-3-1-1-8-1-5-1-2-3"><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-GENID-1-8-1-3-1-1-8-1-5-1-2-3-10" 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-GENID-1-8-1-3-1-1-8-1-5-1-2-3-15">
-<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-GENID-1-8-1-3-1-1-8-1-5-1-2-3-18" 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