1.1 --- a/epoc32/include/stringloader.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/stringloader.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,827 +1,56 @@
1.4 /*
1.5 -* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).
1.7 * All rights reserved.
1.8 * This component and the accompanying materials are made available
1.9 -* 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
1.10 +* under the terms of "Eclipse Public License v1.0"
1.11 * which accompanies this distribution, and is available
1.12 -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.13 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.14 *
1.15 * Initial Contributors:
1.16 * Nokia Corporation - initial contribution.
1.17 *
1.18 * Contributors:
1.19 *
1.20 -* Description: String Loader API provides methods for loading resource
1.21 -* strings and formatting them.
1.22 +* Description:
1.23 *
1.24 */
1.25
1.26 +
1.27 +
1.28 #ifndef STRINGLOADER_H
1.29 #define STRINGLOADER_H
1.30
1.31 -// INCLUDE FILES
1.32 -#include <coemain.h>
1.33 -#include <biditext.h>
1.34 +#include <coemain.h>
1.35 +#include <biditext.h>
1.36
1.37 -// CLASS DECLARATION
1.38 +class CCoeEnv;
1.39
1.40 +NONSHARABLE_CLASS(StringLoader)
1.41 /**
1.42 -* Class provides methods to load and format resource strings.
1.43 -* String Loader API provides an interface to load and format resource strings
1.44 -* that may contain parameter(s) (\%U for text or or \%N for numerical).
1.45 -* Resource strings are usually defined in an RSS file.
1.46 -*
1.47 -* The API consists of the StringLoader class. All methods are static, so there is
1.48 -* no need to explicitly allocate memory for the interface class.
1.49 -* The implementation needs a CCoeEnv instance to access for example the
1.50 -* resource files.
1.51 -*
1.52 -*
1.53 -* Usage:
1.54 -*
1.55 -* Applications load and format resource strings from normal resources with
1.56 -* static methods of the StringLoader class. The loading is done with the LoadL
1.57 -* and LoadLC methods and with the Load method in situations where memory
1.58 -* allocation from the heap is not possible. Formatting is done automatically
1.59 -* after loading in the LoadL and LoadLC methods, but it can also be done
1.60 -* separately with the Format method in situations where memory allocation from
1.61 -* the heap is not possible. For reading the resource strings with the Load,
1.62 -* LoadL and LoadLC methods, the user should provide a pointer to CCoeEnv for
1.63 -* efficiency reasons. If the pointer is not provided, the implementation uses
1.64 -* the CCoeEnv::Static method internally to get it.
1.65 -*
1.66 -* Different size displays can handle different length strings. To take full
1.67 -* advantage of this fact, StringLoader supports resource strings with multiple
1.68 -* options for string separated by 0x0001 character. Each such string can
1.69 -* contain same or different sub string keys (\%U and \%N). StringLoader returns
1.70 -* all strings, it is responsibility of the caller to parse the result and
1.71 -* choose the proper string to display.
1.72 -*
1.73 -* Setting the maximum sub string length may be done in the text resources. Sub
1.74 -* string maximum lengths can be localized separately for every language.
1.75 -* The maximum sub string length is of the format: \%U[NN]
1.76 -* where NN is a number [01..99]. Please note that NN must always consist of two
1.77 -* characters, i.e. if the sub string maximum length is eight characters, the
1.78 -* value to be used is 08, not plain 8. If the number of characters exceeds the
1.79 -* maximum length, the sub string is cut to fit and the last character is
1.80 -* replaced with an ellipsis character.
1.81 -*
1.82 -* The following examples describe the usage of the String Loader API.
1.83 -*
1.84 -* Usage when one TInt is added:
1.85 -*
1.86 -* @code
1.87 -* // In .loc -file
1.88 -* // #define text_example "You have %N undone tasks."
1.89 -*
1.90 -* // In .rss -file
1.91 -* // RESOURCE TBUF r_text_example { buf = text_example; }
1.92 -*
1.93 -* // (In the .cpp -file)
1.94 -* #include <stringloader.h>
1.95 -*
1.96 -* // Get CCoeEnv instance
1.97 -* CEikonEnv* iEikonEnv = CEikonEnv::Static();
1.98 -*
1.99 -* TInt number( 324 );
1.100 -*
1.101 -* // Method reads a resource string with memory allocation
1.102 -* // and replaces all %N-strings in it with a replacement TInt.
1.103 -* // The heap descriptor must be destroyed when it is no longer needed.
1.104 -* // iEikonEnv is needed for loading the resource string.
1.105 -* HBufC* stringholder = StringLoader::LoadL( R_TEXT_EXAMPLE, number, iEikonEnv );
1.106 -*
1.107 -* // The 'number' is added to the resource string. The result is
1.108 -* // that stringholder points to a heap descriptor containing string:
1.109 -* // "You have 324 undone tasks."
1.110 -*
1.111 -* // Delete the heap descriptor
1.112 -* delete stringholder;
1.113 -* @endcode
1.114 -*
1.115 -*
1.116 -* Usage when several strings are added:
1.117 -*
1.118 -* Index can be included to parameters. Several parameters can have same index,
1.119 -* if same replacement is needed multiple times.
1.120 -*
1.121 -* @code
1.122 -* // In .loc -file
1.123 -* // #define text_example "I'm %2U%1U %3U%0U fine."
1.124 -*
1.125 -* // In .rss -file
1.126 -* // RESOURCE TBUF r_text_example { buf = text_example; }
1.127 -*
1.128 -* // In the .cpp -file
1.129 -* #include <stringloader.h>
1.130 -*
1.131 -* // Get CCoeEnv instance
1.132 -* CEikonEnv* iEikonEnv = CEikonEnv::Static();
1.133 -*
1.134 -* CDesCArrayFlat* strings = new CDesCArrayFlat( 4 );
1.135 -* CleanupStack::PushL( strings );
1.136 -*
1.137 -* strings->AppendL( _L("orking") ); //First string
1.138 -*
1.139 -* strings->AppendL( _L("ll") ); //Second string
1.140 -*
1.141 -* strings->AppendL( _L("sti") ); //Third string
1.142 -*
1.143 -* strings->AppendL( _L("w") ); //Fourth string
1.144 -*
1.145 -* // Method reads a resource string with memory allocation and replaces
1.146 -* // the %(index)U strings in it with replacement strings from an array.
1.147 -* // The heap descriptor must be destroyed when it is no longer needed.
1.148 -* // iEikonEnv is needed for loading the resource string.
1.149 -* HBufC* stringholder = StringLoader::LoadL( R_TEXT_EXAMPLE, *strings, iEikonEnv );
1.150 -*
1.151 -* // Four strings are added to the resource string. The result is
1.152 -* // that stringholder points to a heap descriptor containing string:
1.153 -* // "I'm still working fine."
1.154 -*
1.155 -* // Pop and delete strings array
1.156 -* CleanupStack::PopAndDestroy();
1.157 -*
1.158 -* // Delete the heap descriptor
1.159 -* delete stringholder;
1.160 -* @endcode
1.161 -*
1.162 -*
1.163 -* Usage with scalable UI support:
1.164 -*
1.165 -* @code
1.166 -* // In .loc -file
1.167 -* // #define TEXT_EXAMPLE "You have missed %N messages from %U."<0x0001>"Missed %N msgs from %U."<0x0001>"Missed %N msgs."
1.168 -*
1.169 -* // In .rss -file
1.170 -* // RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; }
1.171 -*
1.172 -* // In the .cpp -file
1.173 -* #include <stringloader.h>
1.174 -*
1.175 -* // Get CCoeEnv instance
1.176 -* CEikonEnv* iEikonEnv = CEikonEnv::Static();
1.177 -*
1.178 -* TInt number( 12 );
1.179 -* _LIT(name, "John Doe");
1.180 -*
1.181 -* // Method reads a resource string with memory allocation,
1.182 -* // replaces all %N strings in it with a replacement TInt and
1.183 -* // all %U strings in it with a replacement string.
1.184 -* // The heap descriptor must be destroyed when it is no longer needed.
1.185 -* // iEikonEnv is needed for loading the resource string.
1.186 -* HBufC* stringholder = StringLoader::LoadL( R_TEXT_EXAMPLE, name, number, iEikonEnv );
1.187 -*
1.188 -* // The number and name are added to the resource string. The result is
1.189 -* // that stringholder points to a heap descriptor containing string:
1.190 -* // "You have missed 12 messages from John Doe.\001Missed 12 msgs from John
1.191 -* // Doe.\001Missed 12 msgs."
1.192 -*
1.193 -* // Delete the heap descriptor
1.194 -* delete stringholder;
1.195 -* @endcode
1.196 -*
1.197 -*
1.198 -* Error handling:
1.199 -*
1.200 -* The leave mechanism of the Symbian OS environment is used to handle memory
1.201 -* exhaustion. The panic mechanism is used to handle programming errors while
1.202 -* debugging. RStringLoader panics for seven different reasons. The panic
1.203 -* category is named STRINGLOADER. The panic codes are:
1.204 -*
1.205 -* - ETooFewArguments = 0 (Unsolved parameters in resource string.)
1.206 -* - ETooManyArguments = 1 (Already solved all parameters in resource string.)
1.207 -* - EKeyStringNotFound = 2 (The key string wasn't found in formatting.)
1.208 -* - EInvalidIndex = 3 (Invalid index in Format-method)
1.209 -* - EDescriptorTooSmall = 4 (Too small destination descriptor.)
1.210 -* - ECCoeEnvNotInitialized = 5 (CCoeEnv is not initialized)
1.211 -* - EInvalidSubstitute = 6 (Substituted string contains KSubStringSeparator)
1.212 -*
1.213 -* @lib commonengine.lib
1.214 -* @since S60 2.0
1.215 +@deprecated
1.216 +@see TulTextResourceUtils
1.217 +@note For compatibility with S60 only
1.218 */
1.219 -class StringLoader
1.220 {
1.221 - public:
1.222 -
1.223 - /**
1.224 - * Load( TDes&, TInt ) reads a resource string without memory
1.225 - * allocation. The loaded string is stored in the destination TDes&.
1.226 - * Because this method doesn't allocate memory the destination
1.227 - * descriptor must be long enough.
1.228 - *
1.229 - * @param aResourceId The numeric ID of the resource string to be read.
1.230 - * @param aDest Reference to the descriptor where the resource string
1.231 - * is loaded.
1.232 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.233 - * give this, CCoeEnv::Static is called to get it.
1.234 - *
1.235 - * @panic ECCoeEnvNotInitialized Parameter aLoaderEnv is NULL and
1.236 - * CCoeEnv::Static returned NULL.
1.237 - */
1.238 - IMPORT_C static void Load( TDes& aDest, TInt aResourceId,
1.239 - CCoeEnv* aLoaderEnv = NULL );
1.240 -
1.241 - /**
1.242 - * Format( TDes&, TDesC&, TInt, TInt ) formats a resource string without
1.243 - * memory allocation. The formatted string is stored in the destination
1.244 - * TDes&. Because this method doesn't allocate memory the destination
1.245 - * descriptor must be long enough. In aPosition -1 means that there is
1.246 - * no index in the key string and all \%N-strings in the original string
1.247 - * are replaced with aSubs. In debug builds the Symbian OS panic
1.248 - * mechanism is used to notify programming errors.
1.249 - *
1.250 - * @param aDest Reference to the descriptor where the resource string
1.251 - * is formatted.
1.252 - * @param aSource Reference to the original string.
1.253 - * @param aPosition The index of the key string.
1.254 - * @param aSubs The replacing TInt.
1.255 - *
1.256 - * @panic EInvalidIndex In debug build if the index of the key string
1.257 - * is invalid.
1.258 - * @panic EDescriptorTooSmall In debug build if the length of the
1.259 - * destination descriptor is to small.
1.260 - * @panic EKeyStringNotFound In debug build if the key string 'N' wasn't
1.261 - * found, aDest is empty.
1.262 - *
1.263 - * One small sample describing the usage of the method.
1.264 - * @code
1.265 - * // Load example string "%0N %1N" defined in rss- and loc-files.
1.266 - * // %0N stands for area code and %1N for phone number.
1.267 - * HBufC* telFormat = StringLoader::LoadLC( R_TEL_FORMAT, iEikonEnv );
1.268 - *
1.269 - * // The replacing number.
1.270 - * TInt areaCode(123);
1.271 - *
1.272 - * StringLoader::Format( destBuf, telFormat,
1.273 - * 0, // %0N stands for area code
1.274 - * areaCode );
1.275 - *
1.276 - * // After returning destBuf contains string "123 %1N".
1.277 - */
1.278 - IMPORT_C static void Format( TDes& aDest, const TDesC& aSource,
1.279 - TInt aPosition, TInt aSubs );
1.280 -
1.281 - /**
1.282 - * Format( TDes&, TDesC&, TInt, TDesC& ) formats a resource string
1.283 - * without memory allocation. The formatted string is stored in the
1.284 - * destination TDes&. Because this method doesn't allocate memory the
1.285 - * destination descriptor must be long enough. In aPosition -1 means
1.286 - * that there is no index in the key string and all \%U-strings in the
1.287 - * original string are replaced with aSubs. In debug builds the
1.288 - * Symbian OS panic mechanism is used to notify programming errors.
1.289 - *
1.290 - * @param aDest Reference to the descriptor where the resource string
1.291 - * is formatted.
1.292 - * @param aSource Reference to the original string.
1.293 - * @param aPosition The index of the key string.
1.294 - * @param aSubs Reference to the replacing string.
1.295 - *
1.296 - * @panic EInvalidIndex In debug build if the index of the key string
1.297 - * is invalid.
1.298 - * @panic EDescriptorTooSmall In debug build if the length of the
1.299 - * destination descriptor is to small.
1.300 - * @panic EKeyStringNotFound In debug build if the key string 'U' wasn't
1.301 - * found, aDest is empty.
1.302 - *
1.303 - * One small sample describing the usage of the method.
1.304 - * @code
1.305 - * // Load example string "%0U %1U" defined in rss- and loc-files.
1.306 - * // %0U stands for weekday string and %1U for date string.
1.307 - * HBufC* timeFormat = StringLoader::LoadLC( R_TIME_FORMAT, iEikonEnv );
1.308 - *
1.309 - * // The replacing string.
1.310 - * _LIT(dateString, "02/10/2006");
1.311 - *
1.312 - * StringLoader::Format( destBuf, timeFormat,
1.313 - * 1, // %1U stands for date string
1.314 - * dateString );
1.315 - *
1.316 - * // After returning destBuf contains string "%0U 02/10/2006".
1.317 - * @endcode
1.318 - */
1.319 - IMPORT_C static void Format( TDes& aDest, const TDesC& aSource,
1.320 - TInt aPosition, const TDesC& aSubs );
1.321 -
1.322 - /**
1.323 - * LoadL( TInt ) reads a resource string with memory allocation.
1.324 - *
1.325 - * @param aResourceId The numeric ID of the resource string to be read.
1.326 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.327 - * give this, CCoeEnv::Static is called to get it.
1.328 - * @return Pointer to a heap descriptor containing the resource
1.329 - * string. The calling program must destroy the heap descriptor
1.330 - * when it is no longer needed.
1.331 - *
1.332 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.333 - * CCoeEnv::Static returned NULL.
1.334 - */
1.335 - IMPORT_C static HBufC* LoadL( TInt aResourceId,
1.336 - CCoeEnv* aLoaderEnv = NULL );
1.337 -
1.338 - /**
1.339 - * LoadL( TInt, TInt ) reads a resource string with memory
1.340 - * allocation and replaces all \%N strings in it with a replacement
1.341 - * TInt. In debug builds the Symbian OS panic mechanism is used to
1.342 - * notify programming errors.
1.343 - *
1.344 - * @param aResourceId The numeric ID of the resource string to be read.
1.345 - * @param aInt The replacing TInt.
1.346 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.347 - * give this, CCoeEnv::Static is called to get it.
1.348 - * @return Pointer to a heap descriptor containing the formatted
1.349 - * resource string. The calling program must destroy the heap
1.350 - * descriptor when it is no longer needed.
1.351 - *
1.352 - * @panic EKeyStringNotFound In debug build if the key string 'N' wasn't
1.353 - * found in formatting.
1.354 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.355 - * CCoeEnv::Static returned NULL.
1.356 - */
1.357 - IMPORT_C static HBufC* LoadL( TInt aResourceId, TInt aInt,
1.358 - CCoeEnv* aLoaderEnv = NULL );
1.359 -
1.360 - /**
1.361 - * LoadL( TInt, const TDesC& ) reads a resource string with memory
1.362 - * allocation and replaces all \%U-strings in it with a replacement
1.363 - * string. In debug builds the Symbian OS panic mechanism is used to
1.364 - * notify programming errors.
1.365 - *
1.366 - * @param aResourceId The numeric ID of the resource string to be read.
1.367 - * @param aString Reference to the replacing string.
1.368 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.369 - * give this, CCoeEnv::Static is called to get it.
1.370 - * @return Pointer to a heap descriptor containing the formatted
1.371 - * resource string. The calling program must destroy the heap
1.372 - * descriptor when it is no longer needed.
1.373 - *
1.374 - * @panic EKeyStringNotFound In debug build if the key string 'U' wasn't
1.375 - * found in formatting.
1.376 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.377 - * CCoeEnv::Static returned NULL.
1.378 - */
1.379 - IMPORT_C static HBufC* LoadL( TInt aResourceId,
1.380 - const TDesC& aString,
1.381 - CCoeEnv* aLoaderEnv = NULL );
1.382 -
1.383 - /**
1.384 - * LoadL( TInt, const TDesC&, TInt ) reads a resource string
1.385 - * with memory allocation, replaces all \%N-strings in it with
1.386 - * a replacement TInt and all \%U-strings in it with a replacement
1.387 - * string. In debug builds the Symbian OS panic mechanism is used to
1.388 - * notify programming errors.
1.389 - *
1.390 - * @param aResourceId The numeric ID of the resource string to be
1.391 - * read.
1.392 - * @param aString Reference to the replacing string.
1.393 - * @param aInt The replacing TInt.
1.394 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.395 - * give this, CCoeEnv::Static is called to get it.
1.396 - * @return Pointer to a heap descriptor containing the formatted
1.397 - * resource string. The calling program must destroy the heap
1.398 - * descriptor when it is no longer needed.
1.399 - *
1.400 - * @panic EKeyStringNotFound In debug build if the key string 'N' or 'U'
1.401 - * wasn't found in formatting.
1.402 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.403 - * CCoeEnv::Static returned NULL.
1.404 - */
1.405 - IMPORT_C static HBufC* LoadL( TInt aResourceId, const TDesC& aString,
1.406 - TInt aInt, CCoeEnv* aLoaderEnv = NULL );
1.407 -
1.408 - /**
1.409 - * LoadL( TInt, const CArrayFix<TInt>& ) reads a resource string with
1.410 - * memory allocation and replaces the \%(index)N-strings in it with
1.411 - * replacement TInts from an array. In debug builds the Symbian OS
1.412 - * panic mechanism is used to notify programming errors.
1.413 - *
1.414 - * @param aResourceId The numeric ID of the resource string to be
1.415 - * read.
1.416 - * @param aInts Reference to the array including the replacing TInts.
1.417 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.418 - * give this, CCoeEnv::Static is called to get it.
1.419 - * @return Pointer to a heap descriptor containing the formatted
1.420 - * resource string. The calling program must destroy the heap
1.421 - * descriptor when it is no longer needed.
1.422 - *
1.423 - * @panic ETooManyArguments In debug build if too many replacing
1.424 - * elements in aInts array.
1.425 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.426 - * CCoeEnv::Static returned NULL.
1.427 - */
1.428 - IMPORT_C static HBufC* LoadL( TInt aResourceId,
1.429 - const CArrayFix<TInt>& aInts,
1.430 - CCoeEnv* aLoaderEnv = NULL );
1.431 -
1.432 - /**
1.433 - * LoadL( TInt, const MDesCArray& ) reads a resource string with
1.434 - * memory allocation and replaces the \%(index)U-strings in it with
1.435 - * replacement strings from an array. In debug builds the Symbian OS
1.436 - * panic mechanism is used to notify programming errors.
1.437 - *
1.438 - * @param aResourceId The numeric ID of the resource string to be read.
1.439 - * @param aStrings Reference to the array including pointers to the
1.440 - * replacing strings.
1.441 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.442 - * give this, CCoeEnv::Static is called to get it.
1.443 - * @return Pointer to a heap descriptor containing the formatted
1.444 - * resource string. The calling program must destroy the heap
1.445 - * descriptor when it is no longer needed.
1.446 - *
1.447 - * @panic ETooManyArguments In debug build if too many replacing
1.448 - * elements in aStrings
1.449 - * array.
1.450 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.451 - * CCoeEnv::Static returned NULL.
1.452 - */
1.453 - IMPORT_C static HBufC* LoadL( TInt aResourceId,
1.454 - const MDesCArray& aStrings,
1.455 - CCoeEnv* aLoaderEnv = NULL );
1.456 -
1.457 - /**
1.458 - * LoadL( TInt, const MDesCArray&, const CArrayFix<TInt>& ) reads a
1.459 - * resource string with memory allocation and replaces the
1.460 - * \%(index)U-strings in it with replacement strings from an array and
1.461 - * the \%(index)N-strings in it with replacement TInts from another
1.462 - * array. In debug builds the Symbian OS panic mechanism is used to
1.463 - * notify programming errors.
1.464 - *
1.465 - * @param aResourceId The numeric ID of the resource string to be read.
1.466 - * @param aStrings Reference to the array including pointers to the
1.467 - * replacing strings.
1.468 - * @param aInts Reference to the array including the replacing TInts.
1.469 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.470 - * give this, CCoeEnv::Static is called to get it.
1.471 - * @return Pointer to a heap descriptor containing the formatted
1.472 - * resource string. The calling program must destroy the heap
1.473 - * descriptor when it is no longer needed.
1.474 - *
1.475 - * @panic ETooManyArguments In debug build if too many replacing
1.476 - * elements in aStrings and/or aInts arrays.
1.477 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.478 - * CCoeEnv::Static returned NULL.
1.479 - */
1.480 - IMPORT_C static HBufC* LoadL( TInt aResourceId,
1.481 - const MDesCArray& aStrings,
1.482 - const CArrayFix<TInt>& aInts,
1.483 - CCoeEnv* aLoaderEnv = NULL );
1.484 - /**
1.485 - * LoadLC( TInt ) reads a resource string with memory allocation and
1.486 - * pushes the string onto the cleanup stack.
1.487 - *
1.488 - * @param aResourceId The numeric ID of the resource string to be read.
1.489 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.490 - * give this, CCoeEnv::Static is called to get it.
1.491 - * @return Pointer to a heap descriptor containing the resource
1.492 - * string. This pointer is in the cleanup stack. The calling
1.493 - * program should pop and destroy the heap descriptor when it is
1.494 - * no longer needed.
1.495 - *
1.496 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.497 - * CCoeEnv::Static returned NULL.
1.498 - */
1.499 - IMPORT_C static HBufC* LoadLC( TInt aResourceId,
1.500 - CCoeEnv* aLoaderEnv = NULL );
1.501 -
1.502 - /**
1.503 - * LoadLC( TInt, TInt ) reads a resource string with memory
1.504 - * allocation, replaces all \%N-strings in it with a replacement
1.505 - * TInt and pushes the string onto the cleanup stack. In debug builds
1.506 - * the Symbian OS panic mechanism is used to notify programming errors.
1.507 - *
1.508 - * @param aResourceId The numeric ID of the resource string to be read.
1.509 - * @param aInt the replacing TInt.
1.510 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.511 - * give this, CCoeEnv::Static is called to get it.
1.512 - * @return pointer to a heap descriptor containing the formatted
1.513 - * resource string. This pointer is in the cleanup stack.
1.514 - * The calling program should pop and destroy the heap
1.515 - * descriptor when it is no longer needed.
1.516 - *
1.517 - * @panic EKeyStringNotFound In debug build if the key string 'N' wasn't
1.518 - * found in formatting.
1.519 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.520 - * CCoeEnv::Static returned NULL.
1.521 - */
1.522 - IMPORT_C static HBufC* LoadLC( TInt aResourceId, TInt aInt,
1.523 - CCoeEnv* aLoaderEnv = NULL );
1.524 -
1.525 - /**
1.526 - * LoadLC( TInt, const TDesC& ) reads a resource string with memory
1.527 - * allocation, replaces all \%U-strings in it with a replacement
1.528 - * string and pushes the string onto the cleanup stack. In debug builds
1.529 - * the Symbian OS panic mechanism is used to notify programming errors.
1.530 - *
1.531 - * @param aResourceId The numeric ID of the resource string to be read.
1.532 - * @param aString Reference to the replacing string.
1.533 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.534 - * give this, CCoeEnv::Static is called to get it.
1.535 - * @return Pointer to a heap descriptor containing the formatted
1.536 - * resource string. This pointer is in the cleanup stack.
1.537 - * The calling program should pop and destroy the heap
1.538 - * descriptor when it is no longer needed.
1.539 - *
1.540 - * @panic EKeyStringNotFound In debug build if the key string 'U' wasn't
1.541 - * found in formatting.
1.542 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.543 - * CCoeEnv::Static returned NULL.
1.544 - */
1.545 - IMPORT_C static HBufC* LoadLC( TInt aResourceId,
1.546 - const TDesC& aString,
1.547 - CCoeEnv* aLoaderEnv = NULL );
1.548 -
1.549 - /**
1.550 - * LoadLC( TInt, const TDesC&, TInt ) reads a resource string
1.551 - * with memory allocation, replaces all \%N-strings in it with
1.552 - * a replacement TInt and the first \%U-strings in it with a replacement
1.553 - * string and pushes the string onto the cleanup stack. In debug builds
1.554 - * the Symbian OS panic mechanism is used to notify programming errors.
1.555 - *
1.556 - * @param aResourceId The numeric ID of the resource string to be
1.557 - * read.
1.558 - * @param aString Reference to the replacing string.
1.559 - * @param aInt The replacing TInt.
1.560 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.561 - * give this, CCoeEnv::Static is called to get it.
1.562 - * @return Pointer to a heap descriptor containing the formatted
1.563 - * resource string. This pointer is in the cleanup stack.
1.564 - * The calling program should pop and destroy the heap
1.565 - * descriptor when it is no longer needed.
1.566 - *
1.567 - * @panic EKeyStringNotFound In debug build if the key string 'N' or 'U'
1.568 - * wasn't found in formatting.
1.569 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.570 - * CCoeEnv::Static returned NULL.
1.571 - */
1.572 - IMPORT_C static HBufC* LoadLC( TInt aResourceId, const TDesC& aString,
1.573 - TInt aInt, CCoeEnv* aLoaderEnv = NULL );
1.574 -
1.575 - /**
1.576 - * LoadLC( TInt, const CArrayFix<TInt>& ) reads a resource string with
1.577 - * memory allocation, replaces the \%(index)N-strings in it with
1.578 - * replacement TInts from an array and pushes the string onto the
1.579 - * cleanup stack. In debug builds the Symbian OS panic mechanism is
1.580 - * used to notify programming errors.
1.581 - *
1.582 - * @param aResourceId The numeric ID of the resource string to be
1.583 - * read.
1.584 - * @param aInts Reference to the array including the replacing TInts.
1.585 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.586 - * give this, CCoeEnv::Static is called to get it.
1.587 - * @return Pointer to a heap descriptor containing the formatted
1.588 - * resource string. This pointer is in the cleanup stack.
1.589 - * The calling program should pop and destroy the heap
1.590 - * descriptor when it is no longer needed.
1.591 - *
1.592 - * @panic ETooManyArguments In debug build if too many replacing
1.593 - * elements in aInts array.
1.594 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.595 - * CCoeEnv::Static returned NULL.
1.596 - */
1.597 - IMPORT_C static HBufC* LoadLC( TInt aResourceId,
1.598 - const CArrayFix<TInt>& aInts,
1.599 - CCoeEnv* aLoaderEnv = NULL );
1.600 -
1.601 - /**
1.602 - * LoadLC( TInt, const MDesCArray& ) reads a resource string with
1.603 - * memory allocation, replaces the \%(index)U-strings in it with
1.604 - * replacement strings from an array and pushes the string onto the
1.605 - * cleanup stack. In debug builds the Symbian OS panic mechanism is
1.606 - * used to notify programming errors.
1.607 - *
1.608 - * @param aResourceId The numeric ID of the resource string to be read.
1.609 - * @param aStrings Reference to the array including pointers to the
1.610 - * replacing strings.
1.611 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.612 - * give this, CCoeEnv::Static is called to get it.
1.613 - * @return Pointer to a heap descriptor containing the formatted
1.614 - * resource string. This pointer is in the cleanup stack.
1.615 - * The calling program should pop and destroy the heap
1.616 - * descriptor when it is no longer needed.
1.617 - *
1.618 - * @panic ETooManyArguments In debug build if too many replacing
1.619 - * elements in aStrings array.
1.620 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.621 - * CCoeEnv::Static returned NULL.
1.622 - */
1.623 - IMPORT_C static HBufC* LoadLC( TInt aResourceId,
1.624 - const MDesCArray& aStrings,
1.625 - CCoeEnv* aLoaderEnv = NULL );
1.626 -
1.627 - /**
1.628 - * LoadLC( TInt, const MDesCArray&, const CArrayFix<TInt>& ) reads a
1.629 - * resource string with memory allocation, replaces the
1.630 - * \%(index)U-strings in it with replacement strings from an array and
1.631 - * the \%(index)N-strings in it with replacement TInts from another
1.632 - * array and pushes the string onto the cleanup stack. In debug builds
1.633 - * the Symbian OS panic mechanism is used to notify programming errors.
1.634 - *
1.635 - * @param aResourceId The numeric ID of the resource string to be read.
1.636 - * @param aStrings Reference to the array including pointers to the
1.637 - * replacing strings.
1.638 - * @param aInts Reference to the array including the replacing TInts.
1.639 - * @param aLoaderEnv Pointer to the control environment. If user doesn't
1.640 - * give this, CCoeEnv::Static is called to get it.
1.641 - * @return Pointer to a heap descriptor containing the formatted
1.642 - * resource string. This pointer is in the cleanup stack.
1.643 - * The calling program should pop and destroy the heap
1.644 - * descriptor when it is no longer needed.
1.645 - *
1.646 - * @panic ETooManyArguments In debug build if too many replacing
1.647 - * elements in aStrings and/or aInts arrays.
1.648 - * @leave KErrNotSupported Parameter aLoaderEnv is NULL and
1.649 - * CCoeEnv::Static returned NULL.
1.650 - */
1.651 - IMPORT_C static HBufC* LoadLC( TInt aResourceId,
1.652 - const MDesCArray& aStrings,
1.653 - const CArrayFix<TInt>& aInts,
1.654 - CCoeEnv* aLoaderEnv = NULL );
1.655 -
1.656 - private:
1.657 -
1.658 - /**
1.659 - * C++ default constructor.
1.660 - */
1.661 - StringLoader();
1.662 -
1.663 - // Prohibit copy constructor
1.664 - StringLoader( const StringLoader& );
1.665 - // Prohibit assigment operator
1.666 - StringLoader& operator= ( const StringLoader& );
1.667 -
1.668 - /**
1.669 - * FormatStringL( const TDesC&, const TDesC&, const TDesC& ) finds the
1.670 - * keystring from the source string and replaces it with the
1.671 - * replacement string.
1.672 - *
1.673 - * @param aSource Reference to the source string.
1.674 - * @param aKey Reference to the keystring.
1.675 - * @param aSubs Reference to the replacing string.
1.676 - * @param aDir directionality of the source text
1.677 - * @param aFound ETrue if there were any strongly directional
1.678 - * characters and EFalse if there were none
1.679 - * @return Pointer to a heap descriptor containing the formated string.
1.680 - */
1.681 - static HBufC* FormatStringL(
1.682 - const TDesC& aSource,
1.683 - const TDesC& aKey,
1.684 - const TDesC& aSubs,
1.685 - TBidiText::TDirectionality aDir
1.686 - );
1.687 -
1.688 - /**
1.689 - * FormatStringL( const TDesC&, const TDesC&, const TDesC& ) finds the
1.690 - * keystring from the source string and replaces it with the
1.691 - * replacement string.
1.692 - *
1.693 - * @param aSource Reference to the source string.
1.694 - * @param aKey Reference to the keystring.
1.695 - * @param aSubs Reference to the replacing string.
1.696 - * @param aDirectionality directionality of the source text
1.697 - * @param aParamCount Keeps track of remaining parameters.
1.698 - * Value KUnknownCount denotes that count is not known yet.
1.699 - * Value may be updated by this method to reflect change in count.
1.700 - * @param aSubCount Number of '|' separated substrings.
1.701 - * Value KUnknownCount denotes that count is not known yet.
1.702 - * @return Pointer to a heap descriptor containing the formated string.
1.703 - */
1.704 - static HBufC* FormatStringL(
1.705 - const TDesC& aSource,
1.706 - const TDesC& aKey,
1.707 - const TDesC& aSubs,
1.708 - TBidiText::TDirectionality aDirectionality,
1.709 - TInt& aParamCount,
1.710 - TInt aSubCount
1.711 - );
1.712 -
1.713 - /**
1.714 - * FormatStringL( HbufC*, const CArrayFix<TInt>&, TInt ) finds the
1.715 - * \%(index)N-keystrings from the source string and replaces it with the
1.716 - * replacement TInts.
1.717 - * @param aSource Reference to the source string.
1.718 - * @param aInts Reference to the array containing the replacing TInts.
1.719 - * @param aMax Maximum number of key strings in the resource string.
1.720 - * @return Pointer to a heap descriptor containing the formated string.
1.721 - */
1.722 - static HBufC* FormatStringL( TDesC& aSource,
1.723 - const CArrayFix<TInt>& aInts,
1.724 - TInt aMax,
1.725 - TBidiText::TDirectionality aDir
1.726 - );
1.727 -
1.728 - /**
1.729 - * FormatStringL( HbufC*, const MDesCArray&, TInt ) finds the
1.730 - * \%(index)U-keystrings from the source string and replaces it with the
1.731 - * replacement strings.
1.732 - *
1.733 - * @param aSource Reference to the source string.
1.734 - * @param aStrings Reference to the array containing pointers to the
1.735 - * replacing strings.
1.736 - * @param aMax Maximum number of key strings in the resource string.
1.737 - * @return Pointer to a heap descriptor containing the formated
1.738 - * string.
1.739 - */
1.740 - static HBufC* FormatStringL( TDesC& aSource,
1.741 - const MDesCArray& aStrings,
1.742 - TInt aMax,
1.743 - TBidiText::TDirectionality aDir
1.744 - );
1.745 - /**
1.746 - * Formater( TDes&, const TDesC&, const TDesC&, const TDesC& ) finds
1.747 - * the keystring from the source string and replaces it with the
1.748 - * replacement string. The formated string is stored in the destination
1.749 - * descriptor.
1.750 - *
1.751 - * @param aDest Reference to the destination descriptor.
1.752 - * @param aSource Reference to the source string.
1.753 - * @param aKey Reference to the keystring.
1.754 - * @param aSubs Reference to the replacing string.
1.755 - * @param aDirectionality directionality of the main text
1.756 - * @return Number of keystrings replaced.
1.757 - */
1.758 - static TInt Formater(
1.759 - TDes& aDest,
1.760 - const TDesC& aSource,
1.761 - const TDesC& aKey,
1.762 - const TDesC& aSubs,
1.763 - TBidiText::TDirectionality aDirectionality
1.764 - );
1.765 -
1.766 - /**
1.767 - * KeyStringFormater( TDes&, const TText&, TInt, const TDesC& ) formats
1.768 - * the keystring from given parameters.
1.769 - *
1.770 - * @param aDest Reference to the destination descriptor.
1.771 - * @param aKey Reference to the key letter.
1.772 - * @param aPosition index of the key string.
1.773 - * @param aKeyString Reference to the keystring.
1.774 - */
1.775 - static void KeyStringFormater( TDes& aDest, const TText& aKey,
1.776 - TInt aPosition, const TDesC& aKeyString );
1.777 -
1.778 - /**
1.779 - * Resolves directionality of the given source text.
1.780 - * Place-holder strings are removed so that they don't affect the result.
1.781 - */
1.782 - static TBidiText::TDirectionality ResolveDirectionality( TDes& aText, TBool* aFound );
1.783 -
1.784 - /**
1.785 - * Counts the number of parameters in the text.
1.786 - * Needed for correct memory allocations.
1.787 - *
1.788 - * @param aText Source text
1.789 - * @param aIndex Index to count. If index is invalid, counts all indexes.
1.790 - * @return Parameter count
1.791 - */
1.792 - static TInt GetParamCount( const TDesC& aText, TInt aIndex = -1);
1.793 -
1.794 - /**
1.795 - * Counts the number of substrings (separated by '|'s) in the text.
1.796 - * If no '|' is found, but aText length is greater than zero, return 1.
1.797 - * If aText length is zero, return zero.
1.798 - * Needed for correct memory allocations.
1.799 - *
1.800 - * @param aText Source text
1.801 - * @return Substring count
1.802 - */
1.803 - static TInt GetSubStringCount( const TDesC& aText );
1.804 -
1.805 - /**
1.806 - * Resolves directionality of the given source text.
1.807 - * Uses ResolveDirectionality().
1.808 - */
1.809 - static TBidiText::TDirectionality DirectionalityL( const TDesC& aText, TBool* aFound );
1.810 -
1.811 - /**
1.812 - * Resolves sub strings. Uses ResolveSubStringL()
1.813 - */
1.814 - static HBufC* ResolveSubStringDirsL( TDes& aText, TInt aCount, TBool* aMarker );
1.815 -
1.816 - /**
1.817 - * Resolves sub string and directionality of the sub string.
1.818 - * Adds no dir marker if directionality of the string not found.
1.819 - *
1.820 - * @param aText Source text. After returnig returned sub string
1.821 - * removed from aText.
1.822 - * @param aMarker After returning ETrue if no dir marker added, otherwise EFalse.
1.823 - * @return Substring
1.824 - */
1.825 - static HBufC* ResolveSubStringL( TDes& aText, TBool* aMarker );
1.826 -
1.827 - /**
1.828 - * Removes no dir markers from source text.
1.829 - *
1.830 - * @param aText Source text.
1.831 - */
1.832 - static void RemoveNoDirMarkers( TDes& aText );
1.833 -
1.834 - /**
1.835 - * Used by exported Format methods.
1.836 - */
1.837 - static void FormatL( TDes& aDest, const TDesC& aSource,
1.838 - const TDesC& aKeybuf, const TDesC& aSubs );
1.839 +public:
1.840 + IMPORT_C static void Load(TDes& aDest, TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);
1.841 + IMPORT_C static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, TInt aSubs);
1.842 + IMPORT_C static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, const TDesC& aSubs);
1.843 + IMPORT_C static HBufC* LoadL(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);
1.844 + IMPORT_C static HBufC* LoadL(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
1.845 + IMPORT_C static HBufC* LoadL(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL);
1.846 + IMPORT_C static HBufC* LoadL(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
1.847 + IMPORT_C static HBufC* LoadL(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
1.848 + IMPORT_C static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL);
1.849 + IMPORT_C static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
1.850 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);
1.851 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
1.852 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL);
1.853 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
1.854 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
1.855 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL);
1.856 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
1.857 };
1.858
1.859 #endif // STRINGLOADER_H
1.860
1.861 -// End of File