Flex SDK Wiki

# Spark Spinner - Functional and Design Specification ---- \\ ## Glossary ---- **scale** - See [Range](Spark%20Range%23Glossary) **value wrapping** - When the current value is at the maximum, stepping to the next value will set the current value to the minimum and vice versa. ## Summary and Background ---- This specification describes the proposed new **Spinner** class which extends [Range](Spark%20Range) in Gumbo. Spinner extends from [Range](Spark%20Range) and adds two buttons as skin parts that allow someone to step the current value through its scale. [NumericStepper](Spark%20NumericStepper) will extend from Spinner. The primary motivations for adding this new class were: 1. To allow more generic display components and more complex behavior than the Halo NumericStepper allowed. 2. To have NumericStepper adhere to accessibility standards. By having the Spinner class, developers can be more flexible with the types of displays allowed. One can imagine having a Spinner controlling tabs or a menu by assigning different values to tabs or menu items. Also, NumericStepper was the only basic component that did not support accessibility. Spinner remedies this problem by allowing [NumericStepper](Spark%20NumericStepper) to be a spinner with the additional element of a [TextInput](Gumbo%20FxTextInput). ## Usage Scenarios * Base class for some Gumbo controls such as [NumericStepper](Spark%20NumericStepper). * Base class or separate part for custom controls that utilize selection from an ordered set. Use cases include: 1. Modified [NumericStepper](Spark%20NumericStepper) with different input/display 2. Tabbing control (assign tabs to values) 3. Mobile menu (assign menu items to values) ## Detailed Description ---- ##### Behavior Spinner controls a value through its two buttons, `incrementButton` and `decrementButton`. These buttons use `stepSize` to increment or decrement the values. ##### SkinParts Spinner is composed of two skin parts that are buttons: 1. **incrementButton** increases the value by `stepSize`, if possible, when pressed. 2. **decrementButton** decreases the value by `stepSize`, if possible, when pressed. ##### Inherited Properties `value, minimum, maximum, snapInterval, stepSize` - See [Range](Spark%20Range). * Note: Correct behavior is only implemented for stepSize >= 0. ##### New Properties `allowValueWrap` - enables or disables [value wrapping](%23Glossary). The default is false. ##### Methods `incrementButton_buttonDownHandler(), decrementButton_buttonDownHandler()` - These protected methods handle the behavior of each button. `system_mouseWheelHandler()` - Handles mouse wheel events. ##### Events Whenever the value changes, a `valueCommit` event is dispatched (inherited from [Range](Spark%20Range)). Whenever the value changes because of user interaction, a `change` event is dispatched. ##### Keyboard Behavior * Up increments the value * Down decrements the value. \\ ## API Description ---- package spark.components { //-------------------------------------- // Styles //-------------------------------------- /** * The radius of the corners of this component. * * @default 2 */ Style(name="cornerRadius", type="Number", format="Length", inherit="no", theme="spark", minValue="0.0") /** * The alpha of the focus ring for this component. * * @default 0.5 */ Style(name="focusAlpha", type="Number", inherit="no", theme="spark", minValue="0.0", maxValue="1.0") /** * @copy spark.components.supportClasses.GroupBase#style:focusColor * * @default 0x70B2EE */ Style(name="focusColor", type="uint", format="Color", inherit="yes", theme="spark") /** * @copy spark.components.supportClasses.GroupBase#style:symbolColor * * @default 0x000000 */ Style(name="symbolColor", type="uint", format="Color", inherit="yes", theme="spark") //-------------------------------------- // Events //-------------------------------------- /** * Dispatched when the value of the Spinner control changes * as a result of user interaction. * * @eventType flash.events.Event.CHANGE */ Event(name="change", type="flash.events.Event") //-------------------------------------- // Skin states //-------------------------------------- /** * Normal State */ SkinState("normal") /** * Disabled State */ SkinState("disabled") /** * A Spinner component selects a value from an * ordered set. It uses two buttons that increase or * decrease the current value based on the current * value of the stepSize property. * *

A Spinner consists of two required buttons, * one to increase the current value and one to decrease the * current value. Users can also use the Up Arrow and Down Arrow keys * and the mouse wheel to cycle through the values. * An input value is committed when the user presses the Enter key, * removes focus from the component, or steps the Spinner * by pressing an arrow button or by calling the * changeValueByStep() method.

* *

The scale of an Spinner component is the set of * allowed values for the value property. * The allowed values are the sum of the minimum with * integer multiples of the snapInterval property * which are less than or equal to the maximumvalue. * For example:

* *

*
• minimum = -1
*
• maximum = 10
*
• snapInterval = 3
*

* * Therefore the scale is {-1,2,5,8,10}. * * @see spark.components.NumericStepper * @see spark.skins.spark.SpinnerSkin */ public class Spinner extends Range implements IFocusManagerComponent { include "../core/Version.as"; //-------------------------------------------------------------------------- // // Constructor // //-------------------------------------------------------------------------- /** * Constructor. */ public function Spinner():void; //-------------------------------------------------------------------------- // // SkinParts // //-------------------------------------------------------------------------- //---------------------------------- // decrementButton //---------------------------------- SkinPart(required="false") /** * A skin part that defines the button that, * when pressed, decrements the value property * by stepSize. */ public var decrementButton:Button; //---------------------------------- // incrementButton //---------------------------------- SkinPart(required="false") /** * A skin part that defines the button that, * when pressed, increments the value property * by stepSize. */ public var incrementButton:Button; //-------------------------------------------------------------------------- // // Properties // //-------------------------------------------------------------------------- //---------------------------------- // valueWrap //---------------------------------- /** * Determines the behavior of the control for a step when the current * value is either the maximum * or minimum value. * If allowValueWrap is true, then the * value property wraps from the maximum * to the minimum value, or from * the minimum to the maximum value. * * @default false */ public function get allowValueWrap():Boolean; public function set allowValueWrap(value:Boolean):void; //-------------------------------------------------------------------------- // // Event handlers // //-------------------------------------------------------------------------- /** * Handle a click on the incrementButton. This should * increment value by stepSize. */ protected function incrementButton_buttonDownHandler(event:Event):void; /** * Handle a click on the decrementButton. This should * decrement value by stepSize. */ protected function decrementButton_buttonDownHandler(event:Event):void; /** * Handles the mouseWheel event * when the component is in focus. * The spinner is moved by the amount of the mouse event delta * multiplied by the stepSize. */ protected function system_mouseWheelHandler(event:MouseEvent):void; } } ## B Features ---- none so far ## Additional Implementation Details ---- none ## Prototype Work ---- Prototype of Spinner has shown that it can be a very lightweight base class for [NumericStepper](Spark%20NumericStepper) and other custom controls. ## Compiler Work ---- none ## Web Tier Compiler Impact ---- none ## Flex Feature Dependencies ---- Spinner depends on [Range](Spark%20Range) as its base class. ## Backwards Compatibility ---- ### Syntax changes None - New Class ## Accessibility ---- Provides accessibility for NumericStepper and similar controls. ## Issues and Recommendations ---- 1. Should there be more descriptive events? For distinguishing between keyboard and mouse? ----