williamr@2: /*
williamr@2: * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * 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
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef __TULTEXTRESOURCEUTILS_H__
williamr@2: #define __TULTEXTRESOURCEUTILS_H__
williamr@2: 
williamr@2: #include <e32std.h>
williamr@2: #include <e32base.h>	// class CArrayFix
williamr@2: #include <bamdesca.h>	// class MDesCArray
williamr@2: #include <biditext.h>	// class TBidiText
williamr@2: class CCoeEnv;
williamr@2: 
williamr@2: 
williamr@2: /**
williamr@2: Utility that provides methods to load and format resource strings.
williamr@2: String Loader API provides an interface to load and format resource strings
williamr@2: that may contain parameter(s) (\%U for (unicode) text or or \%N for numerical).
williamr@2: Resource strings are usually defined in an RSS file.
williamr@2: 
williamr@2: The API consists of the TulTextResourceUtils class. All methods are static, so there is
williamr@2: no need to explicitly allocate memory for the interface class.
williamr@2: The implementation needs a CCoeEnv instance to access for example the
williamr@2: resource files.
williamr@2: 
williamr@2: 
williamr@2: Usage:
williamr@2: 
williamr@2: Applications load and format resource strings from normal resources with
williamr@2: static methods of the TulTextResourceUtils class. The loading is done with the LoadL
williamr@2: and LoadLC methods and with the Load method in situations where memory
williamr@2: allocation from the heap is not possible. Formatting is done automatically
williamr@2: after loading in the LoadL and LoadLC methods, but it can also be done
williamr@2: separately with the Format method in situations where memory allocation from
williamr@2: the heap is not possible. For reading the resource strings with the Load,
williamr@2: LoadL and LoadLC methods, the user should provide a pointer to CCoeEnv for
williamr@2: efficiency reasons. If the pointer is not provided, the implementation uses
williamr@2: the CCoeEnv::Static method internally to get it.
williamr@2: 
williamr@2: Different size displays can handle different length strings. To take full
williamr@2: advantage of this fact, TulTextResourceUtils supports resource strings with multiple
williamr@2: options for strings, separated by the character 0x0001. Each such string can
williamr@2: contain the same or different sub string keys (\%U and \%N). TulTextResourceUtils returns
williamr@2: all strings, it is the responsibility of the caller to parse the result and
williamr@2: choose the proper string to display.
williamr@2: 
williamr@2: Setting the maximum sub string length may be done in the text resources. Sub
williamr@2: string maximum lengths can be localized separately for every language.
williamr@2: The maximum sub string length is of the format: \%U[NN]
williamr@2: where NN is a number [01..99]. Please note that NN must always consist of two
williamr@2: characters, i.e. if the sub string maximum length is eight characters, the
williamr@2: value to be used is 08, not plain 8. If the number of characters exceeds the
williamr@2: maximum length, the sub string is cut to fit and the last character is
williamr@2: replaced with an ellipsis character.
williamr@2: 
williamr@2: The following examples describe the usage of the String Loader API.
williamr@2: 
williamr@2: Usage when one TInt is added:
williamr@2: 
williamr@2: @code
williamr@2:  // In .loc -file
williamr@2:  // #define text_example "You have %N undone tasks."
williamr@2: 
williamr@2:  // In .rss -file
williamr@2:  // RESOURCE TBUF r_text_example { buf = text_example; }
williamr@2: 
williamr@2:  // (In the .cpp -file)
williamr@2:  #include <coeutils.h>
williamr@2: 
williamr@2:  // Get CCoeEnv instance
williamr@2:  CEikonEnv* iEikonEnv = CEikonEnv::Static();
williamr@2: 
williamr@2:  TInt number(324);
williamr@2: 
williamr@2:  // Method reads a resource string with memory allocation
williamr@2:  // and replaces the first %N-string in it with replacement TInt.
williamr@2:  // The heap descriptor must be destroyed when it is no longer needed.
williamr@2:  // iEikonEnv is needed for loading the resource string.
williamr@2:  HBufC* stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE, number, iEikonEnv);
williamr@2: 
williamr@2:  // The 'number' is added to the resource string. The result is
williamr@2:  // that stringholder points to a heap descriptor containing string:
williamr@2:  // "You have 324 undone tasks."
williamr@2: 
williamr@2:  // Delete the heap descriptor
williamr@2:  delete stringholder;
williamr@2: @endcode
williamr@2: 
williamr@2: 
williamr@2: Usage when several strings are added:
williamr@2: 
williamr@2: An index can be included to parameters. Several parameters can have same index
williamr@2: if the same replacement is needed multiple times.
williamr@2: 
williamr@2: @code
williamr@2:  // In .loc -file
williamr@2:  // #define text_example "I'm %2U%1U %3U%0U fine."
williamr@2: 
williamr@2:  // In .rss -file
williamr@2:  // RESOURCE TBUF r_text_example { buf = text_example; }
williamr@2: 
williamr@2:  // In the .cpp -file
williamr@2:  #include <coeutils.h>
williamr@2: 
williamr@2:  // Get CCoeEnv instance
williamr@2:  CEikonEnv* iEikonEnv = CEikonEnv::Static();
williamr@2: 
williamr@2:  CDesCArrayFlat* strings = new CDesCArrayFlat(4);
williamr@2:  CleanupStack::PushL(strings);
williamr@2: 
williamr@2:  strings->AppendL(_L("orking")); //First string
williamr@2: 
williamr@2:  strings->AppendL(_L("ll")); //Second string
williamr@2: 
williamr@2:  strings->AppendL(_L("sti")); //Third string
williamr@2: 
williamr@2:  strings->AppendL(_L("w")); //Fourth string
williamr@2: 
williamr@2:  // Method reads a resource string with memory allocation and replaces
williamr@2:  // the %(index)U strings in it with replacement strings from an array.
williamr@2:  // The heap descriptor must be destroyed when it is no longer needed.
williamr@2:  // iEikonEnv is needed for loading the resource string.
williamr@2:  HBufC* stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE, *strings, iEikonEnv);
williamr@2: 
williamr@2:  // Four strings are added to the resource string. The result is
williamr@2:  // that stringholder points to a heap descriptor containing string:
williamr@2:  // "I'm still working fine."
williamr@2: 
williamr@2:  // Pop and delete strings array
williamr@2:  CleanupStack::PopAndDestroy();
williamr@2: 
williamr@2:  // Delete the heap descriptor
williamr@2:  delete stringholder;
williamr@2: @endcode
williamr@2: 
williamr@2: 
williamr@2: Usage with scalable UI support:
williamr@2: 
williamr@2: @code
williamr@2:  // In .loc -file
williamr@2:  // #define TEXT_EXAMPLE "You have missed %N messages from %U."<0x0001>"Missed %N msgs from %U."<0x0001>"Missed %N msgs."
williamr@2: 
williamr@2:  // In .rss -file
williamr@2:  // RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; }
williamr@2: 
williamr@2:  // In the .cpp -file
williamr@2:  #include <coeutils.h>
williamr@2: 
williamr@2:  // Get CCoeEnv instance
williamr@2:  CEikonEnv* iEikonEnv = CEikonEnv::Static();
williamr@2: 
williamr@2:  TInt number(12);
williamr@2:  _LIT(name, "John Doe");
williamr@2: 
williamr@2:  // Method reads a resource string with memory allocation,
williamr@2:  // replaces all %N strings in it with a replacement TInt and
williamr@2:  // all %U strings in it with a replacement string.
williamr@2:  // The heap descriptor must be destroyed  when it is no longer needed.
williamr@2:  // iEikonEnv is needed for loading the resource string.
williamr@2:  HBufC stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE, name, number, iEikonEnv);
williamr@2: 
williamr@2:  // The number and name are added to the resource string. The result is
williamr@2:  // that stringholder points to a heap descriptor containing string:
williamr@2:  // "You have missed 12 messages from John Doe.\001Missed 12 msgs from John
williamr@2:  // Doe.\001Missed 12 msgs."
williamr@2: 
williamr@2:  // Delete the heap descriptor
williamr@2:  delete stringholder;
williamr@2: @endcode
williamr@2: 
williamr@2: 
williamr@2: Error handling:
williamr@2: 
williamr@2: The leave mechanism of the Symbian OS environment is used to handle memory
williamr@2: exhaustion. The panic mechanism is used to handle programming errors while
williamr@2: debugging. TulTextResourceUtils panics for seven different reasons. The panic 
williamr@2: category is named TulTextResourceUtils. The panic codes are:
williamr@2: 
williamr@2: - ETooFewArguments        = 0 (Unsolved parameters in resource string.)
williamr@2: - ETooManyArguments       = 1 (Already solved all parameters in  resource string.)
williamr@2: - EKeyStringNotFound      = 2 (The key string wasn't found in formatting.)
williamr@2: - EInvalidIndex           = 3 (Invalid index in Format-method)
williamr@2: - EDescriptorTooSmall     = 4 (Too small destination descriptor.)
williamr@2: - ECCoeEnvNotInitialized  = 5 (CCoeEnv is not initialized)
williamr@2: - EInvalidSubstitute      = 6 (Substituted string contains KSubStringSeparator)
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: NONSHARABLE_CLASS(TulTextResourceUtils)
williamr@2:     {
williamr@2: public:
williamr@2:     IMPORT_C static void Load(TDes& aDest, TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, TInt aSubs);
williamr@2:     IMPORT_C static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, const TDesC& aSubs);
williamr@2:     IMPORT_C static HBufC* LoadL(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadL(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadL(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadL(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadL(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadLC(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadLC(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadLC(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL);
williamr@2:     IMPORT_C static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
williamr@2: private:
williamr@2:     TulTextResourceUtils();
williamr@2:     TulTextResourceUtils(const TulTextResourceUtils&);	// Prohibit copy constructor
williamr@2:     TulTextResourceUtils& operator= (const TulTextResourceUtils&);	// Prohibit assigment operator
williamr@2:     static HBufC* FormatStringL(const TDesC& aSource, const TDesC& aKey, const TDesC& aSubs, TBidiText::TDirectionality aDir);
williamr@2:     static HBufC* FormatStringL(const TDesC& aSource, const TDesC& aKey, const TDesC& aSubs,
williamr@2:         						 TBidiText::TDirectionality aDirectionality, TInt& aParamCount, TInt aSubCount);
williamr@2:     static HBufC* FormatStringL(TDesC& aSource, const CArrayFix<TInt>& aInts, TInt aMax, TBidiText::TDirectionality aDir);
williamr@2:     static HBufC* FormatStringL(TDesC& aSource, const MDesCArray& aStrings, TInt aMax, TBidiText::TDirectionality aDir);
williamr@2:     static TInt Formater(TDes& aDest, const TDesC& aSource, const TDesC& aKey,
williamr@2:         					const TDesC& aSubs, TBidiText::TDirectionality aDirectionality);
williamr@2: 
williamr@2:     static void KeyStringFormater(TDes& aDest, const TText& aKey, TInt aPosition, const TDesC& aKeyString);
williamr@2:     static TBidiText::TDirectionality ResolveDirectionality(TDes& aText, TBool* aFound);
williamr@2:     static TInt GetParamCount(const TDesC& aText, TInt aIndex = -1);
williamr@2:     static TInt GetSubStringCount(const TDesC& aText);
williamr@2:         
williamr@2:     static TBidiText::TDirectionality DirectionalityL(const TDesC& aText, TBool* aFound);
williamr@2:     static HBufC* ResolveSubStringDirsL(TDes& aText, TInt aCount, TBool* aMarker);
williamr@2:     static HBufC* ResolveSubStringL(TDes& aText, TBool* aMarker);
williamr@2:     static void RemoveNoDirMarkers(TDes& aText);
williamr@2:     static void FormatL(TDes& aDest, const TDesC& aSource, const TDesC& aKeybuf, const TDesC& aSubs);
williamr@2:     };
williamr@2: 
williamr@2: 
williamr@2: #endif	// __TULTEXTRESOURCEUTILS_H__