package spark.components.supportClasses
{

import flash.events.Event;

import spark.components.supportClasses.SkinnableComponent

import mx.events.FlexEvent;

/**
 *  The Range class holds a value and an allowed range for that 
 *  value, defined by <code>minimum</code> and <code>maximum</code> properties. 
 *  The <code>value</code> property 
 *  is always constrained to be between the current <code>minimum</code> and
 *  <code>maximum</code>, and the <code>minimum</code>,
 *  and <code>maximum</code> are always constrained
 *  to be in the proper numerical order, such that
 *  <code>(minimum &lt;= value &lt;= maximum)</code> is <code>true</code>. 
 *  If the value of the <code>snapInterval</code> property is not 0, 
 *  then the <code>value</code> property is also constrained to be a multiple of 
 *  <code>snapInterval</code>.
 * 
 *  <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
    //---------------------------------

    /**
     *  The maximum valid <code>value</code>.
     * 
     *  <p>Changes to the value property are constrained
     *  by <code>commitProperties()</code> to be less than or equal to
     *  maximum with the <code>nearestValidValue()</code> method.</p> 
     *
     *  @default 100
     */
    public function get maximum():Number;
    public function set maximum(value:Number):void;

    //---------------------------------
    // minimum
    //---------------------------------

    /**
     *  The minimum valid <code>value</code>.
     * 
     *  <p>Changes to the value property are constrained
     *  by <code>commitProperties()</code> to be greater than or equal to
     *  minimum with the <code>nearestValidValue()</code> method.</p> 
     *
     *  @default 0
     */
    public function get minimum():Number;
    public function set minimum(value:Number):void;

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

    /**
     *  The amount that the <code>value</code> property 
     *  changes when the <code>changeValueByStep()</code> method is called. It must
     *  be a multiple of <code>snapInterval</code>, unless 
     *  <code>snapInterval</code> is 0. 
     *  If <code>stepSize</code>
     *  is not a multiple, it is rounded to the nearest 
     *  multiple that is greater than or equal to <code>snapInterval</code>.
     *
     *  @default 1
     */
    public function get stepSize():Number;
    public function set stepSize(value:Number):void;

    //---------------------------------
    // value
    //---------------------------------

    <a href="Bindable%28event%3D%26quot%3BvalueCommit%26quot%3B%29">Bindable(event="valueCommit")</a>

    /**
     *  The current value for this range.
     *  
     *  <p>Changes to the value property are constrained
     *  by <code>commitProperties()</code> to be greater than or equal to
     *  the <code>minimum</code> property, less than or equal to the <code>maximum</code> property, and a
     *  multiple of <code>snapInterval</code> with the <code>nearestValidValue()</code>
     *  method.</p> 
     * 
     *  @default 0
     */
    public function get value():Number;
    public function set value(newValue:Number):void;

    //---------------------------------
    // snapInterval
    //---------------------------------

    /**
     *  If nonzero, valid values are the sum of the minimum with integer multiples
     *  of this property and less than or equal to the maximum.
     *  
     *  <p>If the value of this property is zero, then valid values are only constrained
     *  to be between minimum and maximum inclusive.</p>
     * 
     *  <p>This property also constrains valid values for the <code>stepSize</code> property when set.
     *  If this property is not explicitly set and <code>stepSize</code> is set, 
     *  then <code>snapInterval</code> defaults to <code>stepSize</code>.</p>
     *  
     *  @default 1
     */
    public function get snapInterval():Number;
    public function set snapInterval(value:Number):void;

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

    /**
     *  Returns the sum of the minimum with an integer multiple of <code>interval</code> that's 
     *  closest to <code>value</code>, unless <code>value</code> is closer to the maximum limit,
     *  in which case the maximum is returned.
     * 
     *  <p>If <code>interval</code> is equal to 0, the value is clipped to the minimum and maximum 
     *  limits.</p>
     * 
     *  <p>The valid values for a range are defined by the sum of the <code>minimum</code> property
     *  with multiples of the <code>interval</code> and also defined to be less than or equal to the
     *  <code>maximum</code> property.
     * 
     *  The maximum need not be a multiple of <code>snapInterval</code>.</p>
     * 
     *  <p>For example, if <code>minimum</code> is equal to 1, <code>maximum</code> is equal to 6,
     *  and <code>snapInterval</code> is equal to 2, the valid
     *  values for the Range are 1, 3, 5, 6.
     * 
     *  Similarly, if <code>minimum</code> is equal to 2, <code>maximum</code> is equal to 9,
     *  and <code>snapInterval</code> is equal to 1.5, the valid
     *  values for the Range are 2, 3.5, 5, 6.5, 8, and 9.</p>
     * 
     *  @param value The input value.
     *  @param interval The value of snapInterval or an integer multiple of snapInterval.
     *  @return The valid value that's closest to the input.
     */
    protected function nearestValidValue(value:Number, interval:Number):Number;

    /**
     *  Sets the backing store for the <code>value</code> property and 
     *  dispatches a <code>valueCommit</code> event if the property changes.  
     * 
     *  <p>All updates to the <code>value</code> property cause a call to this method.</p>
     * 
     *  <p>This method assumes that the caller has already used the <code>nearestValidValue()</code> method
     *  to constrain the value parameter</p>
     * 
     *  @param value The new value of the <code>value</code> property.
     */
    protected function setValue(value:Number):void;

    /**
     *  Increases or decreases <code>value</code> by <code>stepSize</code>.
     *
     *  @param increase If true, adds <code>stepSize</code> to <code>value</code>, otherwise, subtracts it.
     */
    public function changeValueByStep(increase:Boolean = true):void;
}

}