Spark Range - Functional and Design Specification

package spark.components.supportClasses
{
    
import flash.events.Event;

import spark.components.supportClasses.SkinnableComponent

import mx.events.FlexEvent;

/**
 *  The Range class holds a value and a legal range for that 
 *  value, defined by a minimum and maximum. <code>value</code>
 *  is always constrained to be within the current minimum and
 *  maximum, and the minimum and maximum are always constrained
 *  to be in the proper numerical order such that, at any time,
 *  (minimum &lt;= value &lt;= maximum) is true. 
 *  <code>value</code> is also constrained to be multiples of 
 *  valueInterval if valueInterval is not 0.
 * 
 *  <p>Range has a <code>stepSize</code> property to control 
 *  how much <code>value</code> will change based on small 
 *  stepping operations.</p>
 * 
 *  <p>Range is a base class for various controls that require range
 *  functionality, including TrackBase and Spinner.</p>
 * 
 *  @see spark.components.supportClasses.TrackBase
 *  @see spark.components.Spinner
 */  
public class Range extends SkinnableComponent
{
    include "../core/Version.as";

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

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

    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------
    
    //---------------------------------
    // maximum
    //---------------------------------   
    
    /**
     *  Number which represents the maximum value possible for 
     *  <code>value</code>. If the values for either 
     *  <code>minimum</code> or <code>value</code> are greater
     *  than <code>maximum</code>, they will be changed to 
     *  reflect the new <code>maximum</code>
     *
     *  @default 100
     */
    public function get maximum():Number;

    public function set maximum(value:Number):void;
    
    //---------------------------------
    // minimum
    //---------------------------------
    
    /**
     *  Number which represents the minimum value possible for 
     *  <code>value</code>. If the values for either 
     *  <code>maximum</code> or <code>value</code> are less
     *  than <code>minimum</code>, they will be changed to 
     *  reflect the new <code>minimum</code>
     *
     *  @default 0
     */
    public function get minimum():Number;
    
    public function set minimum(value:Number):void;

    //---------------------------------
    // stepSize
    //---------------------------------    

    /**
     *  <code>stepSize</code> is the amount that the value 
     *  changes when <code>step()</code> is called. It must
     *  be a multiple of <code>valueInterval</code> unless 
     *  <code>valueInterval</code> is 0. If <code>stepSize</code>
     *  is not a multiple, it is rounded to the nearest multiple 
     *  &gt;= <code>valueInterval</code>.
     *
     *  @default 1
     */
    public function get stepSize():Number;

    public function set stepSize(value:Number):void;

    //---------------------------------
    // value
    //---------------------------------
    
    [Bindable(event="valueCommit")]

    /**
     *  Number which represents the current value for this range. 
     *  <code>value</code> will always be constrained to lie 
     *  within the current <code>minimum</code> and 
     *  <code>maximum</code> values. It also must be a multiple
     *  of <code>valueInterval</code>.
     * 
     *  @default 0
     */
    public function get value():Number;

    public function set value(newValue:Number):void;
    
    //---------------------------------
    // valueInterval
    //---------------------------------   

    /**
     *  If greater than 0, <code>valueInterval</code> constrains
     *  <code>value</code> to multiples of itself. If it is 0, then 
     *  <code>value</code> can be any number between minimum and 
     *  maximum. Also, <code>value</code> may always be set to the 
     *  minimum and maximum.
     *  Changing <code>valueInterval</code> also may change 
     *  <code>stepSize</code> to be a multiple of 
     *  <code>valueInterval</code> and &gt;= <code>valueInterval</code>.
     * 
     *  @default 1
     */
    public function get valueInterval():Number;

    public function set valueInterval(value:Number):void;

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

    /**
     *  @private
     */
    override protected function commitProperties():void;

    /**
     *  Utility function to round intervals (such as 
     *  <code>stepSize</code>) to a multiple of valueInterval.
     */
    protected function nearestValidInterval(value:Number, interval:Number):Number;

    /**
     *  Rounds the given value to the closest multiple of the
     *  given interval and constrains it to the range. If interval
     *  is 0, then the value is only bound to the range.
     * 
     *  @param value The value to be rounded.
     *  @param interval The interval to round the value against.
     *  @return The rounded value or 0 if value was NaN.

     */
    protected function nearestValidValue(value:Number, interval:Number):Number;
    
    /**
     *  Directly sets the value without going through the correction
     *  and invalidation processes. Subclasses may use this method if
     *  they wish to customize behavior.
     * 
     *  @param value The number to set <code>value</code>
     */
    protected function setValue(value:Number):void;
    
    /**
     *  Steps the range value up or down.
     *
     *  @param increase Whether the stepping action increases or
     *  decreases <code>value</code>.
     */
    public function step(increase:Boolean = true):void;
}

}