Spark TrackBase - Functional and Design Specification

// Position and value conversions are done using a ratio of the logical track size
// and the size of the range.
position = (value - minimum) * ((trackSize - thumbSize) / (maximum - minimum))
value = minimum + position * ((maximum - minimum) / (trackSize - thumbSize))

package spark.components.supportClasses
{

import flash.events.Event;
import flash.events.MouseEvent;
import flash.geom.Point;

/**
 *  Dispatched when the value of the control changes
 *  as a result of user interaction.
 *
 *  @eventType mx.events.Event
 */
[Event(name="change", type="mx.events.Event")]

/**
 *  TrackBase is a base class for components with a track
 *  and one or more thumbs such as Slider and ScrollBar. It
 *  declares two required SkinParts, <code>thumb</code> and
 *  <code>track</code>. TrackBase also provides the code for
 *  thumb dragging which is shared by Slider and ScrollBar.
 * 
 *  @see spark.components.supportClasse.Range
 *  @see spark.components.supportClassesSlider
 *  @see spark.components.supportClassesScrollBar
 */
public class TrackBase extends Range
{
    include "../core/Version.as";

    //--------------------------------------------------------------------------
    //
    //  Constructor
    //
    //--------------------------------------------------------------------------

    /**
     *  Constructor. 
     */
    public function TrackBase():void;

    //--------------------------------------------------------------------------
    //
    // Skins
    //
    //--------------------------------------------------------------------------

    [SkinPart]
    
    /**
     *  <code>thumb</code> is a SkinPart that defines a button
     *  that can be dragged along the track to increase or
     *  decrease the slider's <code>value</code> property.
     *  Updates to the <code>value</code> through other means
     *  will automatically update the position of the thumb
     *  with respect to the track.
     */
    public var thumb:Button;
    
    [SkinPart]
    
    /**
     *  <code>track</code> is a SkinPart that defines a button
     *  that, when  pressed, will set the <code>value</code>
     *  to the value corresponding with that position.
     */
    public var track:Button;

    //--------------------------------------------------------------------------
    //
    //  Overridden properties: UIComponent, Range
    //
    //--------------------------------------------------------------------------
    
    /**
     *  Enable/disable this component. This also enables/disables any of the 
     *  skin parts for this component.
     */
    override public function set enabled(value:Boolean):void;
    
    override public function set maximum(value:Number):void;

    override public function set minimum(value:Number):void;
    
    override public function set value(newValue:Number):void;
    
    //--------------------------------------------------------------------------
    //
    // Properties
    //
    //--------------------------------------------------------------------------

    //---------------------------------
    // clickOffset
    //---------------------------------

    /**
     *  The clickOffset is the point in the local coordinates of 
     *  the thumb where the last mouse down event occurred. This
     *  is used by calculateNewValue() to determine what value
     *  the thumb has been dragged to.
     */
    protected function get clickOffset():Point;

    //---------------------------------
    // trackSize
    //---------------------------------
    
    /**
     *  This method returns the size of the logical track. 
     *  Subclasses need to override this method to return 
     *  an appropriate value. Note that this number can 
     *  represent any system of units, but those units must 
     *  be consistent with the values returned by
     *  pointToPosition, thumbSize, and valueToPosition.
     */
    protected function get trackSize():Number;
    
    //---------------------------------
    // thumbSize
    //---------------------------------
    
    /**
     *  The size of the thumb on the logical track in the 
     *  units of the subclass, which must be consistent with 
     *  trackSize, pointToPosition and valueToPosition. The 
     *  default thumbSize on the logical track is 0.
     * 
     *  @default 0
     */
    protected function get thumbSize():Number;
    
    protected function set thumbSize(value:Number):void;
    
    //--------------------------------------------------------------------------
    //
    // Methods
    //
    //--------------------------------------------------------------------------

    /**
     *  @private
     */
    override protected function updateDisplayList(unscaledWidth:Number, 
                                                  unscaledHeight:Number):void;

    /**
     *  Adds an eventListener for the updateComplete event so
     *  that TrackBase will correctly position the thumb.
     */
    override protected function attachBehaviors():void;
    
    /**
     *  Removes the updateComplete event handler.
     */
    override protected function removeBehaviors():void;
    /**
     *  Adds event handlers to the track and thumb for mouse events.
     */
    override protected function partAdded(partName:String, instance:*):void;

    /**
     *  Remove event handlers from skin parts.
     */
    override protected function partRemoved(partName:String, instance:*):void;

    /**
     *  Make the skins reflect the enabled state of TrackBase
     */
    protected function enableSkinParts(value:Boolean):void;
    
    /**
     *  Utility method which returns the Range value for a given
     *  position on the track. The Range value is calculated by
     *  finding what fraction of the logical track the position
     *  represents and then multiplying that by the Range.
     */
    protected function positionToValue(position:Number):Number;
    
    /**
     *  Utility function to calculate the thumb's position
     *  corresponding to the given value. The thumb position
     *  is calculated by finding what fraction of the range
     *  the value represents, and then multiplying that by
     *  the logical track size minus the logical thumb size.
     */
    protected function valueToPosition(value:Number):Number;
    
    /**
     *  This function returns a position on the slider relative to its
     *  orientation and shape. The <code>localX</code> and <code>localY</code>
     *  values represent the location in the local coordinate system of the
     *  track. Subclasses must override this method and return the
     *  appropriate value for their situation. Values should not be clamped to
     *  the ends of the track, as that clamping will happen later, prior
     *  to setting the thumb position.
     */
    protected function pointToPosition(localX:Number, localY:Number):Number;

    /**
     *  This method positions the thumb button correctly, given
     *  the position. Subclasses should override this method to position 
     *  the thumb appropriately for their situation.
     */
    protected function positionThumb(thumbPos:Number):void {};
    
    /**
     *  This method sizes the thumb button correctly, given
     *  the thumbSize. Subclasses should override this method to size 
     *  the thumb appropriately for their situation.
     */
    protected function sizeThumb(thumbSize:Number):void {};

    /**
     *  This utility method calculates an appropriate size for the thumb
     *  button, given the current range, pageSize, and trackSize settings.
     *  Subclasses should override this to calculate the correct size in
     *  the units of position.
     * 
     *  @default 0
     */
    protected function calculateThumbSize():Number;

    /**
     *  Given a MouseEvent that contains where the thumb was dragged to and
     *  the previous value of the thumb, calculateNewValue() returns a new
     *  value based on the difference calculated in the mouseDown handler
     *  and the new position. The value is also restricted to the allowed
     *  values here. This method usually should not be overridden.
     */
    protected function calculateNewValue(prevValue:Number, event:MouseEvent):Number;

    //--------------------------------------------------------------------------
    // 
    // Event Handlers
    //
    //--------------------------------------------------------------------------

    /**
     *  @private
     *  Force the component to set itself up correctly now that the
     *  track is completely loaded.
     */
    protected function track_updateCompleteHandler(event:Event):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 {};
}

}