Flex SDK Wiki

# Spark Slider - Functional and Design Specification ---- \\ ## Summary and Background ---- The **SliderBase** class is the base class for Slider controls. It inherits from [TrackBase](Spark%20TrackBase), which contains code common to both Sliders and ScrollBars. SliderBase provides basic functionality for Slider controls such as liveDragging, keyboard handling, track click handling, animation, and dataTips. ## Usage Scenarios ---- * Basic one thumb sliders using the default ticks and labels. Developer only has to set a few properties and change the number of thumbs in the skin. * Two thumb sliders that select a range instead of a certain value. (B-Feature) * Custom sliders with special tracks. Developer subclasses the Slider base class and overrides a few methods. He also must use a custom skin to match the custom slider's behavior. For example, a circular slider or a wavy slider. * Multiple thumb sliders. (B-Feature) * Basic sliders with customized ticks and/or labels. ## Detailed Description ---- ##### SkinParts Slider consists of 2 SkinParts inherited from TrackBase * The [**track**](Spark%20TrackBase%23SkinParts) * The [**thumb**](Spark%20TrackBase%23SkinParts) As well as a new skin part: * The **dataTip** is a dynamic skin part and is of type IFactory which is expected to create instances of type `mx.core.IDataRenderer`. It is used to display a formatted version of the value. ##### Inherited Properties See [Range](Spark%20Range%23Properties). ##### New Properties * **liveDragging** - The default is false. When liveDragging is enabled, the thumb's value is committed as it is dragged along the track instead of when the thumb is released. * **pendingValue** - This protected property holds the temporary value of the slider during animation and user interaction. It is updated even if liveDragging is false. * **showDataTip, dataTipFormatFunction and dataTipPrecision** - These three properties are used to toggle and customize the dataTip. ##### Events See [Range](Spark%20Range%23Events) and [TrackBase](Spark%20TrackBase%23Events). ##### Track Behavior Clicking on the track should result in the thumb sliding to that position. The slide lasts for as long as the value of the style, `slideDuration`. If `slideDuration` is 0, then the thumb will snap to that position. ##### Keyboard Behavior When the thumb has focus: * Left/Down Arrow - decreases the value by stepSize. * Right/Up Arrow - increase the value by stepSize. * Home/End - Change the value to the lowest and highest possible values for the thumb that has focus. A future consideration is how to easily change the keyboard behavior in subclasses instead of assuming standard behavior based on the values. Consider the case of a reversed HSlider where the max is on the left instead of the right. ##### Methods `updateDataTip()` - Subclasses must override this function to position the dataTip. ##### Additional Items to be considered * Slider with more than one thumb - (B feature) * enableTrack property - enables/disables the track. (can enable/disable through skin) * tickInterval/tickValues - TBD * labels - TBD * data tips - Implemented ## API Description ---- package spark.components.supportClasses { //-------------------------------------- // Styles //-------------------------------------- include "../../styles/metadata/BasicInheritingTextStyles.as" /** * The alpha of the focus ring for this component. * * @default 0.55 */ Style(name="focusAlpha", type="Number", inherit="no", theme="spark", minValue="0.0", maxValue="1.0") /** * @copy spark.components.supportClasses.GroupBase#focusColor * * @default 0xFFFFFF */ Style(name="focusColor", type="uint", format="Color", inherit="yes", theme="spark") /** * When true, the thumb's value is * committed as it is dragged along the track instead * of when the thumb button is released. * * @default true */ Style(name="liveDragging", type="Boolean", inherit="no") /** * The SliderBase class lets users select a value by moving a slider thumb between * the end points of the slider track. * The current value of the slider is determined by the relative location of * the thumb between the end points of the slider, * corresponding to the slider's minimum and maximum values. * * The SliderBase class is a base class for HSlider and VSlider. * * @see spark.components.HSlider * @see spark.components.VSlider */ public class SliderBase extends TrackBase implements IFocusManagerComponent { include "../../core/Version.as"; //-------------------------------------------------------------------------- // // Constructor // //-------------------------------------------------------------------------- /** * Constructor. */ public function SliderBase():void; //-------------------------------------------------------------------------- // // Skin parts // //-------------------------------------------------------------------------- SkinPart(required="false", type="mx.core.IDataRenderer") /** * A skin part that defines a dataTip that displays a formatted version of * the current value. The dataTip appears while the thumb is being dragged. * This is a dynamic skin part and must be of type IFactory. */ public var dataTip:IFactory; //-------------------------------------------------------------------------- // // Properties // //-------------------------------------------------------------------------- //--------------------------------- // dataTipformatFunction //--------------------------------- /** * Callback function that formats the data tip text. * The function takes a single Number as an argument * and returns a formatted String. * *

The function has the following signature:

*

         *  funcName(value:Number):Object
         *  

* *

The following example prefixes the data tip text with a dollar sign and * formats the text using the dataTipPrecision * of a SliderBase Control named 'slide':

* *

         *  import mx.formatters.NumberBase;
         *  function myDataTipFormatter(value:Number):Object { 
         *      var dataFormatter:NumberBase = new NumberBase(".", ",", ".", ""); 
         *      return   "$ " + dataFormatter.formatPrecision(String(value), slide.dataTipPrecision); 
         *  }
         *  

* * @default undefined */ public function get dataTipFormatFunction():Function; public function set dataTipFormatFunction(value:Function):void; //--------------------------------- // dataTipPrecision //--------------------------------- /** * Number of decimal places to use for the data tip text. * A value of 0 means to round all values to an integer. * This value is ignored if dataTipFormatFunction is defined. * * @default 2 */ public var dataTipPrecision:int; //---------------------------------- // pendingValue //---------------------------------- /** * The value the slider will have when the mouse button is released. This property * also holds the temporary values set during an animation of the thumb if * the liveDragging style is true; the real value is only set * when the animation ends. * *

If the liveDragging style is false, then the slider's value is only set * when the mouse button is released. The value is not updated while the slider thumb is * being dragged.

* *

This property is updated when the slider thumb moves, even if * liveDragging is false.

* * @default 0 * @return The value implied by the thumb position. */ protected function get pendingValue():Number; protected function set pendingValue(value:Number):void; //--------------------------------- // showDataTip //--------------------------------- /** * If set to true, shows a data tip during user interaction * containing the current value of the slider. In addition, the skinPart, * dataTip, must be defined in the skin in order to * display a data tip. * @default true */ public var showDataTip:Boolean; //-------------------------------------------------------------------------- // // Methods // //-------------------------------------------------------------------------- /** * Used to position the data tip when it is visible. Subclasses must implement * this function. * * @param dataTipInstance The dataTip instance to update and position * @param initialPosition The initial position of the dataTip in the skin */ protected function updateDataTip(dataTipInstance:IDataRenderer, initialPosition:Point):void } } ## B Features ---- ## Additional Implementation Details ---- none ## Prototype Work ---- * Working prototype of HSlider, CircularSlider ## Compiler Work ---- none ## Web Tier Compiler Impact ---- none ## Flex Feature Dependencies ---- * Depends on Range. ## Backwards Compatibility ---- ### Syntax changes None - New Class ### Behavior None ### Warnings/Deprecation None ## Accessibility ---- Support Halo equivalent. ## Performance ---- none. ## Globalization ---- none ## Localization ---- ### Compiler Features none. ## QA ---- Yes. ----