--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/classicui_pub/editors_api/inc/aknuniteditor.h Tue Feb 02 01:00:49 2010 +0200
@@ -0,0 +1,344 @@
+/*
+* Copyright (c) 2006 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: Unit multi-field numeric editor
+*
+*/
+
+
+#ifndef CAKNUNITEDITOR_H
+#define CAKNUNITEDITOR_H
+
+#include <eikmfne.h>
+
+class CAknMfneFloat;
+class CAknMfneSeparator;
+
+/**
+ * A multi-field numeric editor for displaying and editing a floating value
+ * and an associated label.
+ *
+ * CAknUnitEditor is a multi-field numeric editor (MFNE), which is used for
+ * displaying and editing floating point numeric data with a textual
+ * label. Unit in the class name refers to a unit of measurement, for
+ * example distance or speed, hence a typical use case might be an editor
+ * which is used to edit an altitude value for a position in a GPS
+ * application.
+ *
+ * Creating the editor is carried out by using either NewL() or
+ * NewLC() function followed by a call to either ConstructL()
+ * or ConstructFromResourceL() function. Note that if the editor is
+ * not constructed fully, most functions will panic with KERN-EXEC 3.
+ *
+ * The value to be shown by the editor must be set at construction, and
+ * can be later set using SetValue(). The current value of the editor
+ * can be retrieved using Value().
+ *
+ * Minimum and maximum limits can be set using the function
+ * SetMinimumAndMaximum(). NaN values for this function are
+ * not supported, and will cause undefined behaviour.
+ *
+ * The editor supports a label shown next to the value. This label can be
+ * set to a custom value (referred to as custom unit), or a set of
+ * predefined and localized units can be used. See TAknUnitEditorUnits in
+ * eikon.hrh and the two overloads of SetUnitL(). Note that the editor
+ * discards the custom unit when a localized unit is set, so setting
+ * the localized unit back to EAknUnitEditorCustomUnit clears
+ * the unit.
+ *
+ * The editor supports variable number of fractional digits. A value
+ * with no fractional part at all can also be displayed and edited. This
+ * feature can be used with the function SetMaxFractionalDigits(), and
+ * the corresponding getter MaxFractionalDigits(). Values set using
+ * construction functions or SetValue() are rounded to correspond
+ * with the number of fractional digits, so data loss may occur in such
+ * case.
+ *
+ * The editor also supports an uninitialized state, which in practice means
+ * that it can have nothing to display and in such case contains a
+ * 'not a number' (NaN) value. This state can be allowed by the using the flag
+ * EAknUnitEditorAllowUninitialized, found in TAknUnitEditorFlags in
+ * eikon.hrh. For more information about NaN, see Math::IsNaN() and
+ * TRealX::SetNaN().
+ *
+ * @lib eikctl.lib
+ * @since S60 v3.2
+ */
+NONSHARABLE_CLASS( CAknUnitEditor ) : public CEikMfne
+ {
+public:
+ /**
+ * Creates a new CAknUnitEditor object. The client must call ConstructL()
+ * or ConstructFromResourceL() after calling this function.
+ *
+ * @return The created CAknUnitEditor.
+ */
+ IMPORT_C static CAknUnitEditor* NewL();
+
+ /**
+ * Creates a new CAknUnitEditor object, leaving it in the cleanup stack.
+ * The client must call ConstructL() or ConstructFromResourceL()
+ * after calling this function.
+ *
+ * @return The created CAknUnitEditor.
+ */
+ IMPORT_C static CAknUnitEditor* NewLC();
+
+ /**
+ * C++ destructor. Deletes all owned member data.
+ */
+ virtual ~CAknUnitEditor();
+
+ /**
+ * Second-phase constructor. This should be called after creating a
+ * new editor object with NewL() or NewLC(), if the
+ * editor is not constructed from a resource.
+ *
+ * @param aMinimumValue The minimum allowable value.
+ * @param aMaximumValue The maximum allowable value.
+ * @param aInitialValue The initial value, can be NaN if the editor
+ * is set to support it by using the
+ * EAknUnitEditorAllowedUninitialized flag.
+ * @param aMaxFractionalDigits The maximum number of fractional digits.
+ * @param aUnit The unit type, see TAknUnitEditorUnits
+ * in eikon.hrh. Can be set to EAknUnitEditorCustomUnit
+ * or zero if you plan on using a custom unit.
+ * @param aFlags The editor flags, see TAknUnitEditorFlags
+ * in eikon.hrh. This can be set to zero if no flags
+ * are desired. This is also the default parameter.
+ * @leave KErrNotSupported If the given predefined unit type, aUnit,
+ * is not found.
+ * @see TAknUnitEditorUnits
+ * @see TAknUnitEditorFlags
+ */
+ IMPORT_C void ConstructL(
+ TReal aMinimumValue, TReal aMaximumValue,
+ TReal aInitialValue,
+ TInt aMaxFractionalDigits, TInt aUnit, TUint aFlags = 0 );
+
+ /**
+ * Second-phase constructor. This should be called after creating a
+ * new editor object with NewL() or NewLC(), if the
+ * editor is constructed from a resource. The resource structure
+ * used in creating the editor is AVKON_UNIT_EDITOR.
+ *
+ * @param aResourceReader A resource file reader.
+ * @leave KErrNotSupported If the predefined unit type in the resource
+ * is not found.
+ * @see AVKON_UNIT_EDITOR
+ */
+ IMPORT_C void ConstructFromResourceL( TResourceReader& aResourceReader );
+
+ /**
+ * Sets a value to the editor. If the value is too large or small it is
+ * set to maximum or minimum value, respectively. In case of an
+ * unallowed NaN the value is set to be the maximum value.
+ *
+ * @param aValue The value to be set.
+ * @return ETrue, if the value was valid and not changed. The value is
+ * also considered to be valid in case it is rounded to the
+ * limits of the editor's maximum fractional digits.
+ */
+ IMPORT_C TBool SetValue( TReal aValue );
+
+ /**
+ * Gets the value from the editor.
+ *
+ * @return The value from the editor.
+ */
+ IMPORT_C TReal Value() const;
+
+ /**
+ * Tests if particular predefined unit type is supported.
+ *
+ * @param aUnit The predefined unit type, from the enum
+ * TAknUnitEditorUnits.
+ * @return ETrue, if the given predefined unit type is supported.
+ * @see TAknUnitEditorUnits
+ */
+ IMPORT_C TBool SupportsUnit( TInt aUnit ) const;
+
+ /**
+ * Sets the custom unit type. There's no actual limit for the length of
+ * the text, but if the unit text overflows, it will not be wrapped.
+ *
+ * @param aUnit The unit type to be set.
+ */
+ IMPORT_C void SetUnitL( const TDesC& aUnit );
+
+ /**
+ * Sets the predefined and localized unit type. If the given unit type
+ * is EAknUnitEditorCustomUnit, the unit field is emptied and a
+ * subsequent call to SetUnitL( const TDesC& aUnit ) is needed.
+ *
+ * @param aUnit The predefined unit type, from the enum
+ * TAknUnitEditorUnits.
+ * @leave KErrNotSupported If the given predefined unit type is not found.
+ * @see TAknUnitEditorUnits
+ */
+ IMPORT_C void SetUnitL( TInt aUnit );
+
+ /**
+ * Gets the current unit type as a descriptor. This returns the textual
+ * representation of the unit field, regardless of the way it was set.
+ *
+ * @param aDes On return, contains the editor's unit type if it fits in
+ * the given descriptor.
+ * @return Zero, if the function executed successfully. Otherwise the
+ * minimum length needed for the editor's content.
+ */
+ IMPORT_C TInt GetUnit( TDes& aDes ) const;
+
+ /**
+ * Gets the current unit type as an predefined unit type id,
+ * from the enum TAknUnitEditorUnits. Returns EAknUnitEditorCustomUnit
+ * if the last unit set was a custom unit.
+ *
+ * @return The current unit type identifier. EAknUnitEditorCustomUnit
+ * if custom unit was set.
+ * @see TAknUnitEditorUnits
+ */
+ IMPORT_C TInt Unit() const;
+
+ /**
+ * Sets the maximum number of digits to show in the fractional part of
+ * the value. The maximum number of fractional digits is limited
+ * to eight. Setting a value outside of valid range (0 to 8) has
+ * no effect in release builds, and panics in debug builds.
+ *
+ * @param aFractionalDigits The maximum number of digits in the
+ * fractional part. Can be zero to eight.
+ * @panic 1 In debug builds only, if aMaxFractionalDigits is out of
+ * range.
+ */
+ IMPORT_C void SetMaxFractionalDigits( TInt aMaxFractionalDigits );
+
+ /**
+ * Gets the maximum number of digits in the fractional part of the
+ * value.
+ *
+ * @return The maximum number of digits in the fractional part
+ */
+ IMPORT_C TInt MaxFractionalDigits() const;
+
+ /**
+ * Sets the minimum and maximum editor values. NaN values are not
+ * supported, and will cause undefined behaviour.
+ *
+ * @param aMinimumValue The minimum allowable value
+ * @param aMaximumValue The maximum allowable value
+ */
+ IMPORT_C void SetMinimumAndMaximum(
+ TReal aMinimumValue, TReal aMaximumValue );
+
+ /**
+ * Gets the minimum and maximum editor values.
+ *
+ * @param aMinimumValue On return, contains the editor's minimum value
+ * @param aMaximumValue On return, contains the editor's maximum value
+ */
+ IMPORT_C void GetMinimumAndMaximum(
+ TReal& aMinimumValue, TReal& aMaximumValue ) const;
+
+ /**
+ * Sets the editor flags, see TAknUnitEditorFlags in eikon.hrh.
+ *
+ * @param aFlags The editor flags. Note that this overrides all
+ * the flags. Use zero if no flags are desired.
+ * @see TAknUnitEditorFlags
+ */
+ IMPORT_C void SetFlags( TUint aFlags );
+
+ /**
+ * Gets the editor flags, see TAknUnitEditorFlags in eikon.hrh.
+ *
+ * @return The editor flags.
+ * @see TAknUnitEditorFlags
+ */
+ IMPORT_C TUint Flags() const;
+
+// from base class CEikMfne
+
+ /**
+ * From CEikMfne.
+ * Validates the values in the editor. This function should be called
+ * before removing focus from the editor.
+ *
+ * @leave KLeaveWithoutAlert If the value in the field had an error
+ * in it.
+ */
+ IMPORT_C void PrepareForFocusLossL();
+
+protected:
+
+ /**
+ * From CEikMfne.
+ * Deals with focus changes.
+ *
+ * @param aDrawNow Whether to draw the control immediately.
+ */
+ void FocusChanged( TDrawNow aDrawNow );
+
+private:
+
+ /**
+ * C++ constructor.
+ */
+ CAknUnitEditor();
+
+ /**
+ * Checks if the unit field label should be visible.
+ *
+ * @return ETrue, if the unit field should be visible.
+ */
+ TBool UnitFieldVisibility() const;
+
+private: // data
+
+ /**
+ * Bit flags
+ */
+ TUint iFlags;
+
+ /**
+ * The limit for predefined unit indices
+ */
+ const TInt iUnitLimit;
+
+ /**
+ * Value of the current unit type, as in enum
+ * TAknUnitEditorUnits.
+ */
+ TInt iUnitType;
+
+ /**
+ * Helper pointer to float value field
+ * Not own.
+ */
+ CAknMfneFloat* iFloatField;
+
+ /**
+ * Helper pointer to separator field
+ * Not own.
+ */
+ CAknMfneSeparator* iSeparatorField;
+
+ /**
+ * Helper pointer to unit field
+ * Not own.
+ */
+ CAknMfneSeparator* iUnitField;
+
+ };
+
+#endif // CAKNUNITEDITOR_H