/*
* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.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