Symbian3/SDK/Source/GUID-D65D1EDC-5CB4-58C1-99B5-4495B6DA511F-GENID-1-8-1-3-1-1-8-1-5-1.dita
changeset 7 51a74ef9ed63
equal deleted inserted replaced
6:43e37759235e 7:51a74ef9ed63
       
     1 <?xml version="1.0" encoding="utf-8"?>
       
     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
       
     3 <!-- This component and the accompanying materials are made available under the terms of the License 
       
     4 "Eclipse Public License v1.0" which accompanies this distribution, 
       
     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
       
     6 <!-- Initial Contributors:
       
     7     Nokia Corporation - initial contribution.
       
     8 Contributors: 
       
     9 -->
       
    10 <!DOCTYPE concept
       
    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
       
    12 <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
       
    13 utility overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
       
    14 <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
       
    15 Resource Utility is part of the Symbian Text Utilities. It is an API class,
       
    16 which provides static methods for loading and formatting resource strings.
       
    17 The purpose of Text Resource Utility is to make localization of the software
       
    18 easier by allowing variable order in indexing of the key strings in the resource
       
    19 string. </p> <p>Text Resource Utility provides resource string loading and
       
    20 formatting methods for other subsystems. Through simple <codeph>Load()</codeph> and <codeph>Format()</codeph> operation
       
    21 calls, the user can access resource strings which may contain formatting parameters
       
    22 (<codeph>%U</codeph> for text or <codeph>%N</codeph> for numerical). Strings
       
    23 can contain multiple instances of the same parameter. The <codeph>0x0001</codeph> character
       
    24 has special meaning in strings; it is used to delimit different options for
       
    25 displayable string. The client of <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>TulTextResourceUtils</apiname></xref> is
       
    26 responsible for choosing the proper string to display from given options. </p> </section>
       
    27 <section id="GUID-BAEBDD2B-2A9D-4BE6-9078-7835CF9B4E05-GENID-1-8-1-3-1-1-8-1-5-1-2-2"><title>Architectural
       
    28 Relationships</title> <p>The implementation requires a <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>CCoeEnv</apiname></xref> instance
       
    29 (given as reference by the user or <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>CCoeEnv::Static</apiname></xref>)
       
    30 to access the resource files. </p> <p>All interface methods are static, so
       
    31 there is no need to explicitly allocate memory for the interface class. All
       
    32 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
       
    33 interface is accessed through the <codeph>tultextresourceutils.h</codeph> header
       
    34 file. Binaries are linked to the <codeph>etul.dll</codeph> library. </p> </section>
       
    35 <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
       
    36 load and format resource strings from normal resources with static methods
       
    37 of the <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>TulTextResourceUtils</apiname></xref> class.
       
    38 The loading is done with the <codeph>LoadL()</codeph> and <codeph>LoadLC()</codeph> methods
       
    39 and with the <codeph>Load()</codeph> method in situations where memory allocation
       
    40 from the heap is not possible. Formatting is done automatically after loading
       
    41 in the <codeph>LoadL()</codeph> and <codeph>LoadLC() </codeph> methods, but
       
    42 it can also be done separately with the <codeph>Format() </codeph> method
       
    43 in situations where memory allocation from the heap is not possible. </p> <p>For
       
    44 reading the resource strings with the<codeph> Load()</codeph>, <codeph>LoadL()</codeph> and <codeph>LoadLC()</codeph> methods,
       
    45 the user should provide a pointer to <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>CCoeEnv</apiname></xref> for
       
    46 efficiency reasons. If the pointer is not provided, the implementation uses
       
    47 the <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>CCoeEnv::Static</apiname></xref> method
       
    48 internally to get it. The user can get a pointer to <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>CCoeEnv</apiname></xref>,
       
    49 for example, via the <codeph>iEikonEnv</codeph> macro (for which see <codeph>&lt;eikdef.h&gt;</codeph>). </p> <p><b>Scalable
       
    50 UI Support</b> </p> <p>Different size displays can handle different length
       
    51 strings. To take full advantage of this fact, <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>TulTextResourceUtils</apiname></xref> supports
       
    52 resource strings with multiple options for string separated by <codeph>0x0001</codeph> character.
       
    53 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,
       
    54 it is the responsibility of the caller to parse the result and choose the
       
    55 proper string to display. </p> <p><b>Setting the Maximum Substring Length</b> </p> <p>This
       
    56 may be done in the text resources. Sub string maximum lengths can be localized
       
    57 separately for every language. </p> <p>The maximum sub string length is of
       
    58 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
       
    59 a number <codeph>[01..99]</codeph>. Please note that <codeph>NN</codeph> must
       
    60 always consist of two characters, in other words, if the sub string maximum
       
    61 length is eight characters, the value to be used is <codeph>08</codeph>, not
       
    62 plain <codeph>8</codeph>. </p> <p>If the number of characters exceeds the
       
    63 maximum length, the sub string is cut to fit and the last character is replaced
       
    64 with an ellipsis character. </p> <p><b>Error Handling</b> </p> <p>The leave
       
    65 mechanism is used to handle memory exhaustion. Errors in application programming
       
    66 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">
       
    67 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
       
    68 <tbody>
       
    69 <row>
       
    70 <entry><p><codeph>ETooFewArguments</codeph> </p> </entry>
       
    71 <entry><p>= 0: Unsolved parameters in the resource string. </p> </entry>
       
    72 </row>
       
    73 <row>
       
    74 <entry><p><codeph>ETooManyArguments</codeph> </p> </entry>
       
    75 <entry><p>= 1: Already solved all parameters in the resource string. </p> </entry>
       
    76 </row>
       
    77 <row>
       
    78 <entry><p><codeph>EKeyStringNotFound</codeph> </p> </entry>
       
    79 <entry><p>= 2: The key string was not found in formatting. </p> </entry>
       
    80 </row>
       
    81 <row>
       
    82 <entry><p><codeph>EInvalidIndex</codeph> </p> </entry>
       
    83 <entry><p>= 3: Invalid index in the Format method. </p> </entry>
       
    84 </row>
       
    85 <row>
       
    86 <entry><p><codeph>EDescriptorTooSmall</codeph> </p> </entry>
       
    87 <entry><p>= 4: Too small destination descriptor. </p> </entry>
       
    88 </row>
       
    89 <row>
       
    90 <entry><p><codeph>ECCoeEnvNotInitialized</codeph> </p> </entry>
       
    91 <entry><p>= 5: <codeph>CCoeEnv</codeph> not initialized. </p> </entry>
       
    92 </row>
       
    93 <row>
       
    94 <entry><p><codeph>EInvalidSubstitute</codeph> </p> </entry>
       
    95 <entry><p>= 6: Substituted string contains substring separator (i.e. 0x0001). </p> </entry>
       
    96 </row>
       
    97 </tbody>
       
    98 </tgroup>
       
    99 </table> <p><b>Example</b> </p> <p>The following example describes the usage
       
   100 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: */
       
   101 
       
   102 #include &lt;tultextresourceutils.h&gt;
       
   103 
       
   104 // Get CCoeEnv instance
       
   105 CEikonEnv* iEikonEnv = CEikonEnv::Static();
       
   106 
       
   107 /*
       
   108 *   One TInt to add:
       
   109 */
       
   110 
       
   111 //(In .loc -file)
       
   112 #define TEXT_EXAMPLE "You have %N undone tasks."
       
   113 
       
   114 //(In .rss -file)
       
   115 RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; }
       
   116 
       
   117 //(In the .cpp -file)
       
   118 TInt number( 324 );
       
   119 
       
   120 //
       
   121 //iEikonEnv is needed for loading the resource string.
       
   122 //
       
   123 HBufC* stringholder = TulTextResourceUtils::LoadL( R_TEXT_EXAMPLE, number, iEikonEnv );
       
   124 
       
   125 //
       
   126 //The TInt in number is added to the resource string. The result is
       
   127 //that stringholder points to a heap descriptor containing string:
       
   128 //"You have 324 undone tasks."
       
   129 //
       
   130 
       
   131 /*
       
   132 *   Several strings to add:
       
   133 */
       
   134 
       
   135 //(In a .loc -file)
       
   136 #define TEXT_EXAMPLE "I'm %2U%1U %3U%0U fine." 
       
   137 
       
   138 //(In an .rss -file)
       
   139 RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; }
       
   140 
       
   141 //(In the .cpp -file)
       
   142 CDesCArrayFlat* strings = new CDesCArrayFlat( 4 );
       
   143 CleanupStack::PushL( strings );
       
   144 
       
   145 strings-&gt;AppendL( _L("orking") ); //First string
       
   146 
       
   147 strings-&gt;AppendL( _L("ll") ); //Second string
       
   148 
       
   149 strings-&gt;AppendL( _L("sti") ); //Third string
       
   150 
       
   151 strings-&gt;AppendL( _L("w") ); //Fourth string
       
   152 
       
   153 //
       
   154 //iEikonEnv is needed for loading the resource string.
       
   155 //
       
   156 HBufC* stringholder = TulTextResourceUtils::LoadL( R_TEXT_EXAMPLE, *strings, iEikonEnv );
       
   157 
       
   158 //
       
   159 //The strings in strings are added to the resource string. The result is
       
   160 //that stringholder points to a heap descriptor containing string:
       
   161 //"I'm still working fine."
       
   162 //
       
   163 
       
   164 /*
       
   165 * Scalable UI support
       
   166 */
       
   167 //(In .loc -file)
       
   168 #define TEXT_EXAMPLE "You have missed %N messages from %U."&lt;0x0001&gt;"Missed %N msgs from %U."&lt;0x0001&gt;"Missed %N msgs."
       
   169 
       
   170 //(In .rss -file)
       
   171 RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; }
       
   172 
       
   173 //(In the .cpp -file)
       
   174 TInt number( 12 );
       
   175 _LIT(name, “John Doe”);
       
   176 
       
   177 //
       
   178 //iEikonEnv is needed for loading the resource string.
       
   179 //
       
   180 HBufC* stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE,name,number,iEikonEnv);
       
   181 
       
   182 //
       
   183 //The number and name are added to the resource string. The result is
       
   184 //that stringholder points to a heap descriptor containing string:
       
   185 //"You have missed 12 messages from John Doe.\001Missed 12 msgs from John
       
   186 // Doe.\001Missed 12 msgs."
       
   187 //
       
   188 
       
   189 CleanupStack::PopAndDestroy(); //strings
       
   190 </codeblock> <p>For more information on individual methods, please see the
       
   191 reference API for <xref href="GUID-E19C9DB8-2C8B-366B-B650-2673B066256D.dita"><apiname>TulTextResourceUtils</apiname></xref>. </p> </section>
       
   192 </conbody></concept>