Recipe 13.6. Adding a Form Control for Gathering Numeric Input

Problem

You want to add a form control to your application that allows the user to input a number.

Solution

Use a numeric stepper. Alternatively, you can also use a combo box, list, text input, or input text field.

Discussion

The NumericStepper component is specifically designed to allow the user to select from a sequential range of numeric values. Adding a numeric stepper is quite simple. You can drag an instance of the component from the Components panel to the stage. Then, as with most components, you should give the numeric stepper an instance name using the Property inspector. If the default settings work for your application, you don't need to do anything else. Otherwise, you should set the parameters for the instance using the Component Inspector panel or the Property inspector.

Numeric steppers have four parameters that you are most likely to configure. The minimum and maximum properties determine the range of possible values for the numeric stepper. The stepSize parameter determines what increment is used between each step. The value parameter allows you to specify the default value. For example, if you want to allow the user to specify a numeric value from 0 to 100 in increments of 5 then you should set minimum to 0, maximum to 100, and stepSize to 5. It should be noted that the possible values are calculated starting from 0 and not from the value specified by the value parameter. For example, you might think that you could configure a numeric stepper to allow only odd numbers by setting the value parameter to 1 and the stepSize to 2. However, even though the initial value will be 1, the subsequent values will be 2, 4, 6, and so on. And if you scroll back down, the numeric stepper will land on 0, not 1 (assuming the minimum value is still set to 0).

Although the numeric stepper is specifically designed to allow users to select from a range of numbers, you can also choose to use a combo box or list for the same purposes, but a slightly different display. A combo box and/or list also allow you to define specific numeric values that are not necessarily part of a pattern that would work within a numeric stepper. For example, you might want to allow the user to select from the values 1,000, 2,300, 2,401, and 8,200. In such a case, a combo box or list would be much better suited than a numeric stepper.

You can also choose to use a text input or an input text field to allow the user to input a number without having to select from a predefined set of values. In such a case, you should disallow the user from inputting nonnumeric characters. You can accomplish that by setting the restrict parameter for a text input or the restrict property for a dynamic text field. You can access the restrict parameter for a text input via the Component Inspector panel (the parameter is not accessible from the Property inspector). The parameter allows you to specify characters to allow and/or disallow. In the case of allowing numeric input, allow all the digits as well as the dot if you want to allow floating-point number entries (numbers with decimal places). For example, to allow a user to enter any floating-point number, you should specify the value of 1234567890. for the restrict parameter.

If you are using a dynamic text field, you must use ActionScript to access the restrict property. The restrict property for a text field allows you to specify the same types of values as the restrict parameter for a text input. The following code allows a user to input any floating-point number into a text field with an instance name of tNumericInput:

 tNumericInput.restrict = "1234567890.";