Multi-Field Numeric Editors

As their name suggests, multi-field numeric editors ( MFNE s) are used for entry of multiple numeric fields into a single editor. Note that the simplest MFNE, namely the number editor, actually contains only one field.

Characters appropriate to the type of editor separate the fields, for example, a dot (" . ") is used to separate fields in an IP (Internet Protocol) address editor, as shown in Figure 8-11.

Figure 8-11. An IP address editor.

As well as IP addresses, Series 60 provides MFNEs for editing single-integer numbers , ranges, times, dates and durations. Each editor has a minimum, maximum and a current value. The minimum and maximum values limit the range of values that the user can enter. Depending on the type of editor, this limit is applied either to each field or to the editor as a whole. For example, in an IP address editor, the minimum and maximum values determine the range of the values that could be entered into each field of the address, whereas in a date editor, the minimum and maximum values limit the range of dates that could be entered in the editor as a whole.

This section provides details of the available MFNEs and describes how to define a resource structure and instantiate one. It also explains how to get and set the value of an MFNE.

IP Address Editor

The IP address editor allows the user to enter IPv4 addresses in decimal format ”that is, four decimal numbers between 0 and 255, separated by a dot (" . "). An example of an IP address editor is shown in Figure 8-11.

Number Editor

The number editor is very similar to the integer editor, in that it can be used for editing integers. However, its behavior is more like that of a floating-point editor ”when values are out of range, they are set to the nearest valid value. Also, when the maximum value of the number editor is set to be greater than its minimum value, the editor will panic during its construction. An example of a number editor is shown in Figure 8-12.

Figure 8-12. A number editor.

Note that the integer editor derives from CEikEdwin , whereas the number editor derives from CEikMfne , and this provides them with different configuration options.

Range Editor

The range editor allows the user to enter two numbers representing a range. The second number must be greater than or equal to the first, and by default the numbers are separated by a dash (" - "). However, you can change the separator used in the editor's resource definition. An example of a range editor is shown in Figure 8-13.

Figure 8-13. A range editor.

Time Editor

The time editor has fields for hours, minutes and seconds, and you can use flags to determine which of these fields are displayed. It is available in either 12-hour or 24-hour format ”the default is 12- hour format. The locale settings are used to determine formatting, and which characters are used to separate the fields. An example of a time editor is shown in Figure 8-14.

Figure 8-14. A time editor shown in 12-hour format with no seconds field.

Date Editor

The date editor provides day, month and year fields. Again, the locale settings are used to determine formatting and the characters that are used to separate the fields. An example of a date editor is shown in Figure 8-15.

Figure 8-15. A date editor.

Time and Date Editor

The time and date editor has the properties of both the time and date editors. Yet again, the locale settings are used to determine formatting and the characters that are used to separate the fields. An example of a time and date editor is shown in Figure 8-16.

Figure 8-16. A time and date editor.

Duration Editor

The duration editor displays a length of time in hours, minutes and seconds. As with the time editor, you can use flags to determine which of these fields are shown. The locale settings are used to determine formatting and the characters that are used to separate the fields. An example duration editor is shown in Figure 8-17.

Figure 8-17. A duration editor.

Time Offset Editor

The time offset editor allows the user to edit a signed time offset in hours, minutes and seconds. The locale settings are used to determine formatting and the characters that are used to separate the fields. An example time offset editor is shown in Figure 8-18.

Figure 8-18. A time offset editor.

Using an MFNE

As with the secret editor, the code for MFNEs is quite simple. Therefore, a comprehensive example is not required. Instead, this section focuses on defining an MFNE in a resource, instantiating an MFNE and getting and setting an MFNE's value.

Defining an MFNE in a Resource

The type of resource you define depends on the MFNE that you are using. Table 8-14 shows which resource to use when instantiating an MFNE, and which control to use if using the MFNE as part of a dialog:

For example, you can define a number editor in a NUMBER_EDITOR resource:

 RESOURCE NUMBER_EDITOR my_number_editor    {    min = 0;    max = 200;    }

Each resource has a field representing the maximum and minimum values for the editor. The type and name of these will depend on the particular MFNE that you are using. As shown, the number editor has integer values for the " min " and " max " fields. Further information on these resource structures can be found in the file \epoc32\include\eikon.rh in the root directory of your SDK. The values of any flags used can be found in \epoc32\include\eikon.hrh , also in this directory ”their names all contain the string " Mfne ".

Instantiating an MFNE

You can instantiate the editor using any of the standard methods . For example, you can use the first-phase constructor of its class and then call ConstructFromResourceL() , or you can instantiate one as part of a dialog line ”in which case the dialog constructs and owns the editor.

Table 8-14 shows which class you should use when instantiating an MFNE.

Table 8-14. MFNE Editor Resources and Classes

MFNE Editor	Class	Resource	Control
Range	`CEikRangeEditor`	`RANGE_EDITOR`	`EEikCtRangeEditor`
Time	`CEikTimeEditor`	`TIME_EDITOR`	`EEikCtTimeEditor`
Date	`CEikDateEditor`	`DATE_EDITOR`	`EEikCtDateEditor`
Duration	`CEikDurationEditor`	`DURATION_EDITOR`	`EEikCtDurationEditor`
Time and Date	`CEikTimeAndDateEditor`	`TIME_AND_DATE_EDITOR`	`EEikCtTimeAndDateEditor`
IP Address	`CAknIpFieldEditor`	`IP_FIELD_EDITOR`	`EAknCtIpFieldEditor`
Number	`CEikNumberEditor`	`NUMBER_EDITOR`	`EEikCtNumberEditor`
Time Offset	`CEikTimeOffsetEditor`	`TIME_OFFSET_EDITOR`	`EEikCtTimeOffsetEditor`

Getting and Setting the Value of an MFNE

Once constructed , you can get and set the value of the editor using the API methods for the particular class of object that you are using ”these are typically functions of the form GetXXX() and SetXXX() . Refer to the class definitions in the header files \epoc32\include\eikmfne.h and \epoc32\include\aknipfed.h in the root directory of your SDK.

Also, it is possible to dynamically get and set the minimum and maximum values of an MFNE using the applicable class overloads of the methods SetMinimumAndMaximum() and GetMinimumAndMaximum() .