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 TResourceReader &  aResourceReader  ) 
 

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 TDes &  aDes  )  const
 

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 TUint  aFlags  ) 
 

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 TInt  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.

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 const TDesC &  aUnit  ) 
 

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 TReal  aValue  ) 
 

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 TInt  aUnit  )  const
 

Tests if particular predefined unit type is supported.

Parameters:
aUnit  The predefined unit type, from the enum TAknUnitEditorUnits.
Returns:
ETrue, if the given predefined unit type is supported.
See also:
TAknUnitEditorUnits
IMPORT_C TInt CAknUnitEditor::Unit  )  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.

Returns:
The current unit type identifier. EAknUnitEditorCustomUnit if custom unit was set.
See also:
TAknUnitEditorUnits
IMPORT_C TReal CAknUnitEditor::Value  )  const
 

Gets the value from the editor.

Returns:
The value from the editor.

The documentation for this class was generated from the following file:

Copyright © Nokia Corporation 2001-2008
Back to top