/*

 * 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