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