slider-value-range.js revision a79d36e65c99c6422a9eb88d1fc3be127e92b391
/**
* Adds value support for Slider as a range of integers between a configured
* minimum and maximum value. For use with <code>Y.Base.build(..)</code> to
* add the plumbing to <code>Y.SliderBase</code>.
*
* @module slider
* @submodule slider-value-range
*/
// Constants for compression or performance
var MIN = 'min',
MAX = 'max',
VALUE = 'value',
// MINORSTEP = 'minorStep',
// MAJORSTEP = 'majorStep',
/**
* One class of value algorithm that can be built onto SliderBase. By default,
* values range between 0 and 100, but you can configure these on the
* built Slider class by setting the <code>min</code> and <code>max</code>
* configurations. Set the initial value (will cause the thumb to move to the
* appropriate location on the rail) in configuration as well if appropriate.
*
* @class SliderValueRange
*/
function SliderValueRange() {
this._initSliderValueRange();
}
// Prototype properties and methods that will be added onto host class
prototype: {
/**
* Factor used to translate value -> position -> value.
*
* @property _factor
* @type {Number}
* @protected
*/
_factor: 1,
/**
* Stub for construction logic. Override if extending this class and
* you need to set something up during the initializer phase.
*
* @method _initSliderValueRange
* @protected
*/
_initSliderValueRange: function () {},
/**
* Override of stub method in SliderBase that is called at the end of
* its bindUI stage of render(). Subscribes to internal events to
* trigger UI and related state updates.
*
* @method _bindValueLogic
* @protected
*/
_bindValueLogic: function () {
this.after( {
minChange : this._afterMinChange,
maxChange : this._afterMaxChange,
valueChange: this._afterValueChange
} );
},
/**
* Move the thumb to appropriate position if necessary. Also resets
* the cached offsets and recalculates the conversion factor to
* translate position to value.
*
* @method _syncThumbPosition
* @protected
*/
_syncThumbPosition: function () {
this._calculateFactor();
},
/**
* Calculates and caches
* (range between max and min) / (rail length)
* for fast runtime calculation of position -> value.
*
* @method _calculateFactor
* @protected
*/
_calculateFactor: function () {
// The default thumb width is based on Sam skin's thumb dimension.
// This attempts to allow for rendering off-DOM, then attaching
// without the need to call syncUI(). It is still recommended
// to call syncUI() in these cases though, just to be sure.
},
/**
* Dispatch the new position of the thumb into the value setting
* operations.
*
* @method _defThumbMoveFn
* @param e { EventFacade } The host's thumbMove event
* @protected
*/
_defThumbMoveFn: function ( e ) {
// This test avoids duplication of this.set(..) if the origin
// of this thumbMove is from slider.set('value',x);
// slider.set() -> afterValueChange -> uiMoveThumb ->
// fire(thumbMove) -> _defThumbMoveFn -> this.set()
/* FIXME: aria and keyboard have problems with this
"if condition" when slider length is less than max - min.
If the value change caused by keyboard doesn't result
in the thumb moving, the value is set back to previous value
by _defThumbMoveFn (slider-value-range.js).
*/
}
},
/**
* <p>Converts a pixel position into a value. Calculates current
* thumb offset from the leading edge of the rail multiplied by the
* ratio of <code>(max - min) / (constraining dim)</code>.</p>
*
* <p>Override this if you want to use a different value mapping
* algorithm.</p>
*
* @method _offsetToValue
* @param offset { Number } X or Y pixel offset
* @return { mixed } Value corresponding to the provided pixel offset
* @protected
*/
_offsetToValue: function ( offset ) {
},
/**
* Converts a value into a pixel offset for use in positioning
* the thumb according to the reverse of the
* <code>_offsetToValue( xy )</code> operation.
*
* @method _valueToOffset
* @param val { Number } The value to map to pixel X or Y position
* @return { Number } The pixel offset
* @protected
*/
_valueToOffset: function ( value ) {
return offset;
},
/**
* Returns the current value. Override this if you want to introduce
* output formatting. Otherwise equivalent to slider.get( "value" );
*
* @method getValue
* @return {Number}
*/
getValue: function () {
},
/**
* Updates the current value. Override this if you want to introduce
* input value parsing or preprocessing. Otherwise equivalent to
* slider.set( "value", v );
*
* @method setValue
* @param val {Number} The new value
* @return {Slider}
* @chainable
*/
},
/**
* Update position according to new min value. If the new min results
* in the current value being out of range, the value is set to the
* closer of min or max.
*
* @method _afterMinChange
* @param e { EventFacade } The <code>min</code> attribute change event.
* @protected
*/
_afterMinChange: function ( e ) {
this._verifyValue();
this._syncThumbPosition();
},
/**
* Update position according to new max value. If the new max results
* in the current value being out of range, the value is set to the
* closer of min or max.
*
* @method _afterMaxChange
* @param e { EventFacade } The <code>max</code> attribute change event.
* @protected
*/
_afterMaxChange: function ( e ) {
this._verifyValue();
this._syncThumbPosition();
},
/**
* Verifies that the current value is within the min - max range. If
* not, value is set to either min or max, depending on which is
* closer.
*
* @method _verifyValue
* @protected
*/
_verifyValue: function () {
// events? To make dd.set( 'min', n ); execute after minChange
}
},
/**
* Propagate change to the thumb position unless the change originated
* from the thumbMove event.
*
* @method _afterValueChange
* @param e { EventFacade } The <code>valueChange</code> event.
* @protected
*/
_afterValueChange: function ( e ) {
if ( !e.positioned ) {
this._setPosition( e.newVal );
}
},
/**
* Positions the thumb in accordance with the translated value.
*
* @method _setPosition
* @protected
*/
_setPosition: function ( value ) {
},
/**
* Validates new values assigned to <code>min</code> attribute. Numbers
* are acceptable. Override this to enforce different rules.
*
* @method _validateNewMin
* @param value { mixed } Value assigned to <code>min</code> attribute.
* @return { Boolean } True for numbers. False otherwise.
* @protected
*/
_validateNewMin: function ( value ) {
},
/**
* Validates new values assigned to <code>max</code> attribute. Numbers
* are acceptable. Override this to enforce different rules.
*
* @method _validateNewMax
* @param value { mixed } Value assigned to <code>max</code> attribute.
* @return { Boolean } True for numbers. False otherwise.
* @protected
*/
_validateNewMax: function ( value ) {
},
/**
* Restricts new values assigned to <code>value</code> attribute to be
* between the configured <code>min</code> and <code>max</code>.
* Rounds to nearest integer value.
*
* @method _setNewValue
* @param value { Number } Value assigned to <code>value</code> attribute
* @return { Number } Normalized and constrained value
* @protected
*/
_setNewValue: function ( value ) {
},
/**
* Returns the nearest valid value to the value input. If the provided
* value is outside the min - max range, accounting for min > max
* scenarios, the nearest of either min or max is returned. Otherwise,
* the provided value is returned.
*
* @method _nearestValue
* @param value { mixed } Value to test against current min - max range
* @return { Number } Current min, max, or value if within range
* @protected
*/
_nearestValue: function ( value ) {
tmp;
// Account for reverse value range (min > max)
min :
max :
}
},
/**
* Attributes that will be added onto host class.
*
* @property ATTRS
* @type {Object}
* @static
* @protected
*/
ATTRS: {
/**
* The value associated with the farthest top, left position of the
* rail. Can be greater than the configured <code>max</code> if you
* want values to increase from right-to-left or bottom-to-top.
*
* @attribute min
* @type { Number }
* @default 0
*/
min: {
value : 0,
validator: '_validateNewMin'
},
/**
* The value associated with the farthest bottom, right position of
* the rail. Can be less than the configured <code>min</code> if
* you want values to increase from right-to-left or bottom-to-top.
*
* @attribute max
* @type { Number }
* @default 100
*/
max: {
value : 100,
validator: '_validateNewMax'
},
/**
*
* @attribute minorStep
* @type {Number}
* @default 1
*/
minorStep : {
value:1
},
/**
*
* @attribute majorStep
* @type {Number}
* @default 10
*/
majorStep : {
value:10
},
/**
* The value associated with the thumb's current position on the
* rail. Defaults to the value inferred from the thumb's current
* position. Specifying value in the constructor will move the
* thumb to the position that corresponds to the supplied value.
*
* @attribute value
* @type { Number }
* @default (inferred from current thumb position)
*/
value: {
value : 0,
setter: '_setNewValue'
}
}
}, true );