CAknUnitEditor Class Reference

API published in: S60 3rd Ed FP 2

Link against: avkon.lib eikctl.lib eikcoctl.lib uiklaf.lib form.lib

Capability Information

Required Capabilities

None

#include <aknuniteditor.h>

Inherits CEikMfne.

Detailed Description

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().


Public Member Functions
virtual	~CAknUnitEditor ()
	C++ destructor.
IMPORT_C void	ConstructL (TReal aMinimumValue, TReal aMaximumValue, TReal aInitialValue, TInt aMaxFractionalDigits, TInt aUnit, TUint aFlags=0)
	Second-phase constructor.
IMPORT_C void	ConstructFromResourceL (TResourceReader &aResourceReader)
	Second-phase constructor.
IMPORT_C TBool	SetValue (TReal aValue)
	Sets a value to the editor.
IMPORT_C TReal	Value () const
	Gets the value from the editor.
IMPORT_C TBool	SupportsUnit (TInt aUnit) const
	Tests if particular predefined unit type is supported.
IMPORT_C void	SetUnitL (const TDesC &aUnit)
	Sets the custom unit type.
IMPORT_C void	SetUnitL (TInt aUnit)
	Sets the predefined and localized unit type.
IMPORT_C TInt	GetUnit (TDes &aDes) const
	Gets the current unit type as a descriptor.
IMPORT_C TInt	Unit () const
	Gets the current unit type as an predefined unit type id, from the enum TAknUnitEditorUnits.
IMPORT_C void	SetMaxFractionalDigits (TInt aMaxFractionalDigits)
	Sets the maximum number of digits to show in the fractional part of the value.
IMPORT_C TInt	MaxFractionalDigits () const
	Gets the maximum number of digits in the fractional part of the value.
IMPORT_C void	SetMinimumAndMaximum (TReal aMinimumValue, TReal aMaximumValue)
	Sets the minimum and maximum editor values.
IMPORT_C void	GetMinimumAndMaximum (TReal &aMinimumValue, TReal &aMaximumValue) const
	Gets the minimum and maximum editor values.
IMPORT_C void	SetFlags (TUint aFlags)
	Sets the editor flags, see TAknUnitEditorFlags in eikon.hrh.
IMPORT_C TUint	Flags () const
	Gets the editor flags, see TAknUnitEditorFlags in eikon.hrh.
IMPORT_C void	PrepareForFocusLossL ()
	From CEikMfne.
Static Public Member Functions
static IMPORT_C CAknUnitEditor *	NewL ()
	Creates a new CAknUnitEditor object.
static IMPORT_C CAknUnitEditor *	NewLC ()
	Creates a new CAknUnitEditor object, leaving it in the cleanup stack.
Protected Member Functions
void	FocusChanged (TDrawNow aDrawNow)
	From CEikMfne.

Constructor & Destructor Documentation

virtual CAknUnitEditor::~CAknUnitEditor ( ) [virtual]

C++ destructor.

Deletes all owned member data.

Member Function Documentation

IMPORT_C void CAknUnitEditor::ConstructFromResourceL

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.

Parameters:

aResourceReader

A resource file reader.

Leave:: KErrNotSupported If the predefined unit type in the resource is not found.

See also:: AVKON_UNIT_EDITOR

IMPORT_C void CAknUnitEditor::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 not constructed from a resource.

Parameters:

	aMinimumValue	The minimum allowable value.
	aMaximumValue	The maximum allowable value.
	aInitialValue	The initial value, can be NaN if the editor is set to support it by using the EAknUnitEditorAllowedUninitialized flag.
	aMaxFractionalDigits	The maximum number of fractional digits.
	aUnit	The unit type, see TAknUnitEditorUnits in eikon.hrh. Can be set to EAknUnitEditorCustomUnit or zero if you plan on using a custom unit.
	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 also:: TAknUnitEditorUnits
TAknUnitEditorFlags

IMPORT_C TUint CAknUnitEditor::Flags

(

)

const

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

Returns:: The editor flags.

See also:: TAknUnitEditorFlags

void CAknUnitEditor::FocusChanged ( TDrawNow aDrawNow ) [protected, virtual]

From CEikMfne.

Deals with focus changes.

Parameters:

aDrawNow

Whether to draw the control immediately.

Reimplemented from CEikMfne.

IMPORT_C void CAknUnitEditor::GetMinimumAndMaximum	(	TReal &	aMinimumValue,
		TReal &	aMaximumValue
	)	const

Gets the minimum and maximum editor values.

Parameters:

	aMinimumValue	On return, contains the editor's minimum value
	aMaximumValue	On return, contains the editor's maximum value

IMPORT_C TInt CAknUnitEditor::GetUnit

Gets the current unit type as a descriptor.

This returns the textual representation of the unit field, regardless of the way it was set.

Parameters:

aDes

On return, contains the editor's unit type if it fits in the given descriptor.

Returns:: Zero, if the function executed successfully. Otherwise the minimum length needed for the editor's content.

IMPORT_C TInt CAknUnitEditor::MaxFractionalDigits

(

)

const

Gets the maximum number of digits in the fractional part of the value.

Returns:: The maximum number of digits in the fractional part

static IMPORT_C CAknUnitEditor* CAknUnitEditor::NewL ( ) [static]

Creates a new CAknUnitEditor object.

The client must call ConstructL() or ConstructFromResourceL() after calling this function.

Returns:: The created CAknUnitEditor.

static IMPORT_C CAknUnitEditor* CAknUnitEditor::NewLC ( ) [static]

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

The client must call ConstructL() or ConstructFromResourceL() after calling this function.

Returns:: The created CAknUnitEditor.

IMPORT_C void CAknUnitEditor::PrepareForFocusLossL ( ) [virtual]

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.

Reimplemented from CEikMfne.

IMPORT_C void CAknUnitEditor::SetFlags

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

Parameters:

aFlags

The editor flags. Note that this overrides all the flags. Use zero if no flags are desired.

See also:: TAknUnitEditorFlags

IMPORT_C void CAknUnitEditor::SetMaxFractionalDigits

(

TInt

aMaxFractionalDigits

)

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.

Parameters:

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 CAknUnitEditor::SetMinimumAndMaximum	(	TReal	aMinimumValue,
		TReal	aMaximumValue
	)

Sets the minimum and maximum editor values.

NaN values are not supported, and will cause undefined behaviour.

Parameters:

	aMinimumValue	The minimum allowable value
	aMaximumValue	The maximum allowable value

IMPORT_C void CAknUnitEditor::SetUnitL

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.

Parameters:

aUnit

The predefined unit type, from the enum TAknUnitEditorUnits.

Leave:: KErrNotSupported If the given predefined unit type is not found.

See also:: TAknUnitEditorUnits

IMPORT_C void CAknUnitEditor::SetUnitL

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.

Parameters:

aUnit

The unit type to be set.

IMPORT_C TBool CAknUnitEditor::SetValue

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.

Parameters:

aValue

The value to be set.

Returns:: 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 CAknUnitEditor::SupportsUnit

Tests if particular predefined unit type is supported.

Parameters:

aUnit

The predefined unit type, from the enum TAknUnitEditorUnits.