--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/textandlocutils/numbergrouping/inc/AknPhoneNumberGrouping.h Fri Jun 11 15:33:54 2010 +0300
@@ -0,0 +1,213 @@
+/*
+* Copyright (c) 2002-2004 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:
+*
+* This class gives feature variant - independent access to Series 60 number grouping
+* and provides digit type conversion.
+*
+*
+*/
+
+
+#ifndef AKNPHONENUMBERGROUPING_H
+#define AKNPHONENUMBERGROUPING_H
+
+// INCLUDES
+
+#include <e32std.h>
+#include <gdi.h>
+
+// CONSTANTS
+
+
+// CLASS DECLARATION
+
+class CPNGNumberGrouping;
+
+
+/**
+* This class acts as a wrapper for the Number Grouping engine (NumberGrouping.dll).
+* It exposes non-static API to the engine so that it can be used without the client code dealing with the
+* issues of
+* - build switches for calling numbergrouping API
+* - build switches for linking to NumberGrouping.lib
+* - checks on Feature Manager.
+*
+* It deals with these internally. In the case of __SERIES60_PHONE_NUMBER_GROUPING being #undef-ed, this
+* object acts as if there is a "null" phone number grouping.
+*
+* Static methods are included for those who are doing a small number of individual groupings of phone numbers,
+* say, when a view or popup is constructed, or a title pane is refreshed. These construct the object
+* internally within the static call.
+*
+* The class also deals with the conversion of numbers to potentially locale or setting-
+* specific number symbols, using the Series 60 platform policy.
+*
+* For repeated, frequent operations, the non-static API is recommended. Only a limited number of methods
+* from NumberGrouping.h are exposed, but these suffice in the main use cases.
+*
+* @lib Avkon.dll
+* @since 2.6
+*/
+NONSHARABLE_CLASS(CAknPhoneNumberGrouping) : public CBase
+ {
+ public:
+ // 2 stage constructors
+ IMPORT_C static CAknPhoneNumberGrouping* NewLC(TInt aUnformattedLength);
+ IMPORT_C static CAknPhoneNumberGrouping* NewL(TInt aUnformattedLength);
+
+ // Destructor
+ ~CAknPhoneNumberGrouping();
+
+ public: // non-static methods for using phone number grouping engine in the simplest cases
+
+ /**
+ * Load an ungrouped number into the phone number grouping engine
+ * This calls the CPNGNumberGrouping::Set within the engine
+ *
+ * @since 2.6
+ * @param aUngroupedNumber input ungrouped phone number
+ * @return KErrNone if there was no error
+ */
+ IMPORT_C TInt Set( const TDesC& aUngroupedNumber );
+
+ /**
+ * Returns a reference to the formatted number stored within the number grouping engine
+ *
+ * NOTE: This api does not convert to current digit type. This requires a method that takes
+ * a modifiable descriptor, so use CopyFormattedNumber( TDes& ) const
+ *
+ * This method is particularly useful for obtaining the size of the required buffer to copy
+ * the grouped phone number to by calling FormattedNumber.Length()
+ *
+ * @since 2.6
+ * @return reference to internally held formatted (grouped) phone number
+ */
+ IMPORT_C const TDesC& FormattedNumber() const;
+
+ /**
+ * Copies the grouped phone number stored in the object to the supplied output buffer,
+ * performing any current digit type conversion required.
+ *
+ * The length required for the supplied output descriptor must be greater or equal to the text waiting
+ * to be copied out of the instance. This can be determined before the call with no loss of
+ * performance with FormattedNumber().Length();
+ *
+ * The application will be Panicked (USER 11) if the output descriptor is too short.
+ *
+ * @since 2.6
+ * @param aGroupedNumber Output (grouped) descriptor to be written to. To avoid a panic, this
+ * must be at least as big as the formatted number currently stored.
+ */
+ IMPORT_C void CopyFormattedNumber( TDes& aGroupedNumber ) const;
+
+ public: // Static utility methods for doing the one-off grouping of phone numbers
+
+ /**
+ * Static utility method for doing one-off grouping of a phone number according to the current
+ * configuration.
+ *
+ * The method Leaves if the number grouping engine could not be allocated, or the output heap memory
+ * could not be allocated.
+ *
+ * @since 2.6
+ * @param aUngroupedNumber Input descriptor to be grouped
+ * @return Pointer to heap descriptor containing the grouped number
+ * Ownership is transferred to the caller
+ */
+ IMPORT_C static HBufC* CreateGroupedPhoneNumberL( const TDesC& aUngroupedNumber );
+
+ /**
+ * Static utility method for doing one-off grouping of a phone number according to the current
+ * configuration.
+ *
+ * The operations are internally trapped so as not to leave. The grouped number must fit into output
+ * descriptor, or else no grouping will take place and the input will just be copied to the output.
+ * A negative return value will indicate that the output did not fit, and by how much.
+ *
+ * The application will be Panicked (USER 11) if the output descriptor is too short even for an exact
+ * copy of the input.
+ *
+ * @since 2.6
+ * @param aUngroupedNumber Input descriptor to be grouped
+ * @param aGroupedNumber Output (grouped) descriptor to be written to
+ * @return If the entire grouped number could be copied to the output, then the
+ * returned number is zero or positive. This number represents the number
+ * of further characters in the grouped number that could have been accomodated.
+ * A negative return value indicates that the grouped number could not be
+ * copied, and that the ungrouped number had to be copied. The magnitude
+ * of the return value in this case is how many more characters would have
+ * been needed.
+ */
+ IMPORT_C static TInt GroupPhoneNumber( const TDesC& aUngroupedNumber, TDes& aGroupedNumber );
+
+ /**
+ * Static utility method for doing one-off grouping of a phone number according to the current
+ * configuration.
+ *
+ * The operations are internally trapped so as not to leave. The grouped number must fit into the one,
+ * input/output descriptor, or else no grouping will take place. A negative return value indicates that the
+ * grouped number did not fit.
+ *
+ * @since 2.6
+ * @param aUngroupedNumber Input descriptor to be grouped
+ * @return If the entire grouped number could be copied to the output, then the
+ * returned number is zero or positive. This number represents the number
+ * of further characters in the grouped number that could have been accomodated.
+ * A negative return value indicates that the grouped number could not be
+ * copied, and that the ungrouped number had to be copied. The magnitude
+ * of the return value in this case is how many more characters would have
+ * been needed.
+ */
+ IMPORT_C static TInt GroupPhoneNumber( TDes& aPhoneNumber );
+
+ private:
+ /**
+ * C++ constructor.
+ */
+ CAknPhoneNumberGrouping();
+
+ /**
+ * 2nd phase constructor is private.
+ */
+ void ConstructL( TInt aUnformattedLength );
+
+ /**
+ * Internal method for creating a phone number grouping engine and copying out the result to an
+ * output buffer.
+ *
+ * The creation of the engine may leave, in which case nothing else happens. But if it does not
+ * leave, an attempt will be made to copy the grouped phone number to aGroupedPhoneNumber.
+ * If there is enough space, it is copied and the amount of space in characters left over in
+ * the target buffer is returned. If it does not fit, then there is no copy made and the
+ * aExtraSpace contains a negative value, the additional length required.
+ *
+ * @param aUngroupedNumber Input descriptor containing a phone number
+ * @param aGroupedNumber Output descriptor for the grouped phone number
+ * @param aExtraSpace How much extra space there was in the output descriptor
+ * @return EFalse iff the grouped phone number was not copied.
+ */
+ static TBool DoFormatPhoneNumberL(
+ const TDesC& aUngroupedNumber,
+ TDes& aGroupedNumber,
+ TInt& aExtraSpace);
+
+ private:
+ // Owned number grouping engine
+ CPNGNumberGrouping* iNumberGroupingEngine;
+ };
+
+#endif
+
+// End of File