Numeric Editors

Numeric editors are single-line editors that limit the characters that users can enter into them to numeric types. Series 60 supplies three different editors that can be used to enter numeric data:

• Integer editor.

• Floating-Point Number editor.

• Fixed-Point Number editor.

All numeric editors have characteristics that determine their behavior, as shown in Table 8-11.

In addition to these, the fixed-point number editor can specify of the number of places to keep after the decimal.

The resource structures and classes used for the numeric editors are shown in Table 8-12.

Table 8-11. Numeric Editor Characteristics

Characteristic	Description
Minimum and Maximum Values	This sets the valid range of values for the editor. As you will see in the NumericEditor example, each editor deals with out-of-range values differently.
Default Value	This specifies the editor's initial value. All editors specify a default, although the integer editor's default is referred to as the " unset_value ".
Maximum Length	This is the maximum number of characters that the editor can hold. Nonnumeric characters, such as decimal points, count as well ”take this into account when specifying a maximum length.

Table 8-12. Numeric Editor Resources and Classes

Numeric Editor	Class	Resource	Control
Floating-Point	CEikFloatingPointEditor	FLPTED	EEikCtFlPtEd
Integer	CAknIntegerEdwin	AVKON_INTEGER_EDWIN	EAknCtIntegerEdwin
Fixed-Point	CEikFixedPointEditor	FIXPTED	EEikCtFxPtEd

Configuring Numeric Editors

The example application NumericEditor shows you how to define resources for an integer and fixed-point editor, and how to set, get and validate values in any numeric editor. It allows the user to enter and edit minimal details for the employees of a company, and displays brief details of them in a list. The main screen of NumericEditor is shown in Figure 8-8.

Figure 8-8. The NumericEditor list screen.

Selecting New from the Options menu allows the user to add a new employee by filling in a form. Selecting Open allows the user to edit an existing employee's details. The form for creating and editing entries is shown in Figure 8-9.

Figure 8-9. The NumericEditor form containing numeric editors.

This form contains two numeric editors: age (an integer editor) and salary (a fixed-point editor).

NumericEditor is based on the form example, OpponentForm , and so details of the form or the list will not be covered here. See Chapter 6 for more information on forms, and Chapter 7 for more information on lists.

Defining an Integer Editor Resource

You define an integer editor in an AVKON_INTEGER_EDWIN resource, as shown in Table 8-12. In NumericEditor , a form contains the editors, so the resource is defined in one of the dialog lines of the r_numericeditor_form resource. The form uses the AVKON_INTEGER_EDWIN to construct a CAknIntegerEdwin . Part of the form resource is shown below:

 ... Control = AVKON_INTEGER_EDWIN    {    maxlength = 2;    min = 18;    max = 70;    unset_value = 18;    }; ... 

The editor definition specifies default values for all of its fields. The maxlength value of 2 provides for a two-digit number ”note that for floating-point editors, this value must be incremented by 1 to accommodate the decimal point. The minimum value is set to 18 and the maximum is set to 70 ”note that you can specify negative numbers if this is appropriate to your application. unset_value is the default value for the editor, and here this is also set to 18 .

Unlike other numeric editors, there are no checks in an integer editor ( CAknIntegerEdwin ) that prevent you from setting the maximum to be less than the minimum!

Defining a Fixed-Point Editor Resource

The NumericEditor example's fixed-point editor is defined in a FIXPTED resource, as shown in Table 8-12. As before, this resource is defined in one of the dialog lines of the r_numericeditor_form resource. The form uses the FIXPTED resource to construct a CEikFixedPointEditor , and the relevant part of the form resource is shown here:

 ... control = FIXPTED    {    decimalplaces = 2;    min = 0;    max = 10000000;      // 100000.00 with the decimal point shifted 2 decimal places.    default = 0;    }; ... 

As with the integer editor, each field has a default value. Unlike the integer editor, however, if you specify a maximum value less than the minimum, then the CEikFixedPointEditor editor object will panic on construction.

Obtaining and Validating the Value in a Numeric Editor

Integer editors provide access to their values via the GetTextAsInteger() method, floating-point editors use the GetValueAsReal() method, and fixed-point editors use the GetValueAsInteger() method.

Note that fixed-point editors actually store and manipulate integer values ”to obtain the actual numeric value held, you need to divide by 10 ^N , where N is the number of decimal places set for the editor. Floating-point editors work with TReal values, as you would expect.

In the NumericEditor example, values are retrieved from the editors at the point where the form data is saved in CNumericEditorForm::SaveFormDataL() :

[View full width]

 
 [View full width] 
 ... CAknIntegerEdwin* ageEditor = static_cast<CAknIntegerEdwin*>(ControlOrNull  (ENumericEditorDlgCIdIntegerEdwin)); if (ageEditor)    {    TInt age = 0;    CAknNumericEdwin::TValidationStatus ageStatus = ageEditor->GetTextAsInteger(age);    switch (ageStatus)       {       case CAknNumericEdwin::EValueValid:          {          iEmployee.SetAge(age);          break;          }       ...       }    } CEikFixedPointEditor* salaryEditor = static_cast<CEikFixedPointEditor*>(ControlOrNull  (ENumericEditorDlgCIdFxPtEd)); if (salaryEditor)    {    TInt salary = 0;    CAknNumericEdwin::TValidationStatus salaryStatus = salaryEditor->GetValueAsInteger(salary);   switch (salaryStatus)      {      case CAknNumericEdwin::EValueValid:         {         iEmployee.SetSalary(salary);         break;         }      ...      }   } ... 

GetTextAsInteger() is called to obtain and subsequently validate the age in the integer editor. The method is passed a reference to a TInt , which it sets to the value contained in the editor, and returns an enumerated TValidationStatus value. This represents the validity of the numeric value set, and it can be any of the following values:

• EValueValid ” if the value is valid.

• EValueTooLarge ” if the value is greater than the maximum.

• EvalueTooSmall ” if the value is less than the minimum.

• EValueNotParsed ” if the value was not a valid number.

GetValueAsInteger() is similarly called to obtain and validate the salary in the fixed-point editor. Note that fixed-point and floating-point editors actually validate their value whenever they lose focus. If the current value is outside of the minimum and maximum value constraints, then it is set to the closest legal value. This means that the NumericEditor example does not actually need to validate the value obtained from the fixed-point salary editor.

Setting the Value in a Numeric Editor

You can set the value in a numeric editor using the SetValueL() method. In NumericEditor , this occurs when the form is loaded in the LoadFormValuesFromDataL() method, part of which is shown below:

[View full width]

 
 [View full width] 
 ... CAknIntegerEdwin* ageEditor = static_cast<CAknIntegerEdwin*>(ControlOrNull  (ENumericEditorDlgCIdIntegerEdwin)); if (ageEditor)    {    ageEditor->SetValueL(iEmployee.Age());    } CEikFixedPointEditor* salaryEditor = static_cast<CEikFixedPointEditor*>(ControlOrNull  (ENumericEditorDlgCIdFxPtEd)); if (salaryEditor)   {   TInt salary = iEmployee.Salary();   salaryEditor->SetValueL(&salary);   } ... 

The parameter required by SetValueL() depends on the type of editor. The integer editor's SetValueL() requires a TInt passed by value, the floating-point editor requires a pointer to a treal , and the fixed-point editor requires a pointer to a TInt . Passing in NULL clears a fixed- or floating-point editor.