Using IlvNumberField

The class IlvNumberField class defines a specialized text field for editing numbers with various formats. IlvNumberField is a subclass of IlvTextField.

A Number Field

See Using IlvTextField.

This section covers the following topics:

Selecting an Editing Mode

The IlvNumberField class has two main editing modes, one for integers (IlvInt) and one for floating-point numbers (IlDouble). The editing mode in effect depends on the constructor used.

To create a number field for editing integers, use one of these two constructors:

IlvNumberField* field = new IlvNumberField(display,0,

IlvRect(10,10, 100, 30));

IlvNumberField* field = new IlvNumberField(display,

IlvPoint(10,10), 0);

To create a number field for editing floating point numbers, use one of these two constructors:

IlvNumberField* field = new IlvNumberField(display, 0.0,

IlvRect(10,10, 100, 30));

IlvNumberField* field = new IlvNumberField(display,

IlvPoint(10,10), 0.0);

Choosing a Format

A number field can be assigned a format. You can change the current format at runtime with setFormat.

Formats are defined by this enum declaration:

enum { thousands = 1,

scientific = 2,

padright = 4,

showpoint = 8,

floatmode = 16};

They are set as follows:

obj->setFormat(IlvNumberField::floatmode|IlvNumberField::scientific);

Following is a description of these various date formats:

  • floatmode—Use this mode to edit float values. This mode is automatically set when using a constructor with a value of type IlDouble. See Selecting an Editing Mode.

  • scientific—Use this mode to control the output of IlDouble values in the gadget. If scientific is set, the value is converted using scientific notation, where there is one digit before the decimal point and the number of digits after it is equal to the specified number (six by default). The letter e introduces the exponent. If scientific is not set, the value is converted to decimal notation with precision digits after the decimal point (six digits by default). This only works when the floatmode is set.

  • padright—Use this mode to add the trailing zeros after the decimal point. This only works when the floatmode is set.

  • showpoint—Use this mode with the padright mode to keep the decimal point when removing trailing zeros. This only works when the floatmode is set.

  • thousands—Use this mode to display a “thousand” separator. The default “thousand” separator is the character ‘,’. See Specifying the Thousand Separator.

Defining a Range of Values

You can specify the minimum and maximum numbers that can be edited in a number field. There are two sets of member functions depending on whether you are editing an integer or a floating-point value:

For integers, use setMaxInt and setMinInt.

For floating-point numbers, use setMaxFloat and setMinFloat.

Setting and Retrieving a Value

The IlvNumberField provides two sets of member functions for setting and retrieving a value.

If the value is an integer, use:

IlInt getIntValue(IlBoolean& error) const;

IlBoolean setValue(IlInt, IlBoolean redraw = IlFalse);

If the value is a floating-point number:

IlDouble getFloatValue(IlBoolean& error) const;

IlBoolean setValue(IlDouble, IlBoolean redraw = IlFalse);

Specifying the Thousand Separator

When the number formats thousands and float are set, the thousand separator is displayed. The default thousand separator is the comma character (,). You can change this character using the member function setThousandSeparator. Calling this member functions does not directly change the text in the number field. Therefore, if the field already contains a value, you must first retrieve that value, change the separator, and then set the value again.

Specifying the Decimal Point Character

The default decimal point character for floating-point numbers is the period character (.). You can change this character using the member function setDecimalPointChar.

Calling this member function does not directly change the text in the number field. Therefore, if the field already contains a value, you must first retrieve that value, change the decimal point character, and then set the value again.

Event Handling and Callbacks

When the user presses the Enter Key in a number field, the IlvNumberField::validate member function is called. This virtual member function invokes the Main callback associated with the number field and moves the keyboard focus to the next gadget in the focus chain. This happens only if the field content can be converted to a number, and this number is within the range specified by setMaxFloat, setMinFloat, setMaxInt, and setMinInt.

See Defining a Range of Values, Focus Management, and Associating a Callback with a Gadget.