1 stringloader.h

     1 /*

     2 * Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  String Loader API provides methods for loading resource

    15 *                strings and formatting them.

    16 *

    17 */

    18 

    19 #ifndef STRINGLOADER_H

    20 #define STRINGLOADER_H

    21 

    22 // INCLUDE FILES

    23 #include    <coemain.h>

    24 #include    <biditext.h>

    25 

    26 // CLASS DECLARATION

    27 

    28 /**

    29 * Class provides methods to load and format resource strings.

    30 * String Loader API provides an interface to load and format resource strings

    31 * that may contain parameter(s) (\%U for text or or \%N for numerical).

    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 */

   203 class StringLoader

   204     {

   205     public:

   206 

   207         /**

   208         * Load( TDes&, TInt ) reads a resource string without memory

   209         * allocation. The loaded string is stored in the destination TDes&.

   210         * Because this method doesn't allocate memory the destination 

   211         * descriptor must be long enough.

   212         *

   213         * @param aResourceId The numeric ID of the resource string to be read.

   214         * @param aDest Reference to the descriptor where the resource string

   215         *              is loaded.

   216         * @param aLoaderEnv Pointer to the control environment. If user doesn't

   217         *                   give this, CCoeEnv::Static is called to get it.

   218         *

   219         * @panic ECCoeEnvNotInitialized Parameter aLoaderEnv is NULL and 

   220         *                               CCoeEnv::Static returned NULL.

   221         */

   222         IMPORT_C static void Load( TDes& aDest, TInt aResourceId,

   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     };

   824 

   825 #endif      // STRINGLOADER_H

   826 

   827 // End of File