1 /* |
1 /* |
2 * Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies). |
2 * Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies). |
3 * All rights reserved. |
3 * All rights reserved. |
4 * This component and the accompanying materials are made available |
4 * This component and the accompanying materials are made available |
5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members |
5 * under the terms of "Eclipse Public License v1.0" |
6 * which accompanies this distribution, and is available |
6 * which accompanies this distribution, and is available |
7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
8 * |
8 * |
9 * Initial Contributors: |
9 * Initial Contributors: |
10 * Nokia Corporation - initial contribution. |
10 * Nokia Corporation - initial contribution. |
11 * |
11 * |
12 * Contributors: |
12 * Contributors: |
13 * |
13 * |
14 * Description: String Loader API provides methods for loading resource |
14 * Description: |
15 * strings and formatting them. |
|
16 * |
15 * |
17 */ |
16 */ |
|
17 |
|
18 |
18 |
19 |
19 #ifndef STRINGLOADER_H |
20 #ifndef STRINGLOADER_H |
20 #define STRINGLOADER_H |
21 #define STRINGLOADER_H |
21 |
22 |
22 // INCLUDE FILES |
23 #include <coemain.h> |
23 #include <coemain.h> |
24 #include <biditext.h> |
24 #include <biditext.h> |
|
25 |
25 |
26 // CLASS DECLARATION |
26 class CCoeEnv; |
27 |
27 |
|
28 NONSHARABLE_CLASS(StringLoader) |
28 /** |
29 /** |
29 * Class provides methods to load and format resource strings. |
30 @deprecated |
30 * String Loader API provides an interface to load and format resource strings |
31 @see TulTextResourceUtils |
31 * that may contain parameter(s) (\%U for text or or \%N for numerical). |
32 @note For compatibility with S60 only |
32 * Resource strings are usually defined in an RSS file. |
|
33 * |
|
34 * The API consists of the StringLoader class. All methods are static, so there is |
|
35 * no need to explicitly allocate memory for the interface class. |
|
36 * The implementation needs a CCoeEnv instance to access for example the |
|
37 * resource files. |
|
38 * |
|
39 * |
|
40 * Usage: |
|
41 * |
|
42 * Applications load and format resource strings from normal resources with |
|
43 * static methods of the StringLoader class. The loading is done with the LoadL |
|
44 * and LoadLC methods and with the Load method in situations where memory |
|
45 * allocation from the heap is not possible. Formatting is done automatically |
|
46 * after loading in the LoadL and LoadLC methods, but it can also be done |
|
47 * separately with the Format method in situations where memory allocation from |
|
48 * the heap is not possible. For reading the resource strings with the Load, |
|
49 * LoadL and LoadLC methods, the user should provide a pointer to CCoeEnv for |
|
50 * efficiency reasons. If the pointer is not provided, the implementation uses |
|
51 * the CCoeEnv::Static method internally to get it. |
|
52 * |
|
53 * Different size displays can handle different length strings. To take full |
|
54 * advantage of this fact, StringLoader supports resource strings with multiple |
|
55 * options for string separated by 0x0001 character. Each such string can |
|
56 * contain same or different sub string keys (\%U and \%N). StringLoader returns |
|
57 * all strings, it is responsibility of the caller to parse the result and |
|
58 * choose the proper string to display. |
|
59 * |
|
60 * Setting the maximum sub string length may be done in the text resources. Sub |
|
61 * string maximum lengths can be localized separately for every language. |
|
62 * The maximum sub string length is of the format: \%U[NN] |
|
63 * where NN is a number [01..99]. Please note that NN must always consist of two |
|
64 * characters, i.e. if the sub string maximum length is eight characters, the |
|
65 * value to be used is 08, not plain 8. If the number of characters exceeds the |
|
66 * maximum length, the sub string is cut to fit and the last character is |
|
67 * replaced with an ellipsis character. |
|
68 * |
|
69 * The following examples describe the usage of the String Loader API. |
|
70 * |
|
71 * Usage when one TInt is added: |
|
72 * |
|
73 * @code |
|
74 * // In .loc -file |
|
75 * // #define text_example "You have %N undone tasks." |
|
76 * |
|
77 * // In .rss -file |
|
78 * // RESOURCE TBUF r_text_example { buf = text_example; } |
|
79 * |
|
80 * // (In the .cpp -file) |
|
81 * #include <stringloader.h> |
|
82 * |
|
83 * // Get CCoeEnv instance |
|
84 * CEikonEnv* iEikonEnv = CEikonEnv::Static(); |
|
85 * |
|
86 * TInt number( 324 ); |
|
87 * |
|
88 * // Method reads a resource string with memory allocation |
|
89 * // and replaces all %N-strings in it with a replacement TInt. |
|
90 * // The heap descriptor must be destroyed when it is no longer needed. |
|
91 * // iEikonEnv is needed for loading the resource string. |
|
92 * HBufC* stringholder = StringLoader::LoadL( R_TEXT_EXAMPLE, number, iEikonEnv ); |
|
93 * |
|
94 * // The 'number' is added to the resource string. The result is |
|
95 * // that stringholder points to a heap descriptor containing string: |
|
96 * // "You have 324 undone tasks." |
|
97 * |
|
98 * // Delete the heap descriptor |
|
99 * delete stringholder; |
|
100 * @endcode |
|
101 * |
|
102 * |
|
103 * Usage when several strings are added: |
|
104 * |
|
105 * Index can be included to parameters. Several parameters can have same index, |
|
106 * if same replacement is needed multiple times. |
|
107 * |
|
108 * @code |
|
109 * // In .loc -file |
|
110 * // #define text_example "I'm %2U%1U %3U%0U fine." |
|
111 * |
|
112 * // In .rss -file |
|
113 * // RESOURCE TBUF r_text_example { buf = text_example; } |
|
114 * |
|
115 * // In the .cpp -file |
|
116 * #include <stringloader.h> |
|
117 * |
|
118 * // Get CCoeEnv instance |
|
119 * CEikonEnv* iEikonEnv = CEikonEnv::Static(); |
|
120 * |
|
121 * CDesCArrayFlat* strings = new CDesCArrayFlat( 4 ); |
|
122 * CleanupStack::PushL( strings ); |
|
123 * |
|
124 * strings->AppendL( _L("orking") ); //First string |
|
125 * |
|
126 * strings->AppendL( _L("ll") ); //Second string |
|
127 * |
|
128 * strings->AppendL( _L("sti") ); //Third string |
|
129 * |
|
130 * strings->AppendL( _L("w") ); //Fourth string |
|
131 * |
|
132 * // Method reads a resource string with memory allocation and replaces |
|
133 * // the %(index)U strings in it with replacement strings from an array. |
|
134 * // The heap descriptor must be destroyed when it is no longer needed. |
|
135 * // iEikonEnv is needed for loading the resource string. |
|
136 * HBufC* stringholder = StringLoader::LoadL( R_TEXT_EXAMPLE, *strings, iEikonEnv ); |
|
137 * |
|
138 * // Four strings are added to the resource string. The result is |
|
139 * // that stringholder points to a heap descriptor containing string: |
|
140 * // "I'm still working fine." |
|
141 * |
|
142 * // Pop and delete strings array |
|
143 * CleanupStack::PopAndDestroy(); |
|
144 * |
|
145 * // Delete the heap descriptor |
|
146 * delete stringholder; |
|
147 * @endcode |
|
148 * |
|
149 * |
|
150 * Usage with scalable UI support: |
|
151 * |
|
152 * @code |
|
153 * // In .loc -file |
|
154 * // #define TEXT_EXAMPLE "You have missed %N messages from %U."<0x0001>"Missed %N msgs from %U."<0x0001>"Missed %N msgs." |
|
155 * |
|
156 * // In .rss -file |
|
157 * // RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; } |
|
158 * |
|
159 * // In the .cpp -file |
|
160 * #include <stringloader.h> |
|
161 * |
|
162 * // Get CCoeEnv instance |
|
163 * CEikonEnv* iEikonEnv = CEikonEnv::Static(); |
|
164 * |
|
165 * TInt number( 12 ); |
|
166 * _LIT(name, "John Doe"); |
|
167 * |
|
168 * // Method reads a resource string with memory allocation, |
|
169 * // replaces all %N strings in it with a replacement TInt and |
|
170 * // all %U strings in it with a replacement string. |
|
171 * // The heap descriptor must be destroyed when it is no longer needed. |
|
172 * // iEikonEnv is needed for loading the resource string. |
|
173 * HBufC* stringholder = StringLoader::LoadL( R_TEXT_EXAMPLE, name, number, iEikonEnv ); |
|
174 * |
|
175 * // The number and name are added to the resource string. The result is |
|
176 * // that stringholder points to a heap descriptor containing string: |
|
177 * // "You have missed 12 messages from John Doe.\001Missed 12 msgs from John |
|
178 * // Doe.\001Missed 12 msgs." |
|
179 * |
|
180 * // Delete the heap descriptor |
|
181 * delete stringholder; |
|
182 * @endcode |
|
183 * |
|
184 * |
|
185 * Error handling: |
|
186 * |
|
187 * The leave mechanism of the Symbian OS environment is used to handle memory |
|
188 * exhaustion. The panic mechanism is used to handle programming errors while |
|
189 * debugging. RStringLoader panics for seven different reasons. The panic |
|
190 * category is named STRINGLOADER. The panic codes are: |
|
191 * |
|
192 * - ETooFewArguments = 0 (Unsolved parameters in resource string.) |
|
193 * - ETooManyArguments = 1 (Already solved all parameters in resource string.) |
|
194 * - EKeyStringNotFound = 2 (The key string wasn't found in formatting.) |
|
195 * - EInvalidIndex = 3 (Invalid index in Format-method) |
|
196 * - EDescriptorTooSmall = 4 (Too small destination descriptor.) |
|
197 * - ECCoeEnvNotInitialized = 5 (CCoeEnv is not initialized) |
|
198 * - EInvalidSubstitute = 6 (Substituted string contains KSubStringSeparator) |
|
199 * |
|
200 * @lib commonengine.lib |
|
201 * @since S60 2.0 |
|
202 */ |
33 */ |
203 class StringLoader |
|
204 { |
34 { |
205 public: |
35 public: |
206 |
36 IMPORT_C static void Load(TDes& aDest, TInt aResourceId, CCoeEnv* aLoaderEnv = NULL); |
207 /** |
37 IMPORT_C static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, TInt aSubs); |
208 * Load( TDes&, TInt ) reads a resource string without memory |
38 IMPORT_C static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, const TDesC& aSubs); |
209 * allocation. The loaded string is stored in the destination TDes&. |
39 IMPORT_C static HBufC* LoadL(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL); |
210 * Because this method doesn't allocate memory the destination |
40 IMPORT_C static HBufC* LoadL(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL); |
211 * descriptor must be long enough. |
41 IMPORT_C static HBufC* LoadL(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL); |
212 * |
42 IMPORT_C static HBufC* LoadL(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL); |
213 * @param aResourceId The numeric ID of the resource string to be read. |
43 IMPORT_C static HBufC* LoadL(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL); |
214 * @param aDest Reference to the descriptor where the resource string |
44 IMPORT_C static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL); |
215 * is loaded. |
45 IMPORT_C static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL); |
216 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
46 IMPORT_C static HBufC* LoadLC(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL); |
217 * give this, CCoeEnv::Static is called to get it. |
47 IMPORT_C static HBufC* LoadLC(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL); |
218 * |
48 IMPORT_C static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL); |
219 * @panic ECCoeEnvNotInitialized Parameter aLoaderEnv is NULL and |
49 IMPORT_C static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL); |
220 * CCoeEnv::Static returned NULL. |
50 IMPORT_C static HBufC* LoadLC(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL); |
221 */ |
51 IMPORT_C static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL); |
222 IMPORT_C static void Load( TDes& aDest, TInt aResourceId, |
52 IMPORT_C static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL); |
223 CCoeEnv* aLoaderEnv = NULL ); |
|
224 |
|
225 /** |
|
226 * Format( TDes&, TDesC&, TInt, TInt ) formats a resource string without |
|
227 * memory allocation. The formatted string is stored in the destination |
|
228 * TDes&. Because this method doesn't allocate memory the destination |
|
229 * descriptor must be long enough. In aPosition -1 means that there is |
|
230 * no index in the key string and all \%N-strings in the original string |
|
231 * are replaced with aSubs. In debug builds the Symbian OS panic |
|
232 * mechanism is used to notify programming errors. |
|
233 * |
|
234 * @param aDest Reference to the descriptor where the resource string |
|
235 * is formatted. |
|
236 * @param aSource Reference to the original string. |
|
237 * @param aPosition The index of the key string. |
|
238 * @param aSubs The replacing TInt. |
|
239 * |
|
240 * @panic EInvalidIndex In debug build if the index of the key string |
|
241 * is invalid. |
|
242 * @panic EDescriptorTooSmall In debug build if the length of the |
|
243 * destination descriptor is to small. |
|
244 * @panic EKeyStringNotFound In debug build if the key string 'N' wasn't |
|
245 * found, aDest is empty. |
|
246 * |
|
247 * One small sample describing the usage of the method. |
|
248 * @code |
|
249 * // Load example string "%0N %1N" defined in rss- and loc-files. |
|
250 * // %0N stands for area code and %1N for phone number. |
|
251 * HBufC* telFormat = StringLoader::LoadLC( R_TEL_FORMAT, iEikonEnv ); |
|
252 * |
|
253 * // The replacing number. |
|
254 * TInt areaCode(123); |
|
255 * |
|
256 * StringLoader::Format( destBuf, telFormat, |
|
257 * 0, // %0N stands for area code |
|
258 * areaCode ); |
|
259 * |
|
260 * // After returning destBuf contains string "123 %1N". |
|
261 */ |
|
262 IMPORT_C static void Format( TDes& aDest, const TDesC& aSource, |
|
263 TInt aPosition, TInt aSubs ); |
|
264 |
|
265 /** |
|
266 * Format( TDes&, TDesC&, TInt, TDesC& ) formats a resource string |
|
267 * without memory allocation. The formatted string is stored in the |
|
268 * destination TDes&. Because this method doesn't allocate memory the |
|
269 * destination descriptor must be long enough. In aPosition -1 means |
|
270 * that there is no index in the key string and all \%U-strings in the |
|
271 * original string are replaced with aSubs. In debug builds the |
|
272 * Symbian OS panic mechanism is used to notify programming errors. |
|
273 * |
|
274 * @param aDest Reference to the descriptor where the resource string |
|
275 * is formatted. |
|
276 * @param aSource Reference to the original string. |
|
277 * @param aPosition The index of the key string. |
|
278 * @param aSubs Reference to the replacing string. |
|
279 * |
|
280 * @panic EInvalidIndex In debug build if the index of the key string |
|
281 * is invalid. |
|
282 * @panic EDescriptorTooSmall In debug build if the length of the |
|
283 * destination descriptor is to small. |
|
284 * @panic EKeyStringNotFound In debug build if the key string 'U' wasn't |
|
285 * found, aDest is empty. |
|
286 * |
|
287 * One small sample describing the usage of the method. |
|
288 * @code |
|
289 * // Load example string "%0U %1U" defined in rss- and loc-files. |
|
290 * // %0U stands for weekday string and %1U for date string. |
|
291 * HBufC* timeFormat = StringLoader::LoadLC( R_TIME_FORMAT, iEikonEnv ); |
|
292 * |
|
293 * // The replacing string. |
|
294 * _LIT(dateString, "02/10/2006"); |
|
295 * |
|
296 * StringLoader::Format( destBuf, timeFormat, |
|
297 * 1, // %1U stands for date string |
|
298 * dateString ); |
|
299 * |
|
300 * // After returning destBuf contains string "%0U 02/10/2006". |
|
301 * @endcode |
|
302 */ |
|
303 IMPORT_C static void Format( TDes& aDest, const TDesC& aSource, |
|
304 TInt aPosition, const TDesC& aSubs ); |
|
305 |
|
306 /** |
|
307 * LoadL( TInt ) reads a resource string with memory allocation. |
|
308 * |
|
309 * @param aResourceId The numeric ID of the resource string to be read. |
|
310 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
311 * give this, CCoeEnv::Static is called to get it. |
|
312 * @return Pointer to a heap descriptor containing the resource |
|
313 * string. The calling program must destroy the heap descriptor |
|
314 * when it is no longer needed. |
|
315 * |
|
316 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
317 * CCoeEnv::Static returned NULL. |
|
318 */ |
|
319 IMPORT_C static HBufC* LoadL( TInt aResourceId, |
|
320 CCoeEnv* aLoaderEnv = NULL ); |
|
321 |
|
322 /** |
|
323 * LoadL( TInt, TInt ) reads a resource string with memory |
|
324 * allocation and replaces all \%N strings in it with a replacement |
|
325 * TInt. In debug builds the Symbian OS panic mechanism is used to |
|
326 * notify programming errors. |
|
327 * |
|
328 * @param aResourceId The numeric ID of the resource string to be read. |
|
329 * @param aInt The replacing TInt. |
|
330 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
331 * give this, CCoeEnv::Static is called to get it. |
|
332 * @return Pointer to a heap descriptor containing the formatted |
|
333 * resource string. The calling program must destroy the heap |
|
334 * descriptor when it is no longer needed. |
|
335 * |
|
336 * @panic EKeyStringNotFound In debug build if the key string 'N' wasn't |
|
337 * found in formatting. |
|
338 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
339 * CCoeEnv::Static returned NULL. |
|
340 */ |
|
341 IMPORT_C static HBufC* LoadL( TInt aResourceId, TInt aInt, |
|
342 CCoeEnv* aLoaderEnv = NULL ); |
|
343 |
|
344 /** |
|
345 * LoadL( TInt, const TDesC& ) reads a resource string with memory |
|
346 * allocation and replaces all \%U-strings in it with a replacement |
|
347 * string. In debug builds the Symbian OS panic mechanism is used to |
|
348 * notify programming errors. |
|
349 * |
|
350 * @param aResourceId The numeric ID of the resource string to be read. |
|
351 * @param aString Reference to the replacing string. |
|
352 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
353 * give this, CCoeEnv::Static is called to get it. |
|
354 * @return Pointer to a heap descriptor containing the formatted |
|
355 * resource string. The calling program must destroy the heap |
|
356 * descriptor when it is no longer needed. |
|
357 * |
|
358 * @panic EKeyStringNotFound In debug build if the key string 'U' wasn't |
|
359 * found in formatting. |
|
360 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
361 * CCoeEnv::Static returned NULL. |
|
362 */ |
|
363 IMPORT_C static HBufC* LoadL( TInt aResourceId, |
|
364 const TDesC& aString, |
|
365 CCoeEnv* aLoaderEnv = NULL ); |
|
366 |
|
367 /** |
|
368 * LoadL( TInt, const TDesC&, TInt ) reads a resource string |
|
369 * with memory allocation, replaces all \%N-strings in it with |
|
370 * a replacement TInt and all \%U-strings in it with a replacement |
|
371 * string. In debug builds the Symbian OS panic mechanism is used to |
|
372 * notify programming errors. |
|
373 * |
|
374 * @param aResourceId The numeric ID of the resource string to be |
|
375 * read. |
|
376 * @param aString Reference to the replacing string. |
|
377 * @param aInt The replacing TInt. |
|
378 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
379 * give this, CCoeEnv::Static is called to get it. |
|
380 * @return Pointer to a heap descriptor containing the formatted |
|
381 * resource string. The calling program must destroy the heap |
|
382 * descriptor when it is no longer needed. |
|
383 * |
|
384 * @panic EKeyStringNotFound In debug build if the key string 'N' or 'U' |
|
385 * wasn't found in formatting. |
|
386 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
387 * CCoeEnv::Static returned NULL. |
|
388 */ |
|
389 IMPORT_C static HBufC* LoadL( TInt aResourceId, const TDesC& aString, |
|
390 TInt aInt, CCoeEnv* aLoaderEnv = NULL ); |
|
391 |
|
392 /** |
|
393 * LoadL( TInt, const CArrayFix<TInt>& ) reads a resource string with |
|
394 * memory allocation and replaces the \%(index)N-strings in it with |
|
395 * replacement TInts from an array. In debug builds the Symbian OS |
|
396 * panic mechanism is used to notify programming errors. |
|
397 * |
|
398 * @param aResourceId The numeric ID of the resource string to be |
|
399 * read. |
|
400 * @param aInts Reference to the array including the replacing TInts. |
|
401 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
402 * give this, CCoeEnv::Static is called to get it. |
|
403 * @return Pointer to a heap descriptor containing the formatted |
|
404 * resource string. The calling program must destroy the heap |
|
405 * descriptor when it is no longer needed. |
|
406 * |
|
407 * @panic ETooManyArguments In debug build if too many replacing |
|
408 * elements in aInts array. |
|
409 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
410 * CCoeEnv::Static returned NULL. |
|
411 */ |
|
412 IMPORT_C static HBufC* LoadL( TInt aResourceId, |
|
413 const CArrayFix<TInt>& aInts, |
|
414 CCoeEnv* aLoaderEnv = NULL ); |
|
415 |
|
416 /** |
|
417 * LoadL( TInt, const MDesCArray& ) reads a resource string with |
|
418 * memory allocation and replaces the \%(index)U-strings in it with |
|
419 * replacement strings from an array. In debug builds the Symbian OS |
|
420 * panic mechanism is used to notify programming errors. |
|
421 * |
|
422 * @param aResourceId The numeric ID of the resource string to be read. |
|
423 * @param aStrings Reference to the array including pointers to the |
|
424 * replacing strings. |
|
425 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
426 * give this, CCoeEnv::Static is called to get it. |
|
427 * @return Pointer to a heap descriptor containing the formatted |
|
428 * resource string. The calling program must destroy the heap |
|
429 * descriptor when it is no longer needed. |
|
430 * |
|
431 * @panic ETooManyArguments In debug build if too many replacing |
|
432 * elements in aStrings |
|
433 * array. |
|
434 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
435 * CCoeEnv::Static returned NULL. |
|
436 */ |
|
437 IMPORT_C static HBufC* LoadL( TInt aResourceId, |
|
438 const MDesCArray& aStrings, |
|
439 CCoeEnv* aLoaderEnv = NULL ); |
|
440 |
|
441 /** |
|
442 * LoadL( TInt, const MDesCArray&, const CArrayFix<TInt>& ) reads a |
|
443 * resource string with memory allocation and replaces the |
|
444 * \%(index)U-strings in it with replacement strings from an array and |
|
445 * the \%(index)N-strings in it with replacement TInts from another |
|
446 * array. In debug builds the Symbian OS panic mechanism is used to |
|
447 * notify programming errors. |
|
448 * |
|
449 * @param aResourceId The numeric ID of the resource string to be read. |
|
450 * @param aStrings Reference to the array including pointers to the |
|
451 * replacing strings. |
|
452 * @param aInts Reference to the array including the replacing TInts. |
|
453 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
454 * give this, CCoeEnv::Static is called to get it. |
|
455 * @return Pointer to a heap descriptor containing the formatted |
|
456 * resource string. The calling program must destroy the heap |
|
457 * descriptor when it is no longer needed. |
|
458 * |
|
459 * @panic ETooManyArguments In debug build if too many replacing |
|
460 * elements in aStrings and/or aInts arrays. |
|
461 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
462 * CCoeEnv::Static returned NULL. |
|
463 */ |
|
464 IMPORT_C static HBufC* LoadL( TInt aResourceId, |
|
465 const MDesCArray& aStrings, |
|
466 const CArrayFix<TInt>& aInts, |
|
467 CCoeEnv* aLoaderEnv = NULL ); |
|
468 /** |
|
469 * LoadLC( TInt ) reads a resource string with memory allocation and |
|
470 * pushes the string onto the cleanup stack. |
|
471 * |
|
472 * @param aResourceId The numeric ID of the resource string to be read. |
|
473 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
474 * give this, CCoeEnv::Static is called to get it. |
|
475 * @return Pointer to a heap descriptor containing the resource |
|
476 * string. This pointer is in the cleanup stack. The calling |
|
477 * program should pop and destroy the heap descriptor when it is |
|
478 * no longer needed. |
|
479 * |
|
480 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
481 * CCoeEnv::Static returned NULL. |
|
482 */ |
|
483 IMPORT_C static HBufC* LoadLC( TInt aResourceId, |
|
484 CCoeEnv* aLoaderEnv = NULL ); |
|
485 |
|
486 /** |
|
487 * LoadLC( TInt, TInt ) reads a resource string with memory |
|
488 * allocation, replaces all \%N-strings in it with a replacement |
|
489 * TInt and pushes the string onto the cleanup stack. In debug builds |
|
490 * the Symbian OS panic mechanism is used to notify programming errors. |
|
491 * |
|
492 * @param aResourceId The numeric ID of the resource string to be read. |
|
493 * @param aInt the replacing TInt. |
|
494 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
495 * give this, CCoeEnv::Static is called to get it. |
|
496 * @return pointer to a heap descriptor containing the formatted |
|
497 * resource string. This pointer is in the cleanup stack. |
|
498 * The calling program should pop and destroy the heap |
|
499 * descriptor when it is no longer needed. |
|
500 * |
|
501 * @panic EKeyStringNotFound In debug build if the key string 'N' wasn't |
|
502 * found in formatting. |
|
503 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
504 * CCoeEnv::Static returned NULL. |
|
505 */ |
|
506 IMPORT_C static HBufC* LoadLC( TInt aResourceId, TInt aInt, |
|
507 CCoeEnv* aLoaderEnv = NULL ); |
|
508 |
|
509 /** |
|
510 * LoadLC( TInt, const TDesC& ) reads a resource string with memory |
|
511 * allocation, replaces all \%U-strings in it with a replacement |
|
512 * string and pushes the string onto the cleanup stack. In debug builds |
|
513 * the Symbian OS panic mechanism is used to notify programming errors. |
|
514 * |
|
515 * @param aResourceId The numeric ID of the resource string to be read. |
|
516 * @param aString Reference to the replacing string. |
|
517 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
518 * give this, CCoeEnv::Static is called to get it. |
|
519 * @return Pointer to a heap descriptor containing the formatted |
|
520 * resource string. This pointer is in the cleanup stack. |
|
521 * The calling program should pop and destroy the heap |
|
522 * descriptor when it is no longer needed. |
|
523 * |
|
524 * @panic EKeyStringNotFound In debug build if the key string 'U' wasn't |
|
525 * found in formatting. |
|
526 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
527 * CCoeEnv::Static returned NULL. |
|
528 */ |
|
529 IMPORT_C static HBufC* LoadLC( TInt aResourceId, |
|
530 const TDesC& aString, |
|
531 CCoeEnv* aLoaderEnv = NULL ); |
|
532 |
|
533 /** |
|
534 * LoadLC( TInt, const TDesC&, TInt ) reads a resource string |
|
535 * with memory allocation, replaces all \%N-strings in it with |
|
536 * a replacement TInt and the first \%U-strings in it with a replacement |
|
537 * string and pushes the string onto the cleanup stack. In debug builds |
|
538 * the Symbian OS panic mechanism is used to notify programming errors. |
|
539 * |
|
540 * @param aResourceId The numeric ID of the resource string to be |
|
541 * read. |
|
542 * @param aString Reference to the replacing string. |
|
543 * @param aInt The replacing TInt. |
|
544 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
545 * give this, CCoeEnv::Static is called to get it. |
|
546 * @return Pointer to a heap descriptor containing the formatted |
|
547 * resource string. This pointer is in the cleanup stack. |
|
548 * The calling program should pop and destroy the heap |
|
549 * descriptor when it is no longer needed. |
|
550 * |
|
551 * @panic EKeyStringNotFound In debug build if the key string 'N' or 'U' |
|
552 * wasn't found in formatting. |
|
553 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
554 * CCoeEnv::Static returned NULL. |
|
555 */ |
|
556 IMPORT_C static HBufC* LoadLC( TInt aResourceId, const TDesC& aString, |
|
557 TInt aInt, CCoeEnv* aLoaderEnv = NULL ); |
|
558 |
|
559 /** |
|
560 * LoadLC( TInt, const CArrayFix<TInt>& ) reads a resource string with |
|
561 * memory allocation, replaces the \%(index)N-strings in it with |
|
562 * replacement TInts from an array and pushes the string onto the |
|
563 * cleanup stack. In debug builds the Symbian OS panic mechanism is |
|
564 * used to notify programming errors. |
|
565 * |
|
566 * @param aResourceId The numeric ID of the resource string to be |
|
567 * read. |
|
568 * @param aInts Reference to the array including the replacing TInts. |
|
569 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
570 * give this, CCoeEnv::Static is called to get it. |
|
571 * @return Pointer to a heap descriptor containing the formatted |
|
572 * resource string. This pointer is in the cleanup stack. |
|
573 * The calling program should pop and destroy the heap |
|
574 * descriptor when it is no longer needed. |
|
575 * |
|
576 * @panic ETooManyArguments In debug build if too many replacing |
|
577 * elements in aInts array. |
|
578 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
579 * CCoeEnv::Static returned NULL. |
|
580 */ |
|
581 IMPORT_C static HBufC* LoadLC( TInt aResourceId, |
|
582 const CArrayFix<TInt>& aInts, |
|
583 CCoeEnv* aLoaderEnv = NULL ); |
|
584 |
|
585 /** |
|
586 * LoadLC( TInt, const MDesCArray& ) reads a resource string with |
|
587 * memory allocation, replaces the \%(index)U-strings in it with |
|
588 * replacement strings from an array and pushes the string onto the |
|
589 * cleanup stack. In debug builds the Symbian OS panic mechanism is |
|
590 * used to notify programming errors. |
|
591 * |
|
592 * @param aResourceId The numeric ID of the resource string to be read. |
|
593 * @param aStrings Reference to the array including pointers to the |
|
594 * replacing strings. |
|
595 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
596 * give this, CCoeEnv::Static is called to get it. |
|
597 * @return Pointer to a heap descriptor containing the formatted |
|
598 * resource string. This pointer is in the cleanup stack. |
|
599 * The calling program should pop and destroy the heap |
|
600 * descriptor when it is no longer needed. |
|
601 * |
|
602 * @panic ETooManyArguments In debug build if too many replacing |
|
603 * elements in aStrings array. |
|
604 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
605 * CCoeEnv::Static returned NULL. |
|
606 */ |
|
607 IMPORT_C static HBufC* LoadLC( TInt aResourceId, |
|
608 const MDesCArray& aStrings, |
|
609 CCoeEnv* aLoaderEnv = NULL ); |
|
610 |
|
611 /** |
|
612 * LoadLC( TInt, const MDesCArray&, const CArrayFix<TInt>& ) reads a |
|
613 * resource string with memory allocation, replaces the |
|
614 * \%(index)U-strings in it with replacement strings from an array and |
|
615 * the \%(index)N-strings in it with replacement TInts from another |
|
616 * array and pushes the string onto the cleanup stack. In debug builds |
|
617 * the Symbian OS panic mechanism is used to notify programming errors. |
|
618 * |
|
619 * @param aResourceId The numeric ID of the resource string to be read. |
|
620 * @param aStrings Reference to the array including pointers to the |
|
621 * replacing strings. |
|
622 * @param aInts Reference to the array including the replacing TInts. |
|
623 * @param aLoaderEnv Pointer to the control environment. If user doesn't |
|
624 * give this, CCoeEnv::Static is called to get it. |
|
625 * @return Pointer to a heap descriptor containing the formatted |
|
626 * resource string. This pointer is in the cleanup stack. |
|
627 * The calling program should pop and destroy the heap |
|
628 * descriptor when it is no longer needed. |
|
629 * |
|
630 * @panic ETooManyArguments In debug build if too many replacing |
|
631 * elements in aStrings and/or aInts arrays. |
|
632 * @leave KErrNotSupported Parameter aLoaderEnv is NULL and |
|
633 * CCoeEnv::Static returned NULL. |
|
634 */ |
|
635 IMPORT_C static HBufC* LoadLC( TInt aResourceId, |
|
636 const MDesCArray& aStrings, |
|
637 const CArrayFix<TInt>& aInts, |
|
638 CCoeEnv* aLoaderEnv = NULL ); |
|
639 |
|
640 private: |
|
641 |
|
642 /** |
|
643 * C++ default constructor. |
|
644 */ |
|
645 StringLoader(); |
|
646 |
|
647 // Prohibit copy constructor |
|
648 StringLoader( const StringLoader& ); |
|
649 // Prohibit assigment operator |
|
650 StringLoader& operator= ( const StringLoader& ); |
|
651 |
|
652 /** |
|
653 * FormatStringL( const TDesC&, const TDesC&, const TDesC& ) finds the |
|
654 * keystring from the source string and replaces it with the |
|
655 * replacement string. |
|
656 * |
|
657 * @param aSource Reference to the source string. |
|
658 * @param aKey Reference to the keystring. |
|
659 * @param aSubs Reference to the replacing string. |
|
660 * @param aDir directionality of the source text |
|
661 * @param aFound ETrue if there were any strongly directional |
|
662 * characters and EFalse if there were none |
|
663 * @return Pointer to a heap descriptor containing the formated string. |
|
664 */ |
|
665 static HBufC* FormatStringL( |
|
666 const TDesC& aSource, |
|
667 const TDesC& aKey, |
|
668 const TDesC& aSubs, |
|
669 TBidiText::TDirectionality aDir |
|
670 ); |
|
671 |
|
672 /** |
|
673 * FormatStringL( const TDesC&, const TDesC&, const TDesC& ) finds the |
|
674 * keystring from the source string and replaces it with the |
|
675 * replacement string. |
|
676 * |
|
677 * @param aSource Reference to the source string. |
|
678 * @param aKey Reference to the keystring. |
|
679 * @param aSubs Reference to the replacing string. |
|
680 * @param aDirectionality directionality of the source text |
|
681 * @param aParamCount Keeps track of remaining parameters. |
|
682 * Value KUnknownCount denotes that count is not known yet. |
|
683 * Value may be updated by this method to reflect change in count. |
|
684 * @param aSubCount Number of '|' separated substrings. |
|
685 * Value KUnknownCount denotes that count is not known yet. |
|
686 * @return Pointer to a heap descriptor containing the formated string. |
|
687 */ |
|
688 static HBufC* FormatStringL( |
|
689 const TDesC& aSource, |
|
690 const TDesC& aKey, |
|
691 const TDesC& aSubs, |
|
692 TBidiText::TDirectionality aDirectionality, |
|
693 TInt& aParamCount, |
|
694 TInt aSubCount |
|
695 ); |
|
696 |
|
697 /** |
|
698 * FormatStringL( HbufC*, const CArrayFix<TInt>&, TInt ) finds the |
|
699 * \%(index)N-keystrings from the source string and replaces it with the |
|
700 * replacement TInts. |
|
701 * @param aSource Reference to the source string. |
|
702 * @param aInts Reference to the array containing the replacing TInts. |
|
703 * @param aMax Maximum number of key strings in the resource string. |
|
704 * @return Pointer to a heap descriptor containing the formated string. |
|
705 */ |
|
706 static HBufC* FormatStringL( TDesC& aSource, |
|
707 const CArrayFix<TInt>& aInts, |
|
708 TInt aMax, |
|
709 TBidiText::TDirectionality aDir |
|
710 ); |
|
711 |
|
712 /** |
|
713 * FormatStringL( HbufC*, const MDesCArray&, TInt ) finds the |
|
714 * \%(index)U-keystrings from the source string and replaces it with the |
|
715 * replacement strings. |
|
716 * |
|
717 * @param aSource Reference to the source string. |
|
718 * @param aStrings Reference to the array containing pointers to the |
|
719 * replacing strings. |
|
720 * @param aMax Maximum number of key strings in the resource string. |
|
721 * @return Pointer to a heap descriptor containing the formated |
|
722 * string. |
|
723 */ |
|
724 static HBufC* FormatStringL( TDesC& aSource, |
|
725 const MDesCArray& aStrings, |
|
726 TInt aMax, |
|
727 TBidiText::TDirectionality aDir |
|
728 ); |
|
729 /** |
|
730 * Formater( TDes&, const TDesC&, const TDesC&, const TDesC& ) finds |
|
731 * the keystring from the source string and replaces it with the |
|
732 * replacement string. The formated string is stored in the destination |
|
733 * descriptor. |
|
734 * |
|
735 * @param aDest Reference to the destination descriptor. |
|
736 * @param aSource Reference to the source string. |
|
737 * @param aKey Reference to the keystring. |
|
738 * @param aSubs Reference to the replacing string. |
|
739 * @param aDirectionality directionality of the main text |
|
740 * @return Number of keystrings replaced. |
|
741 */ |
|
742 static TInt Formater( |
|
743 TDes& aDest, |
|
744 const TDesC& aSource, |
|
745 const TDesC& aKey, |
|
746 const TDesC& aSubs, |
|
747 TBidiText::TDirectionality aDirectionality |
|
748 ); |
|
749 |
|
750 /** |
|
751 * KeyStringFormater( TDes&, const TText&, TInt, const TDesC& ) formats |
|
752 * the keystring from given parameters. |
|
753 * |
|
754 * @param aDest Reference to the destination descriptor. |
|
755 * @param aKey Reference to the key letter. |
|
756 * @param aPosition index of the key string. |
|
757 * @param aKeyString Reference to the keystring. |
|
758 */ |
|
759 static void KeyStringFormater( TDes& aDest, const TText& aKey, |
|
760 TInt aPosition, const TDesC& aKeyString ); |
|
761 |
|
762 /** |
|
763 * Resolves directionality of the given source text. |
|
764 * Place-holder strings are removed so that they don't affect the result. |
|
765 */ |
|
766 static TBidiText::TDirectionality ResolveDirectionality( TDes& aText, TBool* aFound ); |
|
767 |
|
768 /** |
|
769 * Counts the number of parameters in the text. |
|
770 * Needed for correct memory allocations. |
|
771 * |
|
772 * @param aText Source text |
|
773 * @param aIndex Index to count. If index is invalid, counts all indexes. |
|
774 * @return Parameter count |
|
775 */ |
|
776 static TInt GetParamCount( const TDesC& aText, TInt aIndex = -1); |
|
777 |
|
778 /** |
|
779 * Counts the number of substrings (separated by '|'s) in the text. |
|
780 * If no '|' is found, but aText length is greater than zero, return 1. |
|
781 * If aText length is zero, return zero. |
|
782 * Needed for correct memory allocations. |
|
783 * |
|
784 * @param aText Source text |
|
785 * @return Substring count |
|
786 */ |
|
787 static TInt GetSubStringCount( const TDesC& aText ); |
|
788 |
|
789 /** |
|
790 * Resolves directionality of the given source text. |
|
791 * Uses ResolveDirectionality(). |
|
792 */ |
|
793 static TBidiText::TDirectionality DirectionalityL( const TDesC& aText, TBool* aFound ); |
|
794 |
|
795 /** |
|
796 * Resolves sub strings. Uses ResolveSubStringL() |
|
797 */ |
|
798 static HBufC* ResolveSubStringDirsL( TDes& aText, TInt aCount, TBool* aMarker ); |
|
799 |
|
800 /** |
|
801 * Resolves sub string and directionality of the sub string. |
|
802 * Adds no dir marker if directionality of the string not found. |
|
803 * |
|
804 * @param aText Source text. After returnig returned sub string |
|
805 * removed from aText. |
|
806 * @param aMarker After returning ETrue if no dir marker added, otherwise EFalse. |
|
807 * @return Substring |
|
808 */ |
|
809 static HBufC* ResolveSubStringL( TDes& aText, TBool* aMarker ); |
|
810 |
|
811 /** |
|
812 * Removes no dir markers from source text. |
|
813 * |
|
814 * @param aText Source text. |
|
815 */ |
|
816 static void RemoveNoDirMarkers( TDes& aText ); |
|
817 |
|
818 /** |
|
819 * Used by exported Format methods. |
|
820 */ |
|
821 static void FormatL( TDes& aDest, const TDesC& aSource, |
|
822 const TDesC& aKeybuf, const TDesC& aSubs ); |
|
823 }; |
53 }; |
824 |
54 |
825 #endif // STRINGLOADER_H |
55 #endif // STRINGLOADER_H |
826 |
56 |
827 // End of File |
|