Flex SDK Wiki

# Spark TrackBase - Functional and Design Specification ---- \\ ## Summary and Background ---- The **TrackBase** class subclasses [Range](Spark%20Range) and introduces the concepts of a thumb and a track for the thumb to move along. TrackBase also provides simple thumb dragging functionality for classes such as [SliderBase](Spark%20Slider) and [ScrollBarBase](Spark%20ScrollBar), both of which subclass TrackBase. ## Usage Scenarios ---- * [SliderBase](Spark%20Slider) subclasses TrackBase. * [ScrollBarBase](Spark%20ScrollBar) subclasses TrackBase. ## Detailed Description ---- ##### SkinParts TrackBase consists of 2 SkinParts. * The **track** SkinPart is the button on which the thumb is positioned on. It represents the entire range of possible values. * The **thumb** SkinPart is a button which moves through the range of positions along the track based on the current value. ##### Inherited Properties (from [Range](Spark%20Range)) `value, minimum, maximum, snapInterval, stepSize` - See [Range](Spark%20Range%23Properties). ##### Behavior and Methods `pointToValue()` - Takes a point relative to the track and converts it to a valid value. This method must be overridden by a subclass. `updateSkinDisplayList()` - Used primarily to set the bounds and position of the thumb. It may be used to update other parts of the skin if necessary. `system_mouseWheelHandler()` - Handles mouse wheel events. `thumb_mouseDownHandler(), system_mouseMoveHandler(), system_mouseUpHandler()` - These methods handle different stages of dragging the thumb. `track_mouseDownHandler()` - Handles the user clicking on the track. ##### Events "valueCommit" - Whenever the value changes, a "valueCommit" event is dispatched (inherited from Range). "change" - Whenever the value changes because of user interaction such as dragging the thumb or clicking on the track, a "change" event is dispatched. "changeStart" - Dispatched at the start of a user interaction or when an animation begins. "changeEnd" - Dispatched at the end of a user interaction or when an animation ends. "thumbPress" - User presses a thumb. "thumbDrag" - User drags the thumb while it is still pressed. "thumbRelease" - User releases the thumb after it has been pressed. ## API Description ---- package spark.components.supportClasses { /** * Dispatched when the value of the control changes * as a result of user interaction. * * @eventType flash.events.Event.CHANGE */ Event(name="change", type="flash.events.Event") /** * Dispatched at the end of a user interaction * or when an animation ends. * * @eventType mx.events.FlexEvent.CHANGE_END */ Event(name="changeEnd", type="mx.events.FlexEvent") /** * Dispatched at the start of a user interaction * or when an animation starts. * * @eventType mx.events.FlexEvent.CHANGE_START */ Event(name="changeStart", type="mx.events.FlexEvent") /** * Dispatched when the thumb is pressed and then moved by the mouse. * This event is always preceded by a thumbPress event. * * @eventType spark.events.TrackBaseEvent.THUMB_DRAG */ Event(name="thumbDrag", type="spark.events.TrackBaseEvent") /** * Dispatched when the thumb is pressed, meaning * the user presses the mouse button over the thumb. * * @eventType spark.events.TrackBaseEvent.THUMB_PRESS */ Event(name="thumbPress", type="spark.events.TrackBaseEvent") /** * Dispatched when the thumb is released, * meaning the user releases the mouse button after * a thumbPress event. * * @eventType spark.events.TrackBaseEvent.THUMB_RELEASE */ Event(name="thumbRelease", type="spark.events.TrackBaseEvent") /** * Normal State */ SkinState("normal") /** * Disabled State */ SkinState("disabled") /** * Duration in milliseconds for a sliding animation * when you click on the track to move a thumb. This style is * used for both Sliders and Scrollbars. For Sliders, any click * on the track will cause an animation using this style, as the thumb * will move to the clicked position. For ScrollBars, this style is * used only when shift-clicking on the track, which causes the thumb * to move to the clicked position. Clicking on a ScrollBar track when * the shift key is not pressed will result in paging behavior instead. * The smoothScrolling style must also be set on the * ScrollBar to get animated behavior when shift-clicking. * *

This duration is for an animation that covers the entire distance of the * track; smaller distances will use a proportionally smaller duration.

* * @default 300 */ Style(name="slideDuration", type="Number", format="Time", inherit="no") /** * The TrackBase class is a base class for components with a track * and one or more thumb buttons, such as Slider and ScrollBar. It * declares two required skin parts: thumb and * track. * The TrackBase class also provides the code for * dragging the thumb button, which is shared by the Slider and ScrollBar classes. * * * @see spark.components.supportClasses.Slider * @see spark.components.supportClasses.ScrollBar */ public class TrackBase extends Range { include "../core/Version.as"; //-------------------------------------------------------------------------- // // Constructor // //-------------------------------------------------------------------------- /** * Constructor. */ public function TrackBase():void; //-------------------------------------------------------------------------- // // Skins // //-------------------------------------------------------------------------- SkinPart(required="false") /** * A skin part that defines a button * that can be dragged along the track to increase or * decrease the value property. * Updates to the value property * automatically update the position of the thumb button * with respect to the track. */ public var thumb:Button; SkinPart(required="false") /** * A skin part that defines a button * that, when pressed, sets the value property * to the value corresponding with the current button position on the track. */ public var track:Button; //-------------------------------------------------------------------------- // // Methods // //-------------------------------------------------------------------------- /** * Converts a track-relative x,y pixel location into a value between * the minimum and maximum, inclusive. * *

TrackBase subclasses must override this method and perform conversions * that take their own geometry into account. * * For example, a vertical slider might compute a value like this: *

         *  return (y / track.height) * (maximum - minimum);
         *  

*

* *

By default, this method returns minimum.

* * @param x The x coordinate of the location relative to the track's origin. * @param y The y coordinate of the location relative to the track's origin. * @return A value between the minimum and maximum, inclusive. */ protected function pointToValue(x:Number, y:Number):Number; //-------------------------------------------------------------------------- // // Event Handlers // //-------------------------------------------------------------------------- /** * Sets the bounds of skin parts, typically the thumb, whose geometry isn't fully * specified by the skin's layout. * *

Most subclasses override this method to update the thumb's size, position, and * visibility, based on the minimum, maximum, and value properties.

* *

By default, this method does nothing.

* */ protected function updateSkinDisplayList():void; /** * Handles the mouseWheel event when the component is in focus. The thumb is * moved by the amount of the mouse event delta multiplied by the stepSize. */ protected function system_mouseWheelHandler(event:MouseEvent):void; //--------------------------------- // Thumb dragging handlers //--------------------------------- /** * Handle mouse-down events on the scroll thumb. Records * the mouse down point in clickOffset. */ protected function thumb_mouseDownHandler(event:MouseEvent):void; /** * Capture mouse-move events anywhere on or off the stage. * First, we calculate the new value based on the new position * using calculateNewValue(). Then, we move the thumb to * the new value's position. Last, we set the value and * dispatch a "change" event if the value changes. */ protected function system_mouseMoveHandler(event:MouseEvent):void; /** * Handle mouse-up events anywhere on or off the stage. */ protected function system_mouseUpHandler(event:MouseEvent):void; //--------------------------------- // Track down handlers //--------------------------------- /** * Handle mouse-down events for the scroll track. Subclasses * should override this method if they want the track to * recognize mouse clicks on the track. */ protected function track_mouseDownHandler(event:MouseEvent):void; } } ## B Features ---- ## Additional Implementation Details ---- none ## Prototype Work ---- ## 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. ----