How to use the NumericStepper component

The NumericStepper component allow a user to select a numeric value in a specific range. The value may be changed by pressing the increment or decrement buttons, or by typing a value into a text input.

Live preview of the NumericStepper component

The Basics

First, let's create a NumericStepper control, set up its range of values, and add it to the the display list.

var stepper = new NumericStepper();
stepper.minimum = 0.0;
stepper.maximum = 100.0;
stepper.value = 50.0;
addChild(stepper);

The value property indicates the current value of the stepper, while the minimum and maximum properties establish a range of possible values. We can further control the stepper's behavior with the step property:

stepper.step = 1;

The step property controls how the numeric stepper's value is rounded as the user interacts with it. If we set the stepper's step to 1.0, as we do above, the stepper will increment on whole numbers only, and it cannot have a value like 4.5, for instance.

Add an event listener for Event.CHANGE to perform an action when the value property changes:

stepper.addEventListener(Event.CHANGE, stepper_changeHandler);

The listener might look something like this:

function stepper_changeHandler(event:Event):Void {
    var stepper = cast(event.currentTarget, NumericStepper);
    trace("stepper.value change: " + stepper.value);
}

Styles

A number of styles may be customized on the sub-components of a NumericStepper component, including styles on the decrement and increment buttons and the text input.

Layout

A couple of styles are available for customizing the position of the decrement and increment buttons, relative to the text input.

To see a live demonstration of button layouts with NumericStepper, open the numeric-stepper-button-layouts sample in your web browser. (Source Code)

Set the buttonDirection property to specify if the buttons should be positioned vertically or horizontally.

stepper.buttonDirection = VERTICAL;

Set the textInputPosition property to specify how the text input should be placed, relative to the buttons.

stepper.textInputPosition = LEFT;

Decrement and increment buttons

The decrement and increment buttons in a NumericStepper component are of type Button. Their appearance may be customized globally in a theme, or they may be customized outside of a theme on an specific, individual NumericStepper.

See How to use the Button component for complete details about which styles are available for the button.

Style the decrement and increment buttons globally

Use the NumericStepper.CHILD_VARIANT_DECREMENT_BUTTON and NumericStepper.CHILD_VARIANT_INCREMENT_BUTTON constants in a theme to provide a function that globally styles the buttons in all NumericStepper components.

styleProvider.setStyleFunction(
    Button,
    NumericStepper.CHILD_VARIANT_DECREMENT_BUTTON,
    setNumericStepper_DecrementButton_Styles);

styleProvider.setStyleFunction(
    Button,
    NumericStepper.CHILD_VARIANT_INCREMENT_BUTTON,
    setNumericStepper_IncrementButton_Styles);

The functions should use the following signature.

function setNumericStepper_DecrementButton_Styles(button:Button):Void {
    // ... set styles here
}

function setNumericStepper_IncrementButton_Styles(button:Button):Void {
    // ... set styles here
}

Style the decrement and increment buttons in a specific `NumericStepper`

The decrementButtonFactory and incrementButtonFactory properties may be used to customize the creation of an individual button.

stepper.decrementButtonFactory = () -> {
    var button = new Button();
    // ... set styles here
    return button;
};

stepper.incrementButtonFactory = () -> {
    var button = new Button();
    // ... set styles here
    return button;
};

TextInput

The text input in a NumericStepper component is of type TextInput. Its appearance may be customized globally in a theme, or it may be customized outside of a theme on an specific, individual NumericStepper.

See How to use the TextInput component for complete details about which styles are available for the text input.

Style text input globally

Use the NumericStepper.CHILD_VARIANT_TEXT_INPUT constant in a theme to provide a function that globally styles the text inputs in all NumericStepper components.

styleProvider.setStyleFunction(
    TextInput,
    NumericStepper.CHILD_VARIANT_TEXT_INPUT,
    setNumericStepper_TextInput_Styles);

The function should use the following signature.

function setNumericStepper_TextInput_Styles(textInput:TextInput):Void {
    // ... set styles here
}

Style the text input in a specific `NumericStepper`

The textInputFactory property may be used to customize the creation of an individual text input.

stepper.textInputFactory = () -> {
    var textInput = new TextInput();
    // ... set styles here
    return textInput;
};