uiStepperInput

uiStepperInput

The uiStepperInput is used to display single line editable numeric values that can also be adjusted using stepper buttons placed inside the control.

Using uiStepperInput

ActionScript 3.0 Example

import com.ghostwire.ui.containers.uiBox;
import com.ghostwire.ui.controls.uiText;
import com.ghostwire.ui.controls.uiStepperInput;
import com.ghostwire.ui.data.uiRange;
import com.ghostwire.ui.enums.ALIGN;
 
import flash.events.Event;
 
// ** text label **
var txt:uiText = new uiText("Cargo Load:");
txt.alignY = ALIGN.CENTER;
 
// ** create a range with value 12, minimum 0, maximum 99 **
var range:uiRange = new uiRange(12,0,99);
range.addEventListener(Event.CHANGE,on_rangeChange);
 
// ** stepperinput using range **
var kgInput:uiStepperInput    = new uiStepperInput(range);
 
var suffix:uiText = new uiText("KG");
suffix.alignY = ALIGN.CENTER;
 
var box:uiBox = new uiBox();
box.addChild(txt);
box.addChild(kgInput);
box.addChild(suffix);
 
addChild(box);
 
function on_rangeChange(evt:Event):void
{
    trace(uiRange(evt.target).value);
}

The values represented by a uiStepperInput is defined by a com.ghostwire.ui.data.uiRange object, which must be declared in the constructor of the uiStepperInput. This uiRange object contains the values for the current value, minimum and maximum values, as well as the step and page sizes.

var sizeInput:uiStepperInput = new uiStepperInput(new uiRange(10,0,100)); // ** current value 10, minimum 0, maximum 100 **

To be notified of changes to the current value, listen for the Event.CHANGE event that will be dispatched by the uiRange object when the value is adjusted:

sizeInput.range.addEventListener(Event.CHANGE,on_rangeChange);
function on_rangeChange(evt:Event):void
{
    trace(uiRange(evt.target).value);
}

To adjust the minimum and maximum values, use the resize(minimum, maximum) method of the uiRange object:

sizeInput.range.resize(20,50); // ** adjust minimum to 20, maximum to 50 **

To be notified of changes to the minimum and/or maximum values, listen for the Event.RESIZE event that will be dispatched by the uiRange object when the range has been adjusted (resized using the resize() method):

sizeInput.range.addEventListener(Event.RESIZE,on_rangeResize);
function on_rangeResize(evt:Event):void
{
    trace(uiRange(evt.target).minimum);
    trace(uiRange(evt.target).maximum);
}

The step value determines one unit of each increment/decrement.

The page value determines the amount to increment/decrement when the Page Up and Page Down key is hit, respectively. This value must be higher than the step value, otherwise pressing the Page Up/Page Down keys has no effect.

Size

The default desired size of a uiStepperInput instance depends on the expected space that will be used for the text and the stepper buttons. The size of the text will of course be affected by the text style used, ie the font face and font size affects this default size. The minimum and maximum values set for the range, as well as the digits property, also affects the width of the text.

If unconstrained, the control will request for space and resize itself automatically to fit the widest expected text. For example, if maximum is 1000, the control will attempt to resize itself to fit 4 characters. If additionally, digits property is set to 2 (decimal points), then the control will attempt to resize to fit 7 characters.

var kgInput:uiStepperInput    = new uiStepperInput(new uiRange(500,0,1000));
kgInput.digits = 2;

User Interaction

While a uiStepperInput instance has focus, the user can type inside the text field (if editable property is true), or use the following keys to interact with the control:

Key	Action
Down Arrow	Value decrements by `range.step`.
End	Value is set to `range.maximum` value.
Home	Value is set to `range.minimum` value.
Page Down	Value decrements by `range.page` (only if `range.page` is bigger than `range.step`).
Page Up	Value increments by `range.page` (only if `range.page` is bigger than `range.step`).
Shift+Tab	Moves focus to previous UI control in the tab focus chain.
Tab	Moves focus to next UI control in the tab focus chain.
Up Arrow	Value increments by `range.step`.

NOTE: Using the stepper buttons to change the value does not focus the control. The user must click on the text field or use the Tab key to move focus to the control.

API Reference

For more information on the members of the com.ghostwire.ui.controls.uiStepperInput class, please refer to the API Reference.