|
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><eikdef.h></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 <tultextresourceutils.h> |
|
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->AppendL( _L("orking") ); //First string |
|
146 |
|
147 strings->AppendL( _L("ll") ); //Second string |
|
148 |
|
149 strings->AppendL( _L("sti") ); //Third string |
|
150 |
|
151 strings->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."<0x0001>"Missed %N msgs from %U."<0x0001>"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> |