--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/classicui_plat/number_grouping_api/inc/NumberGrouping.h Tue Feb 02 01:00:49 2010 +0200
@@ -0,0 +1,351 @@
+/*
+* Copyright (c) 2002-2008 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: Provides formatting (grouping) for plain phone numbers
+*
+*
+*/
+
+
+#ifndef C_NUMBER_GROUPING_H
+#define C_NUMBER_GROUPING_H
+
+// #define __TEST_AS_EXE__ // put this in if you want all the test code to run and swap the mmps...
+
+#include "NumberGroupingStd.h"
+
+class TResourceReader;
+class CRegularExpression;
+class CPNGNumberGroupingExtension;
+
+/**
+* Engine class to format plain phone numbers by inserting grouping separators.
+* Both unformatted and formatted buffers are maintained by this class.
+* A reversed formatted buffer is also available to assist the client in performing wrapping.
+*
+* @lib NumberGrouping.lib
+*/
+NONSHARABLE_CLASS(CPNGNumberGrouping) : public CBase
+{
+
+/**
+* Central Repository key values for KNumberGrouping key in NumberGroupingCRKeys.h
+*/
+public:
+ enum TNumberGroupingCRValues
+ {
+ /** Number grouping disabled */
+ ENumberGroupingDisabled = 0,
+ /** Number grouping enabled (USA) */
+ ENumberGroupingEnabled = 1
+ };
+
+public:
+ IMPORT_C static CPNGNumberGrouping* NewL(TInt aMaxLength = 0, TBool aReversed = EFalse);
+ IMPORT_C static CPNGNumberGrouping* NewLC(TInt aMaxLength = 0, TBool aReversed = EFalse);
+ IMPORT_C ~CPNGNumberGrouping();
+
+ IMPORT_C TInt Insert(TInt aIndex, TText aChar);
+ IMPORT_C TInt Delete(TInt aIndex);
+ IMPORT_C TInt Append(TText aChar);
+
+ /**
+ * Sets the new unformatted phone number.
+ *
+ * Formatting does not actually occur until an API is called that accesses in some way the formatted buffer
+ * or one of its characteristics
+ *
+ * @param aNumber Ungrouped phone number to be copied into the NumberGrouping engine's unformatted buffer
+ * @return KErrOverflow if the number is too long for the length of the unformatted buffer
+ */
+ IMPORT_C TInt Set(const TDesC& aNumber);
+
+ /**
+ * @return Length of the currently formatted (grouped) buffer
+ */
+ IMPORT_C TInt Length() const;
+
+ /**
+ * @return Length of the currently unformatted buffer
+ */
+ IMPORT_C TInt UnFormattedLength() const;
+
+ /**
+ * This returns the maximum size of the unformatted buffer. This is the value that was provided during
+ * construction.
+ *
+ * Descriptors provided to Set() must be shorter than this length.
+ *
+ * @return maximum length of the unformatted buffer.
+ */
+ IMPORT_C TInt MaxDisplayLength() const;
+
+ /**
+ * Routine to determine if the character at a given position in the formatted phone number
+ * is a space character derived from the number grouping. That is, not part of the supplied phone number
+ * proper, but a space character from the number grouping.
+ *
+ * A client can check the descriptor returned by FormattedNumber() directly to perform a simple test
+ * of whether the character is a Space or not (whether or not derived from number grouping formatting)
+ *
+ * Note also that this returns EFalse if the character is some other formatting character besides
+ * space. To determine that, use IsCharacterInsertedByNumberGrouping().
+ *
+ * @param aPos The index of the character of interest
+ * @return EFalse iff the characer at aPos in the formatted buffer is a space coming from grouping
+ */
+ IMPORT_C TBool IsSpace(TInt aPos) const;
+
+ /**
+ * Access to section of the formatted buffer.
+ * This routine returns a descriptor for the indicated range in the formatted (grouped) internal
+ * buffer. If there are spaces at either end of the indicated section of the formatted buffer, then
+ * the returned descriptor is adjusted to point to the trimmed buffer in order to avoid the spaces.
+ *
+ * @param aFrom Inclusive starting index
+ * @param aTo Inclusive end index
+ * @return reference to const non-modifiable descriptor for the indicated, trimmed text
+ */
+ IMPORT_C const TDesC& FormattedNumber(TInt aFrom, TInt aTo) const;
+
+ IMPORT_C const TDesC& FormattedNumber() const;
+
+ /**
+ * Access to part of the reverse formatted number. If there are spaces at either end of the indicated
+ * section of the formatted buffer, then the returned descriptor is adjusted to point to the trimmed
+ * buffer in order to avoid the spaces.
+ *
+ * Returns KNullDesC if the feature has not been enabled by passing ETrue to the
+ * parameter aReversed during construction
+ *
+ * @param aFrom lower (inclusive) limit of the text to look at
+ * @param aTo upper (inclusive) limit of the text to look at
+ * @return Reference to descriptor containing the selected text
+ */
+ IMPORT_C const TDesC& ReverseFormattedNumber(TInt aFrom, TInt aTo) const;
+
+ /**
+ * Access to the reverse formatted number
+ *
+ * Returns KNullDesC if the feature has not been enabled by passing ETrue to the
+ * parameter aReversed during construction
+ *
+ * @return Reference to descriptor containing the reverse formatted text
+ */
+ IMPORT_C const TDesC& ReverseFormattedNumber() const;
+ IMPORT_C const TDesC& Selection(TInt aFrom, TInt aTo) const;
+
+ IMPORT_C const TDesC& UnFormattedNumber(TInt aFrom, TInt aTo) const;
+ IMPORT_C const TDesC& UnFormattedNumber() const;
+
+ /**
+ * This method allows the client to determine if the indexed character is a number grouping supplied
+ * character. Specifically, this means that this character originates in the number grouping formatting
+ * and not from the supplied unformatted phone number.
+ *
+ * Where the number has not been grouped (e.g. because there is an invalid phone number character in the
+ * supplied descriptor), this method returns EFalse, even if the character pointed to may be of the nature
+ * of a number grouping character. Use IsChangedByGrouping() to see if the number has been changed by
+ * grouping at all.
+ *
+ * Where a client is interested purely in the nature of the characters rather than whether they come from
+ * grouping or not, he may examine the examine the text via the descriptor reference returned by
+ * FormattedNumber().
+ *
+ * @since Series 60 2.6
+ * @param aPos The index provided is for the formatted number.
+ * @return EFalse iff the character at the supplied index is part of the supplied phone number
+ */
+ IMPORT_C TBool IsCharacterInsertedByNumberGrouping(TInt aPos) const;
+
+ /**
+ * Method to determine if the current number has been changed by number grouping.
+ * If this returns EFalse, then FormattedNumber() and UnFormattedNumber() refer to descriptors of with identical
+ * content.
+ * If this method returns ETrue, then the descriptors that would be returned by the two accessor APIs refer
+ * to descriptors with different content.
+ *
+ * @since Series 60 2.6
+ * @return ETrue iff formatting of the number has made an effective difference.
+ */
+ IMPORT_C TBool IsChangedByGrouping() const;
+
+ /**
+ * @return return iLanguage.
+ */
+ inline TLanguage Language() const;
+
+
+public:
+
+ TLanguage iForceLanguage;
+
+private: // private classes and enums
+
+ class TPNGSeparator
+ {
+ public:
+ TPNGSeparator();
+ TPNGSeparator( TInt aPos, TText aSeparatorCharacter );
+ public:
+ TInt iPosition;
+ TText iSeparatorCharacter;
+ };
+
+ class TPNGGroupingInfo
+ {
+ public:
+ TPNGGroupingInfo();
+ public:
+ TInt iMinNumberOfDigits;
+ TInt iMaxNumberOfDigits;
+ RArray<TPNGSeparator> iAfterPositions; // Positions of separators "after" the beginning
+ TPNGSeparator iBeforePosition; // Positions of separators "before" the end
+ };
+
+ // Constant for no pattern in use:
+ enum
+ {
+ ENoMatchedPattern = -1
+ };
+
+private: // Constructors
+ CPNGNumberGrouping( TInt aMaxLength, TBool aReserved);
+ void ConstructL();
+
+private:
+ TLanguage doReadLanguageFromSharedData() const;
+
+ void doReadFormatInfoFromResourceFileL();
+ void doClearGroupingItemsList();
+ void doClearFormattedNumbers();
+
+ void doNumberGroupingL() const;
+ void doNumberSquashing() const;
+
+ /**
+ * Read and process a single NUMBER_GROUPING_ITEM resource structure
+ */
+ void ReadGroupingSchemeL(
+ TResourceReader& aResourceReader,
+ RPointerArray<TDesC>& aGroupingPatternsList,
+ TInt& aMaxExtraCharacters );
+
+ /**
+ * Read and skip a single NUMBER_GROUPING_ITEM resource structure
+ */
+ void SkipGroupingSchemeL( TResourceReader& aResourceReader ) const;
+
+ /**
+ * Process the format pattern for "after positions"
+ */
+ void ParseForAfterPositions(
+ const TDesC& aFormatPattern,
+ TPNGGroupingInfo* aGroupingInfo,
+ const TDesC& aWildcardedMatchingPattern,
+ TInt& aMaxExtraCharacters,
+ TBool& trailingPossible ) const;
+
+ /**
+ * Process the format pattern for a before positions
+ */
+ void ParseForBeforePosition(
+ const TDesC& aFormatPattern,
+ CPNGNumberGrouping::TPNGGroupingInfo* aGroupingInfo,
+ TInt& aMaxExtraCharacters
+ ) const;
+
+ /**
+ * This routine is used to find a wildcarded version of the matching pattern
+ * provided in the "initialDigits" element for a grouping scheme read from resource.
+ * It uses the services of the CRegularExpression class, an instance of which is constructed
+ * with the provided aMatchString pattern only.
+ *
+ * The client must supply a modifiable descriptor long enough to hold the wildcarded version
+ * of the pattern.
+ *
+ * For each character index, if there is only one possible valid character, this puts in that
+ * character. If there are more than one, then the supplied aWildcardChar is inserted. The
+ * initialDigits element uses a full stop as a numeric wildcard; this is replaced with the nominated
+ * wildcard.
+ *
+ * Rules: (where 'n, has been passed is used as the wildcard)
+ * "<a numeric digit>" -> "<a numeric digit>"
+ * ( e.g. "1" -> "1" )
+ * "+" -> "+"
+ * "." -> "n"
+ * "[0-3]" -> "n"
+ *
+ * @param aMatchString Regular expression to provide example of
+ * @param aWildcardChar The character to put in the example pattern if there is no single
+ * valid character at that point
+ * @param aWildcardMatchString Descriptor to write the wildcarded match pattern into
+ */
+ void GetWildcardVersionOfMatchStringL(
+ const TDesC& aMatchString,
+ TText aWildcard,
+ TDes& aWildcardMatchString ) const;
+
+ /**
+ * This method expresses the policy of what characters may form part of a phone number
+ * Note that this method is valid even it there is no formatting going on. It is an intrinsic
+ * test on the character itself
+ */
+ TBool IsValidPhoneNumberCharacter(TText aCharacter) const;
+
+ /**
+ * Examines the unformatted number, counting how many digits are found before non-digit
+ * characters or the end is encountered.
+ * Returns 0 if Set() has not been called.
+ */
+ TInt LengthToGroup() const;
+
+ /**
+ * Perform number grouping using pattern at given index. Grouping is only applied to the leading
+ * aLengthToGroup characters.
+ */
+ void doNumberGroupingForPatternL( TInt aMatchedPattern, TInt aLengthToGroup ) const;
+
+private: // private data
+
+ HBufC* iUnformattedNumber;
+ mutable TPtrC iUnformattedNumberPtr;
+
+ mutable HBufC* iFormattedNumber;
+ mutable TPtrC iFormattedNumberPtr;
+
+ mutable HBufC* iReverseFormattedNumber;
+ mutable TPtrC iReverseFormattedNumberPtr;
+
+ mutable TPtrC iSelectionPtr;
+
+ mutable TLanguage iLanguage; // the system language
+ TInt iMaxUnformattedLength;
+ TBool iReversed;
+
+ CRegularExpression* iRegExp; // the patterns for matching
+ RPointerArray<TPNGGroupingInfo> iGroupingItemsList; // the formatting info
+
+ mutable TInt iMatchedPatternIndex; // keep track of what pattern is matched
+ CPNGNumberGroupingExtension* iExtension;
+};
+
+inline TLanguage CPNGNumberGrouping::Language() const
+ {
+ return iLanguage;
+ }
+
+
+#endif // C_NUMBER_GROUPING_H
+
+// End of File