Spark NumericStepper - Functional and Design Specification


Summary and Background

NumericStepper is a Spinner that has a TextInput companion. It extends Spinner and adds a TextInput as a required SkinPart.

The numeric behavior of NumericStepper is exactly the same as Spinner. The scale is the same. The only additional behavior is that users may use the TextInput to edit the value.

Usage Scenarios

Allow users to specify a quantity either through the editable text field or to step the value via the arrow buttons.

Detailed Description

Behavior

See Spinner for detailed description of NumericStepper's behavior in terms of scale.

SkinParts

See Spinner for button SkinParts.

  • textInput - A TextInput that the user can use to change the value of the NumericStepper. Changes done through pressing the buttons and programmatically are also reflected by the TextInput.
Editing the Text Field

NumericStepper specifies an editable text field as a SkinPart called textInput. If textInput is edited, the new value is committed once the user performs an action that does not edit the text. These actions include:

  • Pressing the Enter key
  • Focusing out of the NumericStepper
  • Stepping either through the buttons or programmatically (calling step()).

The value of textInput is committed and then stepped regardless of whether step() is called programmatically or through user interaction.

Events

Whenever the value changes, a "valueCommit" event is dispatched (inherited from Range).
Whenever the value changes because of user interaction, a "change" event is dispatched.

Keyboard Behavior

vSpinner's keyboard controls still apply (except for Left and Right since they navigate the TextInput), but now, the text field can be edited. The value of the text field is committed whenever the user hits enter, focuses out of the NumericStepper using tab, or presses either of the buttons through up or down.

Focus

textInput always has focus when NumericStepper is in focus.

Not yet implemented features

-maxChars property

API Description

package spark.components
{

import flash.display.DisplayObject;
import flash.events.Event;

import mx.events.FlexEvent;
import mx.managers.IFocusManagerComponent;

/**
 *  The NumericStepper control lets the user select
 *  a number from an ordered set.
 *  The NumericStepper control consists of a single-line
 *  input text field and a pair of arrow buttons
 *  for stepping through the possible values.
 *  The Up Arrow and Down Arrow keys also cycle through 
 *  the values. An inputted value is committed whenever
 *  the user presses enter, focuses out of the
 *  NumericStepper, or steps the NumericStepper.
 * 
 *  @see spark.components.Spinner
 */
public class NumericStepper extends Spinner implements IFocusManagerComponent
{
    include "../core/Version.as";
    
    //--------------------------------------------------------------------------
    //
    //  Constructor
    //
    //--------------------------------------------------------------------------
    
    /**
     *  Constructor
     */  
    public function NumericStepper();
    
    //--------------------------------------------------------------------------
    //
    // SkinParts
    //
    //--------------------------------------------------------------------------

    [SkinPart]
    
    /**
     *  <code>textInput</code> is a SkinPart that defines a
     *  TextInput which allows a user to edit the value of
     *  the NumericStepper. The value is rounded and committed
     *  when the user presses enter, focuses out of
     *  the NumericStepper, or steps the NumericStepper.
     */
    public var textInput:TextInput;

    //--------------------------------------------------------------------------
    //
    // Methods
    //
    //--------------------------------------------------------------------------

    /**
     *  @private
     */
    override protected function partAdded(partName:String, instance:*):void;
    
    /**
     *  @private
     */
    override protected function partRemoved(partName:String, instance:*):void;

    /**
     *  @private
     */
    override protected function enableSkinParts(value:Boolean):void;

    /**
     *  @private
     */
    override public function setFocus():void;
    
    /**
     *  @private
     */
    override protected function isOurFocus(target:DisplayObject):Boolean;

    /**
     *  @private
     *  Calls commitTextInput() before stepping.
     */
    override public function step(increase:Boolean = true):void;
    
    /**
     *  Commits the current text of <code>textInput</code> as
     *  <code>value</code> after rounding the new value using
     *  <code>nearestValidValue</code>.
     */
    protected function commitTextInput():void;

    //--------------------------------------------------------------------------
    // 
    // Event Handlers
    //
    //--------------------------------------------------------------------------
    
    //--------------------------------- 
    // Keyboard handlers
    //---------------------------------
    
    /**
     *  When the enter key is pressed, NumericStepper commits the
     *  text currently displayed.
     */
    protected function textInput_enterHandler(event:Event):void;
}

}

B Features

QA

Yes

You must be logged in to comment.

1 Comment