How to use the Feathers NumericStepper
component
The NumericStepper
component displays a numeric value between a minimum and maximum. The value may be changed by pressing the increment or decrement buttons. If editing is enabled (typically not enabled on mobile), the value may be changed by typing a value into a text input.
The Basics
First, let's create a NumericStepper
control, set up its range of values, and add it to the display list.
var stepper:NumericStepper = new NumericStepper();
stepper.minimum = 0;
stepper.maximum = 100;
stepper.value = 50;
this.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
, as we do above, the stepper will increment on whole numbers only, and it cannot have a value like 4.5
, for instance.
Add a listener to the Event.CHANGE
event to know 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:NumericStepper = NumericStepper( event.currentTarget );
trace( "stepper.value changed:", stepper.value);
}
Skinning a NumericStepper
The skins for a NumericStepper
control are divided into three parts. There are the increment and decrement buttons and the text input. There are a few different layout modes that control where the buttons are placed relative to the text input. For full details about what skin and style properties are available, see the NumericStepper
API reference. We'll look at a few of the most common properties below.
Layout Modes
The numeric stepper's layout can be customized to place the buttons in different locations. In the example below, we place the buttons on the right side of the text input, stacked vertically, like you see with many desktop numeric steppers using NumericStepper.BUTTON_LAYOUT_MODE_RIGHT_SIDE_VERTICAL
:
stepper.buttonLayoutMode = NumericStepper.BUTTON_LAYOUT_MODE_RIGHT_SIDE_VERTICAL;
There are two additional options for buttonLayoutMode
. You can use NumericStepper.BUTTON_LAYOUT_MODE_SPLIT_HORIZONTAL
to place the decrement button on the left side of the text input and the increment button button on the right side. Similarly, you can use NumericStepper.BUTTON_LAYOUT_MODE_SPLIT_VERTICAL
to place the increment button on top of the text input and the decrement button on the bottom.
Targeting a NumericStepper
in a theme
If you are creating a theme, you can specify a function for the default styles like this:
getStyleProviderForClass( NumericStepper ).defaultStyleFunction = setNumericStepperStyles;
If you want to customize a specific numeric stepper to look different than the default, you may use a custom style name to call a different function:
stepper.styleNameList.add( "custom-numeric-stepper" );
You can specify the function for the custom style name like this:
getStyleProviderForClass( NumericStepper )
.setFunctionForStyleName( "custom-numeric-stepper", setCustomNumericStepperStyles );
Trying to change the numeric stepper's styles and skins outside of the theme may result in the theme overriding the properties, if you set them before the numeric stepper was added to the stage and initialized. Learn to extend an existing theme to add custom skins.
If you aren't using a theme, then you may set any of the numeric stepper's properties directly.
Skinning the Decrement Button
This section only explains how to access the decrement button sub-component. Please read How to use the Feathers Button
component for full details about the skinning properties that are available on Button
components.
With a Theme
If you're creating a theme, you can target the NumericStepper.DEFAULT_CHILD_STYLE_NAME_DECREMENT_BUTTON
style name.
getStyleProviderForClass( Button )
.setFunctionForStyleName( NumericStepper.DEFAULT_CHILD_STYLE_NAME_DECREMENT_BUTTON, setNumericStepperDecrementButtonStyles );
You can override the default style name to use a different one in your theme, if you prefer:
stepper.customDecrementButtonStyleName = "custom-decrement-button";
You can set the function for the customDecrementButtonStyleName
like this:
getStyleProviderForClass( Button )
.setFunctionForStyleName( "custom-decrement-button", setNumericStepperCustomDecrementButtonStyles );
Without a Theme
If you are not using a theme, you can use decrementButtonFactory
to provide skins for the numeric stepper's decrement button:
stepper.decrementButtonFactory = function():Button
{
var button:Button = new Button();
//skin the decrement button here
button.defaultSkin = new Image( upTexture );
button.downSkin = new Image( downTexture );
return button;
}
Alternatively, or in addition to the decrementButtonFactory
, you may use the decrementButtonProperties
to pass skins to the decrement button.
stepper.decrementButtonProperties.defaultSkin = new Image( upTexture );
stepper.decrementButtonProperties.downSkin = new Image( downTexture );
In general, you should only skins to the numeric stepper's decrement button through decrementButtonProperties
if you need to change skins after the decrement button is created. Using decrementButtonFactory
will provide slightly better performance, and your development environment will be able to provide code hinting thanks to stronger typing.
Skinning the Increment Button
This section only explains how to access the increment button sub-component. Please read How to use the Feathers Button
component for full details about the skinning properties that are available on Button
components.
The numeric stepper's increment button may be skinned similarly to the decrement button. The style name to use with themes is NumericStepper.DEFAULT_CHILD_STYLE_NAME_INCREMENT_BUTTON
or you can customize the style name with customIncrementButtonStyleName
. If you aren't using a theme, then you can use incrementButtonFactory
and incrementButtonProperties
.
If your decrement button and increment buttons don't have icons, you can use decrementButtonLabel
and incrementButtonLabel
to set the button labels:
stepper.decrementButtonLabel = "-";
stepper.incrementButtonLabel = "+";
Skinning the Text Input
This section only explains how to access the text input sub-component. Please read How to use the Feathers TextInput
component for full details about the skinning properties that are available on TextInput
components.
With a Theme
If you're creating a theme, you can target the NumericStepper.DEFAULT_CHILD_STYLE_NAME_TEXT_INPUT
style name.
getStyleProviderForClass( TextInput )
.setFunctionForStyleName( NumericStepper.DEFAULT_CHILD_STYLE_NAME_TEXT_INPUT, setNumericStepperTextInputStyles );
You can override the default style name to use a different one in your theme, if you prefer:
stepper.customTextInputStyleName = "custom-text-input";
You can set the function for the customTextInputStyleName
like this:
getStyleProviderForClass( TextInput )
.setFunctionForStyleName( "custom-text-input", setNumericStepperCustomTextInputStyles );
Without a Theme
If you are not using a theme, you can use textInputFactory
provide skins for the numeric stepper's text input:
stepper.textInputFactory = function():TextInput
{
var input:TextInput = new TextInput();
//skin the text input here
input.backgroundSkin = new Scale9Image( backgroundTextures );
input.padding = 20;
return input;
}
Alternatively, or in addition to the textInputFactory
, you may use the textInputProperties
to pass skins to the text input.
stepper.textInputProperties.backgroundSkin = new Scale9Image( backgroundTextures );
stepper.textInputProperties.padding = 20;
In general, you should only skins to the numeric stepper's text input through textInputProperties
if you need to change skins after the text input is created. Using textInputFactory
will provide slightly better performance, and your development environment will be able to provide code hinting thanks to stronger typing.