diff -r 000000000000 -r 2f259fa3e83a lafagnosticuifoundation/uigraphicsutils/tulinc/tultextresourceutils.h --- /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 +#include // class CArrayFix +#include // class MDesCArray +#include // 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 + + // 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 + + // 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 + + // 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& 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& 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& 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& 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& 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__