Spark Slider - Functional and Design Specification

Glossary

position - The position of the thumb is defined in the units of the subclasses of TrackBase (ie: pixels, radians, etc...). It is converted back and forth from the actual value of TrackBase.

logical track, logical thumb - The logical track is the range of positions determined in the units of the subclass. The logical thumb can move through the entire range of positions from end to end.

visual track, visual thumb - The visual track and visual thumb are the actual track and thumb that is rendered. They may need to be offset from the logical track and thumb to provide the correct look.

These concepts of logical and visual track separate the layout of the track from the functional part of the track.

Summary and Background

The Slider class is the base class for FxSlider controls. It inherits from TrackBase, which contains code common to both Sliders and ScrollBars. Slider provides basic functionality for Slider controls such as liveDragging, keyboard handling and track click handling.

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
• The thumb

Inherited Properties

See Range and TrackBase

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.

Events

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

Track Behavior

Clicking on the track should result in the thumb sliding to that position. Currently, the track click causes the thumb to just appear at that point. In the future, the "slide" will be implemented along with functions that will allow it to be customizable (providing parameters to an easing function, etc...).

Keyboard Behavior

When the thumb has focus:

• Left/Down Arrow - decreases the value. (will change)
• Right/Up Arrow - increase the value. (will change)
• Home/End - Change the value to the lowest and highest possible values for the thumb that has focus. (will change)

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.

Additional Items to be considered

• Slider with more than one thumb - (B feature)
• enableTrack property - enables/disables the track.
• tickInterval/tickValues - TBD
• labels - TBD
• data tips

API Description

package spark.components.supportClasses
{

import flash.events.Event;
import flash.events.KeyboardEvent;
import flash.events.MouseEvent;
import flash.geom.Point;
import flash.ui.Keyboard;

import mx.managers.IFocusManagerComponent;

/**
 * Slider
 */
public class Slider extends TrackBase implements IFocusManagerComponent
{
    include "../core/Version.as";

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

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

    //--------------------------------------------------------------------------
    //
    // Properties
    //
    //--------------------------------------------------------------------------
    
    //--------------------------------- 
    // liveDragging
    //---------------------------------
    
    /**
     *  When liveDragging is enabled, the thumb's value is
     *  committed as it is dragged along the track instead
     *  of when the thumb is released.
     * 
     *  @default false
     */
    public function get liveDragging():Boolean;
    
    public function set liveDragging(value:Boolean):void;

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

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

    /**
     *  Converts a point retrieved from clicking on the track
     *  into a position. This allows subclasses to center
     *  their thumb when clicking on the track.
     */
    protected function pointClickToPosition(localX:Number, 
                                            localY:Number):Number;

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

    //---------------------------------
    // Thumb dragging handlers
    //---------------------------------
    
    /**
     *  @private
     */
    override protected function thumb_mouseDownHandler(event:MouseEvent):void;

    /**
     *  @private
     */
    override protected function system_mouseMoveHandler(event:MouseEvent):void;
    
    /**
     *  @private
     */
    override protected function system_mouseUpHandler(event:MouseEvent):void;

    //---------------------------------
    // Thumb keyboard handlers
    //---------------------------------

    /**
     *  Handle keyboard events. Left/Down decreases the value
     *  decreases the value by stepSize. The opposite for
     *  Right/Up arrows. The Home and End keys set the value
     *  to the min and max respectively.
     */
    protected function thumb_keyboardHandler(event:KeyboardEvent):void;

    //---------------------------------
    // Track down handlers
    //---------------------------------
    
    /**
     *  Handle mouse-down events for the slider track. We
     *  calculate the value based on the new position and then
     *  move the thumb to the correct location as well as
     *  commit the value.
     */
    override protected function track_mouseDownHandler(event:MouseEvent):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.