diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/mw/aknuniteditor.h --- a/epoc32/include/mw/aknuniteditor.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/mw/aknuniteditor.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,344 @@ -aknuniteditor.h +/* +* 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 + +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