1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/mw/tultextresourceutils.h Wed Mar 31 12:27:01 2010 +0100
1.3 @@ -0,0 +1,250 @@
1.4 +/*
1.5 +* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* 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
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +
1.23 +#ifndef __TULTEXTRESOURCEUTILS_H__
1.24 +#define __TULTEXTRESOURCEUTILS_H__
1.25 +
1.26 +#include <e32std.h>
1.27 +#include <e32base.h> // class CArrayFix
1.28 +#include <bamdesca.h> // class MDesCArray
1.29 +#include <biditext.h> // class TBidiText
1.30 +class CCoeEnv;
1.31 +
1.32 +
1.33 +/**
1.34 +Utility that provides methods to load and format resource strings.
1.35 +String Loader API provides an interface to load and format resource strings
1.36 +that may contain parameter(s) (\%U for (unicode) text or or \%N for numerical).
1.37 +Resource strings are usually defined in an RSS file.
1.38 +
1.39 +The API consists of the TulTextResourceUtils class. All methods are static, so there is
1.40 +no need to explicitly allocate memory for the interface class.
1.41 +The implementation needs a CCoeEnv instance to access for example the
1.42 +resource files.
1.43 +
1.44 +
1.45 +Usage:
1.46 +
1.47 +Applications load and format resource strings from normal resources with
1.48 +static methods of the TulTextResourceUtils class. The loading is done with the LoadL
1.49 +and LoadLC methods and with the Load method in situations where memory
1.50 +allocation from the heap is not possible. Formatting is done automatically
1.51 +after loading in the LoadL and LoadLC methods, but it can also be done
1.52 +separately with the Format method in situations where memory allocation from
1.53 +the heap is not possible. For reading the resource strings with the Load,
1.54 +LoadL and LoadLC methods, the user should provide a pointer to CCoeEnv for
1.55 +efficiency reasons. If the pointer is not provided, the implementation uses
1.56 +the CCoeEnv::Static method internally to get it.
1.57 +
1.58 +Different size displays can handle different length strings. To take full
1.59 +advantage of this fact, TulTextResourceUtils supports resource strings with multiple
1.60 +options for strings, separated by the character 0x0001. Each such string can
1.61 +contain the same or different sub string keys (\%U and \%N). TulTextResourceUtils returns
1.62 +all strings, it is the responsibility of the caller to parse the result and
1.63 +choose the proper string to display.
1.64 +
1.65 +Setting the maximum sub string length may be done in the text resources. Sub
1.66 +string maximum lengths can be localized separately for every language.
1.67 +The maximum sub string length is of the format: \%U[NN]
1.68 +where NN is a number [01..99]. Please note that NN must always consist of two
1.69 +characters, i.e. if the sub string maximum length is eight characters, the
1.70 +value to be used is 08, not plain 8. If the number of characters exceeds the
1.71 +maximum length, the sub string is cut to fit and the last character is
1.72 +replaced with an ellipsis character.
1.73 +
1.74 +The following examples describe the usage of the String Loader API.
1.75 +
1.76 +Usage when one TInt is added:
1.77 +
1.78 +@code
1.79 + // In .loc -file
1.80 + // #define text_example "You have %N undone tasks."
1.81 +
1.82 + // In .rss -file
1.83 + // RESOURCE TBUF r_text_example { buf = text_example; }
1.84 +
1.85 + // (In the .cpp -file)
1.86 + #include <coeutils.h>
1.87 +
1.88 + // Get CCoeEnv instance
1.89 + CEikonEnv* iEikonEnv = CEikonEnv::Static();
1.90 +
1.91 + TInt number(324);
1.92 +
1.93 + // Method reads a resource string with memory allocation
1.94 + // and replaces the first %N-string in it with replacement TInt.
1.95 + // The heap descriptor must be destroyed when it is no longer needed.
1.96 + // iEikonEnv is needed for loading the resource string.
1.97 + HBufC* stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE, number, iEikonEnv);
1.98 +
1.99 + // The 'number' is added to the resource string. The result is
1.100 + // that stringholder points to a heap descriptor containing string:
1.101 + // "You have 324 undone tasks."
1.102 +
1.103 + // Delete the heap descriptor
1.104 + delete stringholder;
1.105 +@endcode
1.106 +
1.107 +
1.108 +Usage when several strings are added:
1.109 +
1.110 +An index can be included to parameters. Several parameters can have same index
1.111 +if the same replacement is needed multiple times.
1.112 +
1.113 +@code
1.114 + // In .loc -file
1.115 + // #define text_example "I'm %2U%1U %3U%0U fine."
1.116 +
1.117 + // In .rss -file
1.118 + // RESOURCE TBUF r_text_example { buf = text_example; }
1.119 +
1.120 + // In the .cpp -file
1.121 + #include <coeutils.h>
1.122 +
1.123 + // Get CCoeEnv instance
1.124 + CEikonEnv* iEikonEnv = CEikonEnv::Static();
1.125 +
1.126 + CDesCArrayFlat* strings = new CDesCArrayFlat(4);
1.127 + CleanupStack::PushL(strings);
1.128 +
1.129 + strings->AppendL(_L("orking")); //First string
1.130 +
1.131 + strings->AppendL(_L("ll")); //Second string
1.132 +
1.133 + strings->AppendL(_L("sti")); //Third string
1.134 +
1.135 + strings->AppendL(_L("w")); //Fourth string
1.136 +
1.137 + // Method reads a resource string with memory allocation and replaces
1.138 + // the %(index)U strings in it with replacement strings from an array.
1.139 + // The heap descriptor must be destroyed when it is no longer needed.
1.140 + // iEikonEnv is needed for loading the resource string.
1.141 + HBufC* stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE, *strings, iEikonEnv);
1.142 +
1.143 + // Four strings are added to the resource string. The result is
1.144 + // that stringholder points to a heap descriptor containing string:
1.145 + // "I'm still working fine."
1.146 +
1.147 + // Pop and delete strings array
1.148 + CleanupStack::PopAndDestroy();
1.149 +
1.150 + // Delete the heap descriptor
1.151 + delete stringholder;
1.152 +@endcode
1.153 +
1.154 +
1.155 +Usage with scalable UI support:
1.156 +
1.157 +@code
1.158 + // In .loc -file
1.159 + // #define TEXT_EXAMPLE "You have missed %N messages from %U."<0x0001>"Missed %N msgs from %U."<0x0001>"Missed %N msgs."
1.160 +
1.161 + // In .rss -file
1.162 + // RESOURCE TBUF R_TEXT_EXAMPLE { buf = TEXT_EXAMPLE; }
1.163 +
1.164 + // In the .cpp -file
1.165 + #include <coeutils.h>
1.166 +
1.167 + // Get CCoeEnv instance
1.168 + CEikonEnv* iEikonEnv = CEikonEnv::Static();
1.169 +
1.170 + TInt number(12);
1.171 + _LIT(name, "John Doe");
1.172 +
1.173 + // Method reads a resource string with memory allocation,
1.174 + // replaces all %N strings in it with a replacement TInt and
1.175 + // all %U strings in it with a replacement string.
1.176 + // The heap descriptor must be destroyed when it is no longer needed.
1.177 + // iEikonEnv is needed for loading the resource string.
1.178 + HBufC stringholder = TulTextResourceUtils::LoadL(R_TEXT_EXAMPLE, name, number, iEikonEnv);
1.179 +
1.180 + // The number and name are added to the resource string. The result is
1.181 + // that stringholder points to a heap descriptor containing string:
1.182 + // "You have missed 12 messages from John Doe.\001Missed 12 msgs from John
1.183 + // Doe.\001Missed 12 msgs."
1.184 +
1.185 + // Delete the heap descriptor
1.186 + delete stringholder;
1.187 +@endcode
1.188 +
1.189 +
1.190 +Error handling:
1.191 +
1.192 +The leave mechanism of the Symbian OS environment is used to handle memory
1.193 +exhaustion. The panic mechanism is used to handle programming errors while
1.194 +debugging. TulTextResourceUtils panics for seven different reasons. The panic
1.195 +category is named TulTextResourceUtils. The panic codes are:
1.196 +
1.197 +- ETooFewArguments = 0 (Unsolved parameters in resource string.)
1.198 +- ETooManyArguments = 1 (Already solved all parameters in resource string.)
1.199 +- EKeyStringNotFound = 2 (The key string wasn't found in formatting.)
1.200 +- EInvalidIndex = 3 (Invalid index in Format-method)
1.201 +- EDescriptorTooSmall = 4 (Too small destination descriptor.)
1.202 +- ECCoeEnvNotInitialized = 5 (CCoeEnv is not initialized)
1.203 +- EInvalidSubstitute = 6 (Substituted string contains KSubStringSeparator)
1.204 +
1.205 +@publishedAll
1.206 +@released
1.207 +*/
1.208 +NONSHARABLE_CLASS(TulTextResourceUtils)
1.209 + {
1.210 +public:
1.211 + IMPORT_C static void Load(TDes& aDest, TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);
1.212 + IMPORT_C static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, TInt aSubs);
1.213 + IMPORT_C static void Format(TDes& aDest, const TDesC& aSource, TInt aPosition, const TDesC& aSubs);
1.214 + IMPORT_C static HBufC* LoadL(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);
1.215 + IMPORT_C static HBufC* LoadL(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
1.216 + IMPORT_C static HBufC* LoadL(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL);
1.217 + IMPORT_C static HBufC* LoadL(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
1.218 + IMPORT_C static HBufC* LoadL(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
1.219 + IMPORT_C static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL);
1.220 + IMPORT_C static HBufC* LoadL(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
1.221 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, CCoeEnv* aLoaderEnv = NULL);
1.222 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
1.223 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, CCoeEnv* aLoaderEnv = NULL);
1.224 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, const TDesC& aString, TInt aInt, CCoeEnv* aLoaderEnv = NULL);
1.225 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
1.226 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, CCoeEnv* aLoaderEnv = NULL);
1.227 + IMPORT_C static HBufC* LoadLC(TInt aResourceId, const MDesCArray& aStrings, const CArrayFix<TInt>& aInts, CCoeEnv* aLoaderEnv = NULL);
1.228 +private:
1.229 + TulTextResourceUtils();
1.230 + TulTextResourceUtils(const TulTextResourceUtils&); // Prohibit copy constructor
1.231 + TulTextResourceUtils& operator= (const TulTextResourceUtils&); // Prohibit assigment operator
1.232 + static HBufC* FormatStringL(const TDesC& aSource, const TDesC& aKey, const TDesC& aSubs, TBidiText::TDirectionality aDir);
1.233 + static HBufC* FormatStringL(const TDesC& aSource, const TDesC& aKey, const TDesC& aSubs,
1.234 + TBidiText::TDirectionality aDirectionality, TInt& aParamCount, TInt aSubCount);
1.235 + static HBufC* FormatStringL(TDesC& aSource, const CArrayFix<TInt>& aInts, TInt aMax, TBidiText::TDirectionality aDir);
1.236 + static HBufC* FormatStringL(TDesC& aSource, const MDesCArray& aStrings, TInt aMax, TBidiText::TDirectionality aDir);
1.237 + static TInt Formater(TDes& aDest, const TDesC& aSource, const TDesC& aKey,
1.238 + const TDesC& aSubs, TBidiText::TDirectionality aDirectionality);
1.239 +
1.240 + static void KeyStringFormater(TDes& aDest, const TText& aKey, TInt aPosition, const TDesC& aKeyString);
1.241 + static TBidiText::TDirectionality ResolveDirectionality(TDes& aText, TBool* aFound);
1.242 + static TInt GetParamCount(const TDesC& aText, TInt aIndex = -1);
1.243 + static TInt GetSubStringCount(const TDesC& aText);
1.244 +
1.245 + static TBidiText::TDirectionality DirectionalityL(const TDesC& aText, TBool* aFound);
1.246 + static HBufC* ResolveSubStringDirsL(TDes& aText, TInt aCount, TBool* aMarker);
1.247 + static HBufC* ResolveSubStringL(TDes& aText, TBool* aMarker);
1.248 + static void RemoveNoDirMarkers(TDes& aText);
1.249 + static void FormatL(TDes& aDest, const TDesC& aSource, const TDesC& aKeybuf, const TDesC& aSubs);
1.250 + };
1.251 +
1.252 +
1.253 +#endif // __TULTEXTRESOURCEUTILS_H__