3
Copyright 2011 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
26
* One class of value algorithm that can be built onto SliderBase. By default,
27
* values range between 0 and 100, but you can configure these on the
28
* built Slider class by setting the <code>min</code> and <code>max</code>
29
* configurations. Set the initial value (will cause the thumb to move to the
30
* appropriate location on the rail) in configuration as well if appropriate.
32
* @class SliderValueRange
34
function SliderValueRange() {
35
this._initSliderValueRange();
38
Y.SliderValueRange = Y.mix( SliderValueRange, {
40
// Prototype properties and methods that will be added onto host class
44
* Factor used to translate value -> position -> value.
53
* Stub for construction logic. Override if extending this class and
54
* you need to set something up during the initializer phase.
56
* @method _initSliderValueRange
59
_initSliderValueRange: function () {},
62
* Override of stub method in SliderBase that is called at the end of
63
* its bindUI stage of render(). Subscribes to internal events to
64
* trigger UI and related state updates.
66
* @method _bindValueLogic
69
_bindValueLogic: function () {
71
minChange : this._afterMinChange,
72
maxChange : this._afterMaxChange,
73
valueChange: this._afterValueChange
78
* Move the thumb to appropriate position if necessary. Also resets
79
* the cached offsets and recalculates the conversion factor to
80
* translate position to value.
82
* @method _syncThumbPosition
85
_syncThumbPosition: function () {
86
this._calculateFactor();
88
this._setPosition( this.get( VALUE ) );
92
* Calculates and caches
93
* (range between max and min) / (rail length)
94
* for fast runtime calculation of position -> value.
96
* @method _calculateFactor
99
_calculateFactor: function () {
100
var length = this.get( 'length' ),
101
thumbSize = this.thumb.getStyle( this._key.dim ),
102
min = this.get( MIN ),
103
max = this.get( MAX );
105
// The default thumb width is based on Sam skin's thumb dimension.
106
// This attempts to allow for rendering off-DOM, then attaching
107
// without the need to call syncUI(). It is still recommended
108
// to call syncUI() in these cases though, just to be sure.
109
length = parseFloat( length ) || 150;
110
thumbSize = parseFloat( thumbSize ) || 15;
112
this._factor = ( max - min ) / ( length - thumbSize );
114
Y.log("Calculating factor(~" + this._factor.toFixed(3) + " = (max(" + max + ") - min(" + min + ")) / (length(" + length + ") - thumb size(" + thumbSize + "))","info","slider");
118
* Dispatch the new position of the thumb into the value setting
121
* @method _defThumbMoveFn
122
* @param e { EventFacade } The host's thumbMove event
125
_defThumbMoveFn: function ( e ) {
126
var previous = this.get( VALUE ),
127
value = this._offsetToValue( e.offset );
129
// This test avoids duplication of this.set(..) if the origin
130
// of this thumbMove is from slider.set('value',x);
131
// slider.set() -> afterValueChange -> uiMoveThumb ->
132
// fire(thumbMove) -> _defThumbMoveFn -> this.set()
133
if ( previous !== value ) {
134
this.set( VALUE, value, { positioned: true } );
139
* <p>Converts a pixel position into a value. Calculates current
140
* thumb offset from the leading edge of the rail multiplied by the
141
* ratio of <code>(max - min) / (constraining dim)</code>.</p>
143
* <p>Override this if you want to use a different value mapping
146
* @method _offsetToValue
147
* @param offset { Number } X or Y pixel offset
148
* @return { mixed } Value corresponding to the provided pixel offset
151
_offsetToValue: function ( offset ) {
153
var value = round( offset * this._factor ) + this.get( MIN );
155
Y.log("Offset: " + offset + " => Value: " + value, "info", "slider");
156
return round( this._nearestValue( value ) );
160
* Converts a value into a pixel offset for use in positioning
161
* the thumb according to the reverse of the
162
* <code>_offsetToValue( xy )</code> operation.
164
* @method _valueToOffset
165
* @param val { Number } The value to map to pixel X or Y position
166
* @return { Number } The pixel offset
169
_valueToOffset: function ( value ) {
170
var offset = round( ( value - this.get( MIN ) ) / this._factor );
172
Y.log("Value: " + value + " => Offset: " + offset, "info", "slider");
177
* Returns the current value. Override this if you want to introduce
178
* output formatting. Otherwise equivalent to slider.get( "value" );
183
getValue: function () {
184
return this.get( VALUE );
188
* Updates the current value. Override this if you want to introduce
189
* input value parsing or preprocessing. Otherwise equivalent to
190
* slider.set( "value", v );
193
* @param val {Number} The new value
197
setValue: function ( val ) {
198
return this.set( VALUE, val );
202
* Update position according to new min value. If the new min results
203
* in the current value being out of range, the value is set to the
204
* closer of min or max.
206
* @method _afterMinChange
207
* @param e { EventFacade } The <code>min</code> attribute change event.
210
_afterMinChange: function ( e ) {
213
this._syncThumbPosition();
217
* Update position according to new max value. If the new max results
218
* in the current value being out of range, the value is set to the
219
* closer of min or max.
221
* @method _afterMaxChange
222
* @param e { EventFacade } The <code>max</code> attribute change event.
225
_afterMaxChange: function ( e ) {
228
this._syncThumbPosition();
232
* Verifies that the current value is within the min - max range. If
233
* not, value is set to either min or max, depending on which is
236
* @method _verifyValue
239
_verifyValue: function () {
240
var value = this.get( VALUE ),
241
nearest = this._nearestValue( value );
243
if ( value !== nearest ) {
244
// @TODO Can/should valueChange, minChange, etc be queued
245
// events? To make dd.set( 'min', n ); execute after minChange
246
// subscribers before on/after valueChange subscribers.
247
this.set( VALUE, nearest );
252
* Propagate change to the thumb position unless the change originated
253
* from the thumbMove event.
255
* @method _afterValueChange
256
* @param e { EventFacade } The <code>valueChange</code> event.
259
_afterValueChange: function ( e ) {
260
if ( !e.positioned ) {
261
Y.log("Positioning thumb after set('value',x)","info","slider");
262
this._setPosition( e.newVal );
267
* Positions the thumb in accordance with the translated value.
269
* @method _setPosition
272
_setPosition: function ( value ) {
273
this._uiMoveThumb( this._valueToOffset( value ) );
277
* Validates new values assigned to <code>min</code> attribute. Numbers
278
* are acceptable. Override this to enforce different rules.
280
* @method _validateNewMin
281
* @param value { mixed } Value assigned to <code>min</code> attribute.
282
* @return { Boolean } True for numbers. False otherwise.
285
_validateNewMin: function ( value ) {
286
return Y.Lang.isNumber( value );
290
* Validates new values assigned to <code>max</code> attribute. Numbers
291
* are acceptable. Override this to enforce different rules.
293
* @method _validateNewMax
294
* @param value { mixed } Value assigned to <code>max</code> attribute.
295
* @return { Boolean } True for numbers. False otherwise.
298
_validateNewMax: function ( value ) {
299
return Y.Lang.isNumber( value );
303
* Restricts new values assigned to <code>value</code> attribute to be
304
* between the configured <code>min</code> and <code>max</code>.
305
* Rounds to nearest integer value.
307
* @method _setNewValue
308
* @param value { Number } Value assigned to <code>value</code> attribute
309
* @return { Number } Normalized and constrained value
312
_setNewValue: function ( value ) {
313
return round( this._nearestValue( value ) );
317
* Returns the nearest valid value to the value input. If the provided
318
* value is outside the min - max range, accounting for min > max
319
* scenarios, the nearest of either min or max is returned. Otherwise,
320
* the provided value is returned.
322
* @method _nearestValue
323
* @param value { mixed } Value to test against current min - max range
324
* @return { Number } Current min, max, or value if within range
327
_nearestValue: function ( value ) {
328
var min = this.get( MIN ),
329
max = this.get( MAX ),
332
// Account for reverse value range (min > max)
333
tmp = ( max > min ) ? max : min;
334
min = ( max > min ) ? min : max;
337
return ( value < min ) ?
347
* Attributes that will be added onto host class.
356
* The value associated with the farthest top, left position of the
357
* rail. Can be greater than the configured <code>max</code> if you
358
* want values to increase from right-to-left or bottom-to-top.
366
validator: '_validateNewMin'
370
* The value associated with the farthest bottom, right position of
371
* the rail. Can be less than the configured <code>min</code> if
372
* you want values to increase from right-to-left or bottom-to-top.
380
validator: '_validateNewMax'
384
* The value associated with the thumb's current position on the
385
* rail. Defaults to the value inferred from the thumb's current
386
* position. Specifying value in the constructor will move the
387
* thumb to the position that corresponds to the supplied value.
391
* @default (inferred from current thumb position)
395
setter: '_setNewValue'
401
}, '3.4.1' ,{requires:['slider-base']});