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