1 /*

     2 * Copyright (c) 2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Unit multi-field numeric editor

    15 *

    16 */

    17 

    18 

    19 #ifndef CAKNUNITEDITOR_H

    20 #define CAKNUNITEDITOR_H

    21 

    22 #include <eikmfne.h>

    23 

    24 class CAknMfneFloat;

    25 class CAknMfneSeparator;

    26 

    27 /**

    28  * A multi-field numeric editor for displaying and editing a floating value

    29  * and an associated label.

    30  *

    31  * CAknUnitEditor is a multi-field numeric editor (MFNE), which is used for

    32  * displaying and editing floating point numeric data with a textual

    33  * label. Unit in the class name refers to a unit of measurement, for

    34  * example distance or speed, hence a typical use case might be an editor

    35  * which is used to edit an altitude value for a position in a GPS

    36  * application.

    37  *

    38  * Creating the editor is carried out by using either NewL() or

    39  * NewLC() function followed by a call to either ConstructL()

    40  * or ConstructFromResourceL() function. Note that if the editor is

    41  * not constructed fully, most functions will panic with KERN-EXEC 3.

    42  *

    43  * The value to be shown by the editor must be set at construction, and

    44  * can be later set using SetValue(). The current value of the editor

    45  * can be retrieved using Value().

    46  *

    47  * Minimum and maximum limits can be set using the function

    48  * SetMinimumAndMaximum(). NaN values for this function are

    49  * not supported, and will cause undefined behaviour.

    50  *

    51  * The editor supports a label shown next to the value. This label can be

    52  * set to a custom value (referred to as custom unit), or a set of

    53  * predefined and localized units can be used. See TAknUnitEditorUnits in

    54  * eikon.hrh and the two overloads of SetUnitL(). Note that the editor

    55  * discards the custom unit when a localized unit is set, so setting

    56  * the localized unit back to EAknUnitEditorCustomUnit clears

    57  * the unit.

    58  *

    59  * The editor supports variable number of fractional digits. A value

    60  * with no fractional part at all can also be displayed and edited. This

    61  * feature can be used with the function SetMaxFractionalDigits(), and

    62  * the corresponding getter MaxFractionalDigits(). Values set using

    63  * construction functions or SetValue() are rounded to correspond

    64  * with the number of fractional digits, so data loss may occur in such

    65  * case.

    66  *

    67  * The editor also supports an uninitialized state, which in practice means

    68  * that it can have nothing to display and in such case contains a

    69  * 'not a number' (NaN) value. This state can be allowed by the using the flag

    70  * EAknUnitEditorAllowUninitialized, found in TAknUnitEditorFlags in

    71  * eikon.hrh. For more information about NaN, see Math::IsNaN() and

    72  * TRealX::SetNaN().

    73  *

    74  * @lib eikctl.lib

    75  * @since S60 v3.2

    76  */

    77 NONSHARABLE_CLASS( CAknUnitEditor ) : public CEikMfne

    78     {

    79 public:

    80     /**

    81      * Creates a new CAknUnitEditor object. The client must call ConstructL()

    82      * or ConstructFromResourceL() after calling this function.

    83      *

    84      * @return The created CAknUnitEditor.

    85      */

    86     IMPORT_C static CAknUnitEditor* NewL();

    87     

    88     /**

    89      * Creates a new CAknUnitEditor object, leaving it in the cleanup stack.

    90      * The client must call ConstructL() or ConstructFromResourceL()

    91      * after calling this function.

    92      *

    93      * @return The created CAknUnitEditor.

    94      */

    95     IMPORT_C static CAknUnitEditor* NewLC();

    96 

    97     /**

    98      * C++ destructor. Deletes all owned member data.

    99      */

   100     virtual ~CAknUnitEditor();

   101 

   102     /**

   103      * Second-phase constructor. This should be called after creating a

   104      * new editor object with NewL() or NewLC(), if the

   105      * editor is not constructed from a resource.

   106      *

   107      * @param aMinimumValue The minimum allowable value.

   108      * @param aMaximumValue The maximum allowable value.

   109      * @param aInitialValue The initial value, can be NaN if the editor

   110      *                      is set to support it by using the

   111      *                      EAknUnitEditorAllowedUninitialized flag.

   112      * @param aMaxFractionalDigits The maximum number of fractional digits.

   113      * @param aUnit The unit type, see TAknUnitEditorUnits

   114      *              in eikon.hrh. Can be set to EAknUnitEditorCustomUnit

   115      *              or zero if you plan on using a custom unit.

   116      * @param aFlags The editor flags, see TAknUnitEditorFlags

   117      *               in eikon.hrh. This can be set to zero if no flags

   118      *               are desired. This is also the default parameter.

   119      * @leave KErrNotSupported If the given predefined unit type, aUnit,

   120      *                         is not found.

   121      * @see TAknUnitEditorUnits

   122      * @see TAknUnitEditorFlags

   123      */

   124     IMPORT_C void ConstructL(

   125         TReal aMinimumValue, TReal aMaximumValue,

   126         TReal aInitialValue,

   127         TInt aMaxFractionalDigits, TInt aUnit, TUint aFlags = 0 );

   128     

   129     /**

   130      * Second-phase constructor. This should be called after creating a

   131      * new editor object with NewL() or NewLC(), if the

   132      * editor is constructed from a resource. The resource structure

   133      * used in creating the editor is AVKON_UNIT_EDITOR.

   134      *

   135      * @param aResourceReader A resource file reader.

   136      * @leave KErrNotSupported If the predefined unit type in the resource

   137      *                         is not found.

   138      * @see AVKON_UNIT_EDITOR

   139      */        

   140     IMPORT_C void ConstructFromResourceL( TResourceReader& aResourceReader );

   141 

   142     /**

   143      * Sets a value to the editor. If the value is too large or small it is

   144      * set to maximum or minimum value, respectively. In case of an 

   145      * unallowed NaN the value is set to be the maximum value.

   146      *

   147      * @param aValue The value to be set.

   148      * @return ETrue, if the value was valid and not changed. The value is

   149      *         also considered to be valid in case it is rounded to the

   150      *         limits of the editor's maximum fractional digits.

   151      */

   152     IMPORT_C TBool SetValue( TReal aValue );

   153     

   154     /**

   155      * Gets the value from the editor.

   156      *

   157      * @return The value from the editor.

   158      */

   159     IMPORT_C TReal Value() const;

   160     

   161     /**

   162      * Tests if particular predefined unit type is supported.

   163      *

   164      * @param aUnit The predefined unit type, from the enum

   165      *              TAknUnitEditorUnits.

   166      * @return ETrue, if the given predefined unit type is supported.

   167      * @see TAknUnitEditorUnits

   168      */

   169     IMPORT_C TBool SupportsUnit( TInt aUnit ) const;

   170     

   171     /**

   172      * Sets the custom unit type. There's no actual limit for the length of

   173      * the text, but if the unit text overflows, it will not be wrapped.

   174      *

   175      * @param aUnit The unit type to be set.

   176      */

   177     IMPORT_C void SetUnitL( const TDesC& aUnit );

   178     

   179     /**

   180      * Sets the predefined and localized unit type. If the given unit type

   181      * is EAknUnitEditorCustomUnit, the unit field is emptied and a

   182      * subsequent call to SetUnitL( const TDesC& aUnit ) is needed.

   183      *

   184      * @param aUnit The predefined unit type, from the enum

   185      *              TAknUnitEditorUnits.

   186      * @leave KErrNotSupported If the given predefined unit type is not found.

   187      * @see TAknUnitEditorUnits

   188      */

   189     IMPORT_C void SetUnitL( TInt aUnit );

   190 

   191     /**

   192      * Gets the current unit type as a descriptor. This returns the textual

   193      * representation of the unit field, regardless of the way it was set.

   194      *

   195      * @param aDes On return, contains the editor's unit type if it fits in

   196      *             the given descriptor.

   197      * @return Zero, if the function executed successfully. Otherwise the

   198      *         minimum length needed for the editor's content.

   199      */

   200     IMPORT_C TInt GetUnit( TDes& aDes ) const;

   201     

   202     /**

   203      * Gets the current unit type as an predefined unit type id,

   204      * from the enum TAknUnitEditorUnits. Returns EAknUnitEditorCustomUnit

   205      * if the last unit set was a custom unit.

   206      *

   207      * @return The current unit type identifier. EAknUnitEditorCustomUnit

   208      *         if custom unit was set.

   209      * @see TAknUnitEditorUnits  

   210      */

   211     IMPORT_C TInt Unit() const;

   212 

   213     /**

   214      * Sets the maximum number of digits to show in the fractional part of

   215      * the value. The maximum number of fractional digits is limited

   216      * to eight. Setting a value outside of valid range (0 to 8) has

   217      * no effect in release builds, and panics in debug builds.

   218      *

   219      * @param aFractionalDigits The maximum number of digits in the

   220      *                          fractional part. Can be zero to eight.

   221      * @panic 1 In debug builds only, if aMaxFractionalDigits is out of

   222      *          range.

   223      */

   224     IMPORT_C void SetMaxFractionalDigits( TInt aMaxFractionalDigits );

   225     

   226     /**

   227      * Gets the maximum number of digits in the fractional part of the

   228      * value.

   229      *

   230      * @return The maximum number of digits in the fractional part

   231      */

   232     IMPORT_C TInt MaxFractionalDigits() const;

   233     

   234     /**

   235      * Sets the minimum and maximum editor values. NaN values are not

   236      * supported, and will cause undefined behaviour.

   237      *

   238      * @param aMinimumValue The minimum allowable value

   239      * @param aMaximumValue The maximum allowable value

   240      */

   241     IMPORT_C void SetMinimumAndMaximum(

   242         TReal aMinimumValue, TReal aMaximumValue );

   243     

   244     /**

   245      * Gets the minimum and maximum editor values.

   246      *

   247      * @param aMinimumValue On return, contains the editor's minimum value

   248      * @param aMaximumValue On return, contains the editor's maximum value

   249      */

   250     IMPORT_C void GetMinimumAndMaximum(

   251         TReal& aMinimumValue, TReal& aMaximumValue ) const;

   252         

   253     /**

   254      * Sets the editor flags, see TAknUnitEditorFlags in eikon.hrh.

   255      *

   256      * @param aFlags The editor flags. Note that this overrides all

   257      *               the flags. Use zero if no flags are desired.

   258      * @see TAknUnitEditorFlags

   259      */

   260     IMPORT_C void SetFlags( TUint aFlags );

   261     

   262     /**

   263      * Gets the editor flags, see TAknUnitEditorFlags in eikon.hrh.

   264      *

   265      * @return The editor flags.

   266      * @see TAknUnitEditorFlags

   267      */

   268     IMPORT_C TUint Flags() const;

   269     

   270 // from base class CEikMfne

   271 

   272     /**

   273      * From CEikMfne.

   274      * Validates the values in the editor. This function should be called

   275      * before removing focus from the editor.

   276      *

   277      * @leave KLeaveWithoutAlert If the value in the field had an error

   278      *                           in it.

   279      */

   280     IMPORT_C void PrepareForFocusLossL();

   281     

   282 protected:

   283 

   284     /**

   285      * From CEikMfne.

   286      * Deals with focus changes.

   287      *

   288      * @param aDrawNow Whether to draw the control immediately.

   289      */

   290      void FocusChanged( TDrawNow aDrawNow );

   291 

   292 private:

   293 

   294     /**

   295      * C++ constructor.

   296      */

   297     CAknUnitEditor();

   298     

   299     /**

   300      * Checks if the unit field label should be visible.

   301      *

   302      * @return ETrue, if the unit field should be visible.

   303      */

   304     TBool UnitFieldVisibility() const;

   305     

   306 private: // data

   307 

   308     /**

   309      * Bit flags

   310      */

   311     TUint iFlags;

   312     

   313     /**

   314      * The limit for predefined unit indices

   315      */

   316     const TInt iUnitLimit;

   317     

   318     /**

   319      * Value of the current unit type, as in enum

   320      * TAknUnitEditorUnits.

   321      */

   322     TInt iUnitType;

   323 

   324     /**

   325      * Helper pointer to float value field

   326      * Not own.

   327      */

   328     CAknMfneFloat* iFloatField;

   329     

   330     /**

   331      * Helper pointer to separator field

   332      * Not own.

   333      */

   334     CAknMfneSeparator* iSeparatorField;

   335     

   336     /**

   337      * Helper pointer to unit field

   338      * Not own.

   339      */

   340     CAknMfneSeparator* iUnitField;

   341     

   342     };

   343 

   344 #endif // CAKNUNITEDITOR_H