3
Copyright 2012 Yahoo! Inc. All rights reserved.
4
Licensed under the BSD License.
5
http://yuilibrary.com/license/
7
YUI.add('slider-value-range', function(Y) {
10
* Adds value support for Slider as a range of integers between a configured
11
* minimum and maximum value. For use with <code>Y.Base.build(..)</code> to
12
* add the plumbing to <code>Y.SliderBase</code>.
15
* @submodule slider-value-range
18
// Constants for compression or performance
22
// MINORSTEP = 'minorStep',
23
// MAJORSTEP = 'majorStep',
28
* One class of value algorithm that can be built onto SliderBase. By default,
29
* values range between 0 and 100, but you can configure these on the
30
* built Slider class by setting the <code>min</code> and <code>max</code>
31
* configurations. Set the initial value (will cause the thumb to move to the
32
* appropriate location on the rail) in configuration as well if appropriate.
34
* @class SliderValueRange
36
function SliderValueRange() {
37
this._initSliderValueRange();
40
Y.SliderValueRange = Y.mix( SliderValueRange, {
42
// Prototype properties and methods that will be added onto host class
46
* Factor used to translate value -> position -> value.
55
* Stub for construction logic. Override if extending this class and
56
* you need to set something up during the initializer phase.
58
* @method _initSliderValueRange
61
_initSliderValueRange: function () {},
64
* Override of stub method in SliderBase that is called at the end of
65
* its bindUI stage of render(). Subscribes to internal events to
66
* trigger UI and related state updates.
68
* @method _bindValueLogic
71
_bindValueLogic: function () {
73
minChange : this._afterMinChange,
74
maxChange : this._afterMaxChange,
75
valueChange: this._afterValueChange
80
* Move the thumb to appropriate position if necessary. Also resets
81
* the cached offsets and recalculates the conversion factor to
82
* translate position to value.
84
* @method _syncThumbPosition
87
_syncThumbPosition: function () {
88
this._calculateFactor();
90
this._setPosition( this.get( VALUE ) );
94
* Calculates and caches
95
* (range between max and min) / (rail length)
96
* for fast runtime calculation of position -> value.
98
* @method _calculateFactor
101
_calculateFactor: function () {
102
var length = this.get( 'length' ),
103
thumbSize = this.thumb.getStyle( this._key.dim ),
104
min = this.get( MIN ),
105
max = this.get( MAX );
107
// The default thumb width is based on Sam skin's thumb dimension.
108
// This attempts to allow for rendering off-DOM, then attaching
109
// without the need to call syncUI(). It is still recommended
110
// to call syncUI() in these cases though, just to be sure.
111
length = parseFloat( length ) || 150;
112
thumbSize = parseFloat( thumbSize ) || 15;
114
this._factor = ( max - min ) / ( length - thumbSize );
116
Y.log("Calculating factor(~" + this._factor.toFixed(3) + " = (max(" + max + ") - min(" + min + ")) / (length(" + length + ") - thumb size(" + thumbSize + "))","info","slider");
120
* Dispatch the new position of the thumb into the value setting
123
* @method _defThumbMoveFn
124
* @param e { EventFacade } The host's thumbMove event
127
_defThumbMoveFn: function ( e ) {
128
// To prevent set('value', x) from looping back around
129
if (e.source !== 'set') {
130
this.set(VALUE, this._offsetToValue(e.offset));
135
* <p>Converts a pixel position into a value. Calculates current
136
* thumb offset from the leading edge of the rail multiplied by the
137
* ratio of <code>(max - min) / (constraining dim)</code>.</p>
139
* <p>Override this if you want to use a different value mapping
142
* @method _offsetToValue
143
* @param offset { Number } X or Y pixel offset
144
* @return { mixed } Value corresponding to the provided pixel offset
147
_offsetToValue: function ( offset ) {
149
var value = round( offset * this._factor ) + this.get( MIN );
151
Y.log("Offset: " + offset + " => Value: " + value, "info", "slider");
152
return round( this._nearestValue( value ) );
156
* Converts a value into a pixel offset for use in positioning
157
* the thumb according to the reverse of the
158
* <code>_offsetToValue( xy )</code> operation.
160
* @method _valueToOffset
161
* @param val { Number } The value to map to pixel X or Y position
162
* @return { Number } The pixel offset
165
_valueToOffset: function ( value ) {
166
var offset = round( ( value - this.get( MIN ) ) / this._factor );
168
Y.log("Value: " + value + " => Offset: " + offset, "info", "slider");
173
* Returns the current value. Override this if you want to introduce
174
* output formatting. Otherwise equivalent to slider.get( "value" );
179
getValue: function () {
180
return this.get( VALUE );
184
* Updates the current value. Override this if you want to introduce
185
* input value parsing or preprocessing. Otherwise equivalent to
186
* slider.set( "value", v );
189
* @param val {Number} The new value
193
setValue: function ( val ) {
194
return this.set( VALUE, val );
198
* Update position according to new min value. If the new min results
199
* in the current value being out of range, the value is set to the
200
* closer of min or max.
202
* @method _afterMinChange
203
* @param e { EventFacade } The <code>min</code> attribute change event.
206
_afterMinChange: function ( e ) {
209
this._syncThumbPosition();
213
* Update position according to new max value. If the new max results
214
* in the current value being out of range, the value is set to the
215
* closer of min or max.
217
* @method _afterMaxChange
218
* @param e { EventFacade } The <code>max</code> attribute change event.
221
_afterMaxChange: function ( e ) {
224
this._syncThumbPosition();
228
* Verifies that the current value is within the min - max range. If
229
* not, value is set to either min or max, depending on which is
232
* @method _verifyValue
235
_verifyValue: function () {
236
var value = this.get( VALUE ),
237
nearest = this._nearestValue( value );
239
if ( value !== nearest ) {
240
// @TODO Can/should valueChange, minChange, etc be queued
241
// events? To make dd.set( 'min', n ); execute after minChange
242
// subscribers before on/after valueChange subscribers.
243
this.set( VALUE, nearest );
248
* Propagate change to the thumb position unless the change originated
249
* from the thumbMove event.
251
* @method _afterValueChange
252
* @param e { EventFacade } The <code>valueChange</code> event.
255
_afterValueChange: function ( e ) {
257
Y.log("Positioning thumb after set('value',x)","info","slider");
258
this._setPosition( val, { source: 'set' } );
259
this.thumb.set('aria-valuenow', val);
260
this.thumb.set('aria-valuetext', val);
264
* Positions the thumb in accordance with the translated value.
266
* @method _setPosition
267
* @param value {Number} Value to translate to a pixel position
268
* @param [options] {Object} Details object to pass to `_uiMoveThumb`
271
_setPosition: function ( value, options ) {
272
this._uiMoveThumb( this._valueToOffset( value ), options );
276
* Validates new values assigned to <code>min</code> attribute. Numbers
277
* are acceptable. Override this to enforce different rules.
279
* @method _validateNewMin
280
* @param value {Any} Value assigned to <code>min</code> attribute.
281
* @return {Boolean} True for numbers. False otherwise.
284
_validateNewMin: function ( value ) {
285
return Y.Lang.isNumber( value );
289
* Validates new values assigned to <code>max</code> attribute. Numbers
290
* are acceptable. Override this to enforce different rules.
292
* @method _validateNewMax
293
* @param value { mixed } Value assigned to <code>max</code> attribute.
294
* @return { Boolean } True for numbers. False otherwise.
297
_validateNewMax: function ( value ) {
298
return Y.Lang.isNumber( value );
302
* Restricts new values assigned to <code>value</code> attribute to be
303
* between the configured <code>min</code> and <code>max</code>.
304
* Rounds to nearest integer value.
306
* @method _setNewValue
307
* @param value { Number } Value assigned to <code>value</code> attribute
308
* @return { Number } Normalized and constrained value
311
_setNewValue: function ( value ) {
312
return round( this._nearestValue( value ) );
316
* Returns the nearest valid value to the value input. If the provided
317
* value is outside the min - max range, accounting for min > max
318
* scenarios, the nearest of either min or max is returned. Otherwise,
319
* the provided value is returned.
321
* @method _nearestValue
322
* @param value { mixed } Value to test against current min - max range
323
* @return { Number } Current min, max, or value if within range
326
_nearestValue: function ( value ) {
327
var min = this.get( MIN ),
328
max = this.get( MAX ),
331
// Account for reverse value range (min > max)
332
tmp = ( max > min ) ? max : min;
333
min = ( max > min ) ? min : max;
336
return ( value < min ) ?
346
* Attributes that will be added onto host class.
355
* The value associated with the farthest top, left position of the
356
* rail. Can be greater than the configured <code>max</code> if you
357
* want values to increase from right-to-left or bottom-to-top.
365
validator: '_validateNewMin'
369
* The value associated with the farthest bottom, right position of
370
* the rail. Can be less than the configured <code>min</code> if
371
* you want values to increase from right-to-left or bottom-to-top.
379
validator: '_validateNewMax'
383
* amount to increment/decrement the Slider value
384
* when the arrow up/down/left/right keys are pressed
386
* @attribute minorStep
395
* amount to increment/decrement the Slider value
396
* when the page up/down keys are pressed
398
* @attribute majorStep
407
* The value associated with the thumb's current position on the
408
* rail. Defaults to the value inferred from the thumb's current
409
* position. Specifying value in the constructor will move the
410
* thumb to the position that corresponds to the supplied value.
414
* @default (inferred from current thumb position)
418
setter: '_setNewValue'
425
}, '3.5.1' ,{requires:['slider-base']});