1 /*

     2 * Copyright (c) 2006-2009 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 "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef __TULTEXTRESOURCEUTILS_H__

    21 #define __TULTEXTRESOURCEUTILS_H__

    22 

    23 #include <e32std.h>

    24 #include <e32base.h>	// class CArrayFix

    25 #include <bamdesca.h>	// class MDesCArray

    26 #include <biditext.h>	// class TBidiText

    27 class CCoeEnv;

    28 

    29 

    30 /**

    31 Utility that provides methods to load and format resource strings.

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

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

    34 Resource strings are usually defined in an RSS file.

    35 

    36 The API consists of the TulTextResourceUtils class. All methods are static, so there is

    37 no need to explicitly allocate memory for the interface class.

    38 The implementation needs a CCoeEnv instance to access for example the

    39 resource files.

    40 

    41 

    42 Usage:

    43 

    44 Applications load and format resource strings from normal resources with

    45 static methods of the TulTextResourceUtils class. The loading is done with the LoadL

    46 and LoadLC methods and with the Load method in situations where memory

    47 allocation from the heap is not possible. Formatting is done automatically

    48 after loading in the LoadL and LoadLC methods, but it can also be done

    49 separately with the Format method in situations where memory allocation from

    50 the heap is not possible. For reading the resource strings with the Load,

    51 LoadL and LoadLC methods, the user should provide a pointer to CCoeEnv for

    52 efficiency reasons. If the pointer is not provided, the implementation uses

    53 the CCoeEnv::Static method internally to get it.

    54 

    55 Different size displays can handle different length strings. To take full

    56 advantage of this fact, TulTextResourceUtils supports resource strings with multiple

    57 options for strings, separated by the character 0x0001. Each such string can

    58 contain the same or different sub string keys (\%U and \%N). TulTextResourceUtils returns

    59 all strings, it is the responsibility of the caller to parse the result and

    60 choose the proper string to display.

    61 

    62 Setting the maximum sub string length may be done in the text resources. Sub

    63 string maximum lengths can be localized separately for every language.

    64 The maximum sub string length is of the format: \%U[NN]

    65 where NN is a number [01..99]. Please note that NN must always consist of two

    66 characters, i.e. if the sub string maximum length is eight characters, the

    67 value to be used is 08, not plain 8. If the number of characters exceeds the

    68 maximum length, the sub string is cut to fit and the last character is

    69 replaced with an ellipsis character.

    70 

    71 The following examples describe the usage of the String Loader API.

    72 

    73 Usage when one TInt is added:

    74 

    75 @code

    76  // In .loc -file

    77  // #define text_example "You have %N undone tasks."

    78 

    79  // In .rss -file

    80  // RESOURCE TBUF r_text_example { buf = text_example; }

    81 

    82  // (In the .cpp -file)

    83  #include <coeutils.h>

    84 

    85  // Get CCoeEnv instance

    86  CEikonEnv* iEikonEnv = CEikonEnv::Static();

    87 

    88  TInt number(324);

    89 

    90  // Method reads a resource string with memory allocation

    91  // and replaces the first %N-string in it with replacement TInt.

    92  // The heap descriptor must be destroyed when it is no longer needed.

    93  // iEikonEnv is needed for loading the resource string.

    94  HBufC* stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE, number, iEikonEnv);

    95 

    96  // The 'number' is added to the resource string. The result is

    97  // that stringholder points to a heap descriptor containing string:

    98  // "You have 324 undone tasks."

    99 

   100  // Delete the heap descriptor

   101  delete stringholder;

   102 @endcode

   103 

   104 

   105 Usage when several strings are added:

   106 

   107 An index can be included to parameters. Several parameters can have same index

   108 if the same replacement is needed multiple times.

   109 

   110 @code

   111  // In .loc -file

   112  // #define text_example "I'm %2U%1U %3U%0U fine."

   113 

   114  // In .rss -file

   115  // RESOURCE TBUF r_text_example { buf = text_example; }

   116 

   117  // In the .cpp -file

   118  #include <coeutils.h>

   119 

   120  // Get CCoeEnv instance

   121  CEikonEnv* iEikonEnv = CEikonEnv::Static();

   122 

   123  CDesCArrayFlat* strings = new CDesCArrayFlat(4);

   124  CleanupStack::PushL(strings);

   125 

   126  strings->AppendL(_L("orking")); //First string

   127 

   128  strings->AppendL(_L("ll")); //Second string

   129 

   130  strings->AppendL(_L("sti")); //Third string

   131 

   132  strings->AppendL(_L("w")); //Fourth string

   133 

   134  // Method reads a resource string with memory allocation and replaces

   135  // the %(index)U strings in it with replacement strings from an array.

   136  // The heap descriptor must be destroyed when it is no longer needed.

   137  // iEikonEnv is needed for loading the resource string.

   138  HBufC* stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE, *strings, iEikonEnv);

   139 

   140  // Four strings are added to the resource string. The result is

   141  // that stringholder points to a heap descriptor containing string:

   142  // "I'm still working fine."

   143 

   144  // Pop and delete strings array

   145  CleanupStack::PopAndDestroy();

   146 

   147  // Delete the heap descriptor

   148  delete stringholder;

   149 @endcode

   150 

   151 

   152 Usage with scalable UI support:

   153 

   154 @code

   155  // In .loc -file

   156  // #define TEXT_EXAMPLE "You have missed %N messages from %U."<0x0001>"Missed %N msgs from %U."<0x0001>"Missed %N msgs."

   157 

   158  // In .rss -file

   159  // RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; }

   160 

   161  // In the .cpp -file

   162  #include <coeutils.h>

   163 

   164  // Get CCoeEnv instance

   165  CEikonEnv* iEikonEnv = CEikonEnv::Static();

   166 

   167  TInt number(12);

   168  _LIT(name, "John Doe");

   169 

   170  // Method reads a resource string with memory allocation,

   171  // replaces all %N strings in it with a replacement TInt and

   172  // all %U strings in it with a replacement string.

   173  // The heap descriptor must be destroyed  when it is no longer needed.

   174  // iEikonEnv is needed for loading the resource string.

   175  HBufC stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE, name, number, iEikonEnv);

   176 

   177  // The number and name are added to the resource string. The result is

   178  // that stringholder points to a heap descriptor containing string:

   179  // "You have missed 12 messages from John Doe.\001Missed 12 msgs from John

   180  // Doe.\001Missed 12 msgs."

   181 

   182  // Delete the heap descriptor

   183  delete stringholder;

   184 @endcode

   185 

   186 

   187 Error handling:

   188 

   189 The leave mechanism of the Symbian OS environment is used to handle memory

   190 exhaustion. The panic mechanism is used to handle programming errors while

   191 debugging. TulTextResourceUtils panics for seven different reasons. The panic 

   192 category is named TulTextResourceUtils. The panic codes are:

   193 

   194 - ETooFewArguments        = 0 (Unsolved parameters in resource string.)

   195 - ETooManyArguments       = 1 (Already solved all parameters in  resource string.)

   196 - EKeyStringNotFound      = 2 (The key string wasn't found in formatting.)

   197 - EInvalidIndex           = 3 (Invalid index in Format-method)

   198 - EDescriptorTooSmall     = 4 (Too small destination descriptor.)

   199 - ECCoeEnvNotInitialized  = 5 (CCoeEnv is not initialized)

   200 - EInvalidSubstitute      = 6 (Substituted string contains KSubStringSeparator)

   201 

   202 @publishedAll

   203 @released

   204 */

   205 NONSHARABLE_CLASS(TulTextResourceUtils)

   206     {

   207 public:

   208     IMPORT_C static void Load(TDes& aDest, TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);

   209     IMPORT_C static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, TInt aSubs);

   210     IMPORT_C static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, const TDesC& aSubs);

   211     IMPORT_C static HBufC* LoadL(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);

   212     IMPORT_C static HBufC* LoadL(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL);

   213     IMPORT_C static HBufC* LoadL(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL);

   214     IMPORT_C static HBufC* LoadL(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL);

   215     IMPORT_C static HBufC* LoadL(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);

   216     IMPORT_C static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL);

   217     IMPORT_C static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);

   218     IMPORT_C static HBufC* LoadLC(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);

   219     IMPORT_C static HBufC* LoadLC(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL);

   220     IMPORT_C static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL);

   221     IMPORT_C static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL);

   222     IMPORT_C static HBufC* LoadLC(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);

   223     IMPORT_C static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL);

   224     IMPORT_C static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);

   225 private:

   226     TulTextResourceUtils();

   227     TulTextResourceUtils(const TulTextResourceUtils&);	// Prohibit copy constructor

   228     TulTextResourceUtils& operator= (const TulTextResourceUtils&);	// Prohibit assigment operator

   229     static HBufC* FormatStringL(const TDesC& aSource, const TDesC& aKey, const TDesC& aSubs, TBidiText::TDirectionality aDir);

   230     static HBufC* FormatStringL(const TDesC& aSource, const TDesC& aKey, const TDesC& aSubs,

   231         						 TBidiText::TDirectionality aDirectionality, TInt& aParamCount, TInt aSubCount);

   232     static HBufC* FormatStringL(TDesC& aSource, const CArrayFix<TInt>& aInts, TInt aMax, TBidiText::TDirectionality aDir);

   233     static HBufC* FormatStringL(TDesC& aSource, const MDesCArray& aStrings, TInt aMax, TBidiText::TDirectionality aDir);

   234     static TInt Formater(TDes& aDest, const TDesC& aSource, const TDesC& aKey,

   235         					const TDesC& aSubs, TBidiText::TDirectionality aDirectionality);

   236 

   237     static void KeyStringFormater(TDes& aDest, const TText& aKey, TInt aPosition, const TDesC& aKeyString);

   238     static TBidiText::TDirectionality ResolveDirectionality(TDes& aText, TBool* aFound);

   239     static TInt GetParamCount(const TDesC& aText, TInt aIndex = -1);

   240     static TInt GetSubStringCount(const TDesC& aText);

   241         

   242     static TBidiText::TDirectionality DirectionalityL(const TDesC& aText, TBool* aFound);

   243     static HBufC* ResolveSubStringDirsL(TDes& aText, TInt aCount, TBool* aMarker);

   244     static HBufC* ResolveSubStringL(TDes& aText, TBool* aMarker);

   245     static void RemoveNoDirMarkers(TDes& aText);

   246     static void FormatL(TDes& aDest, const TDesC& aSource, const TDesC& aKeybuf, const TDesC& aSubs);

   247     };

   248 

   249 

   250 #endif	// __TULTEXTRESOURCEUTILS_H__