Flex SDK Wiki

# Spark Range - Functional and Design Specification ---- \\ ## Glossary ---- **scale** - the **scale** of a Range is the set of allowed numbers that the [`value`](%23Properties) property can take on. The allowed numbers are increments of the [`snapInterval`](%23Properties) starting from minimum, but also includes the maximum. For example, a Range with: minimum = -1 maximum = 10 snapInterval = 3 would have a scale of \[-1, 2, 5, 8, 10\]. ## Summary and Background ---- The **Range** base class provides basic functionality for a value constrained by a maximum and minimum as well as restricting the value to a certain increment. Range inherits from SkinnableComponent and subclasses include [TrackBase](Spark%20TrackBase) and [Spinner](Spark%20Spinner). This class allows us to unify ideas of a [scale](%23Glossary) and [stepping](%23Public%20Methods) across subclasses. ## Usage Scenarios ---- * [TrackBase](Spark%20TrackBase) subclasses Range and is the base class for [SliderBase](Spark%20Slider) and [ScrollBarBase](Spark%20ScrollBar) * [Spinner](Spark%20Spinner) subclasses Range and is the base class for [NumericStepper](Spark%20NumericStepper) * ProgressBar will subclass Range as well. ## Detailed Description ---- ##### Properties `value` - The current value. The default is 0. `minimum, maximum` - The minimum and maximum values that constrain value. The minimum may not be > maximum nor can the maximum be < minimum, but they can be equal. The defaults of minimum and maximum are 0 and 100. `snapInterval` - If greater than 0, snapInterval constrains the value of the Range to be increments of snapInterval starting from the minimum, but less than the maximum. If snapInterval is 0, then the value can be any number between minimum and maximum. Also, the value may always be set to the maximum. The default of snapInterval is 1. `stepSize` - stepSize is the amount that the value changes when `changeValueByStep()` is called. It must be a multiple of snapInterval unless snapInterval is 0. If the stepSize is not a multiple of snapInterval, it is rounded to the nearest multiple >= snapInterval. The default of stepSize is 1. Also, if stepSize is explicitly set but snapInterval is not, snapInterval will default to stepSize until snapInterval is explicitly set. ##### Events `valueCommit` - The "valueCommit" event is dispatched when the value changes. ##### Public Methods `changeValueByStep()` - The `changeValueByStep()` method will step the value up or down by `stepSize` depending on the parameter given. ##### Protected Methods `nearestValidValue()` - Rounds the given value to the closest increment of interval starting from the minimum, but less than or equal to the maximum. If interval is 0, then the value is only constrained by the maximum and minimum. `setValue()` - Sets the backing store for value and dispatches a valueCommit event. ## API Description ---- 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 minimum and maximum properties. * The value property * is always constrained to be between the current minimum and * maximum, and the minimum, * and maximum are always constrained * to be in the proper numerical order, such that * (minimum <= value <= maximum) is true. * If the value of the snapInterval property is not 0, * then the value property is also constrained to be a multiple of * snapInterval. * *

Range is a base class for various controls that require range * functionality, including TrackBase and Spinner.

* * @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 value. * *

Changes to the value property are constrained * by commitProperties() to be less than or equal to * maximum with the nearestValidValue() method.

* * @default 100 */ public function get maximum():Number; public function set maximum(value:Number):void; //--------------------------------- // minimum //--------------------------------- /** * The minimum valid value. * *

Changes to the value property are constrained * by commitProperties() to be greater than or equal to * minimum with the nearestValidValue() method.

* * @default 0 */ public function get minimum():Number; public function set minimum(value:Number):void; //--------------------------------- // stepSize //--------------------------------- /** * The amount that the value property * changes when the changeValueByStep() method is called. It must * be a multiple of snapInterval, unless * snapInterval is 0. * If stepSize * is not a multiple, it is rounded to the nearest * multiple that is greater than or equal to snapInterval. * * @default 1 */ public function get stepSize():Number; public function set stepSize(value:Number):void; //--------------------------------- // value //--------------------------------- Bindable(event="valueCommit") /** * The current value for this range. * *

Changes to the value property are constrained * by commitProperties() to be greater than or equal to * the minimum property, less than or equal to the maximum property, and a * multiple of snapInterval with the nearestValidValue() * method.

* * @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. * *

If the value of this property is zero, then valid values are only constrained * to be between minimum and maximum inclusive.

* *

This property also constrains valid values for the stepSize property when set. * If this property is not explicitly set and stepSize is set, * then snapInterval defaults to stepSize.

* * @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 interval that's * closest to value, unless value is closer to the maximum limit, * in which case the maximum is returned. * *

If interval is equal to 0, the value is clipped to the minimum and maximum * limits.

* *

The valid values for a range are defined by the sum of the minimum property * with multiples of the interval and also defined to be less than or equal to the * maximum property. * * The maximum need not be a multiple of snapInterval.

* *

For example, if minimum is equal to 1, maximum is equal to 6, * and snapInterval is equal to 2, the valid * values for the Range are 1, 3, 5, 6. * * Similarly, if minimum is equal to 2, maximum is equal to 9, * and snapInterval is equal to 1.5, the valid * values for the Range are 2, 3.5, 5, 6.5, 8, and 9.

* * @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 value property and * dispatches a valueCommit event if the property changes. * *

All updates to the value property cause a call to this method.

* *

This method assumes that the caller has already used the nearestValidValue() method * to constrain the value parameter

* * @param value The new value of the value property. */ protected function setValue(value:Number):void; /** * Increases or decreases value by stepSize. * * @param increase If true, adds stepSize to value, otherwise, subtracts it. */ public function changeValueByStep(increase:Boolean = true):void; } } ## B Features ---- ## Additional Implementation Details ---- none ## Prototype Work ---- ## Compiler Work ---- none ## Web Tier Compiler Impact ---- none ## Flex Feature Dependencies ---- ## Backwards Compatibility ---- ### Syntax changes None - New Class ### Behavior None ### Warnings/Deprecation None ## Accessibility ---- Support Halo equivalent. ## Performance ---- none. ## Globalization ---- none ## Localization ---- ### Compiler Features none. ## Documentation ---- Yes. ## QA ---- Yes. ----