1 /*

     2 YUI 3.10.3 (build 2fb5187)

     3 Copyright 2013 Yahoo! Inc. All rights reserved.

     4 Licensed under the BSD License.

     5 http://yuilibrary.com/license/

     6 */

     7 

     8 YUI.add('slider-value-range', function (Y, NAME) {

     9 

    10 /**

    11  * Adds value support for Slider as a range of integers between a configured

    12  * minimum and maximum value.  For use with <code>Y.Base.build(..)</code> to

    13  * add the plumbing to <code>Y.SliderBase</code>.

    14  *

    15  * @module slider

    16  * @submodule slider-value-range

    17  */

    18 

    19 // Constants for compression or performance

    20 var MIN       = 'min',

    21     MAX       = 'max',

    22     VALUE     = 'value',

    23 //     MINORSTEP = 'minorStep',

    24 //     MAJORSTEP = 'majorStep',

    25 

    26     round = Math.round;

    27 

    28 /**

    29  * One class of value algorithm that can be built onto SliderBase.  By default,

    30  * values range between 0 and 100, but you can configure these on the

    31  * built Slider class by setting the <code>min</code> and <code>max</code>

    32  * configurations.  Set the initial value (will cause the thumb to move to the

    33  * appropriate location on the rail) in configuration as well if appropriate.

    34  *

    35  * @class SliderValueRange

    36  */

    37 function SliderValueRange() {

    38     this._initSliderValueRange();

    39 }

    40 

    41 Y.SliderValueRange = Y.mix( SliderValueRange, {

    42 

    43     // Prototype properties and methods that will be added onto host class

    44     prototype: {

    45 

    46         /**

    47          * Factor used to translate value -> position -> value.

    48          *

    49          * @property _factor

    50          * @type {Number}

    51          * @protected

    52          */

    53         _factor: 1,

    54 

    55         /**

    56          * Stub for construction logic.  Override if extending this class and

    57          * you need to set something up during the initializer phase.

    58          *

    59          * @method _initSliderValueRange

    60          * @protected

    61          */

    62         _initSliderValueRange: function () {},

    63 

    64         /**

    65          * Override of stub method in SliderBase that is called at the end of

    66          * its bindUI stage of render().  Subscribes to internal events to

    67          * trigger UI and related state updates.

    68          *

    69          * @method _bindValueLogic

    70          * @protected

    71          */

    72         _bindValueLogic: function () {

    73             this.after( {

    74                 minChange  : this._afterMinChange,

    75                 maxChange  : this._afterMaxChange,

    76                 valueChange: this._afterValueChange

    77             } );

    78         },

    79 

    80         /**

    81          * Move the thumb to appropriate position if necessary.  Also resets

    82          * the cached offsets and recalculates the conversion factor to

    83          * translate position to value.

    84          *

    85          * @method _syncThumbPosition

    86          * @protected

    87          */

    88         _syncThumbPosition: function () {

    89             this._calculateFactor();

    90 

    91             this._setPosition( this.get( VALUE ) );

    92         },

    93 

    94         /**

    95          * Calculates and caches

    96          * (range between max and min) / (rail length)

    97          * for fast runtime calculation of position -> value.

    98          *

    99          * @method _calculateFactor

   100          * @protected

   101          */

   102         _calculateFactor: function () {

   103             var length    = this.get( 'length' ),

   104                 thumbSize = this.thumb.getStyle( this._key.dim ),

   105                 min       = this.get( MIN ),

   106                 max       = this.get( MAX );

   107 

   108             // The default thumb width is based on Sam skin's thumb dimension.

   109             // This attempts to allow for rendering off-DOM, then attaching

   110             // without the need to call syncUI().  It is still recommended

   111             // to call syncUI() in these cases though, just to be sure.

   112             length = parseFloat( length ) || 150;

   113             thumbSize = parseFloat( thumbSize ) || 15;

   114 

   115             this._factor = ( max - min ) / ( length - thumbSize );

   116 

   117             Y.log("Calculating factor(~" + this._factor.toFixed(3) + " = (max(" + max + ") - min(" + min + ")) / (length(" + length + ") - thumb size(" + thumbSize + "))","info","slider");

   118         },

   119 

   120         /**

   121          * Dispatch the new position of the thumb into the value setting

   122          * operations.

   123          *

   124          * @method _defThumbMoveFn

   125          * @param e { EventFacade } The host's thumbMove event

   126          * @protected

   127          */

   128         _defThumbMoveFn: function ( e ) {

   129             // To prevent set('value', x) from looping back around

   130             if (e.source !== 'set') {

   131                 this.set(VALUE, this._offsetToValue(e.offset));

   132             }

   133         },

   134 

   135         /**

   136          * <p>Converts a pixel position into a value.  Calculates current

   137          * thumb offset from the leading edge of the rail multiplied by the

   138          * ratio of <code>(max - min) / (constraining dim)</code>.</p>

   139          *

   140          * <p>Override this if you want to use a different value mapping

   141          * algorithm.</p>

   142          *

   143          * @method _offsetToValue

   144          * @param offset { Number } X or Y pixel offset

   145          * @return { mixed } Value corresponding to the provided pixel offset

   146          * @protected

   147          */

   148         _offsetToValue: function ( offset ) {

   149 

   150             var value = round( offset * this._factor ) + this.get( MIN );

   151 

   152             Y.log("Offset: " + offset + " => Value: " + value, "info", "slider");

   153             return round( this._nearestValue( value ) );

   154         },

   155 

   156         /**

   157          * Converts a value into a pixel offset for use in positioning

   158          * the thumb according to the reverse of the

   159          * <code>_offsetToValue( xy )</code> operation.

   160          *

   161          * @method _valueToOffset

   162          * @param val { Number } The value to map to pixel X or Y position

   163          * @return { Number } The pixel offset 

   164          * @protected

   165          */

   166         _valueToOffset: function ( value ) {

   167             var offset = round( ( value - this.get( MIN ) ) / this._factor );

   168 

   169             Y.log("Value: " + value + " => Offset: " + offset, "info", "slider");

   170             return offset;

   171         },

   172 

   173         /**

   174          * Returns the current value.  Override this if you want to introduce

   175          * output formatting. Otherwise equivalent to slider.get( "value" );

   176          *

   177          * @method getValue

   178          * @return {Number}

   179          */

   180         getValue: function () {

   181             return this.get( VALUE );

   182         },

   183 

   184         /**

   185          * Updates the current value.  Override this if you want to introduce

   186          * input value parsing or preprocessing.  Otherwise equivalent to

   187          * slider.set( "value", v );

   188          *

   189          * @method setValue

   190          * @param val {Number} The new value

   191          * @return {Slider}

   192          * @chainable

   193          */

   194         setValue: function ( val ) {

   195             return this.set( VALUE, val );

   196         },

   197 

   198         /**

   199          * Update position according to new min value.  If the new min results

   200          * in the current value being out of range, the value is set to the

   201          * closer of min or max.

   202          *

   203          * @method _afterMinChange

   204          * @param e { EventFacade } The <code>min</code> attribute change event.

   205          * @protected

   206          */

   207         _afterMinChange: function ( e ) {

   208             this._verifyValue();

   209 

   210             this._syncThumbPosition();

   211         },

   212 

   213         /**

   214          * Update position according to new max value.  If the new max results

   215          * in the current value being out of range, the value is set to the

   216          * closer of min or max.

   217          *

   218          * @method _afterMaxChange

   219          * @param e { EventFacade } The <code>max</code> attribute change event.

   220          * @protected

   221          */

   222         _afterMaxChange: function ( e ) {

   223             this._verifyValue();

   224 

   225             this._syncThumbPosition();

   226         },

   227 

   228         /**

   229          * Verifies that the current value is within the min - max range.  If

   230          * not, value is set to either min or max, depending on which is

   231          * closer.

   232          *

   233          * @method _verifyValue

   234          * @protected

   235          */

   236         _verifyValue: function () {

   237             var value   = this.get( VALUE ),

   238                 nearest = this._nearestValue( value );

   239 

   240             if ( value !== nearest ) {

   241                 // @TODO Can/should valueChange, minChange, etc be queued

   242                 // events? To make dd.set( 'min', n ); execute after minChange

   243                 // subscribers before on/after valueChange subscribers.

   244                 this.set( VALUE, nearest );

   245             }

   246         },

   247 

   248         /**

   249          * Propagate change to the thumb position unless the change originated

   250          * from the thumbMove event.

   251          *

   252          * @method _afterValueChange

   253          * @param e { EventFacade } The <code>valueChange</code> event.

   254          * @protected

   255          */

   256         _afterValueChange: function ( e ) {

   257             var val = e.newVal;

   258             Y.log("Positioning thumb after set('value',x)","info","slider");

   259             this._setPosition( val, { source: 'set' } );

   260         },

   261 

   262         /**

   263          * Positions the thumb and its ARIA attributes in accordance with the 

   264          * translated value.

   265          *

   266          * @method _setPosition

   267          * @param value {Number} Value to translate to a pixel position

   268          * @param [options] {Object} Details object to pass to `_uiMoveThumb`

   269          * @protected

   270          */

   271         _setPosition: function ( value, options ) {

   272             this._uiMoveThumb( this._valueToOffset( value ), options );

   273             this.thumb.set('aria-valuenow', value);

   274             this.thumb.set('aria-valuetext', value);

   275         },

   276 

   277         /**

   278          * Validates new values assigned to <code>min</code> attribute.  Numbers

   279          * are acceptable.  Override this to enforce different rules.

   280          *

   281          * @method _validateNewMin

   282          * @param value {Any} Value assigned to <code>min</code> attribute.

   283          * @return {Boolean} True for numbers.  False otherwise.

   284          * @protected

   285          */

   286         _validateNewMin: function ( value ) {

   287             return Y.Lang.isNumber( value );

   288         },

   289 

   290         /**

   291          * Validates new values assigned to <code>max</code> attribute.  Numbers

   292          * are acceptable.  Override this to enforce different rules.

   293          *

   294          * @method _validateNewMax

   295          * @param value { mixed } Value assigned to <code>max</code> attribute.

   296          * @return { Boolean } True for numbers.  False otherwise.

   297          * @protected

   298          */

   299         _validateNewMax: function ( value ) {

   300             return Y.Lang.isNumber( value );

   301         },

   302 

   303         /**

   304          * Restricts new values assigned to <code>value</code> attribute to be

   305          * between the configured <code>min</code> and <code>max</code>.

   306          * Rounds to nearest integer value.

   307          *

   308          * @method _setNewValue

   309          * @param value { Number } Value assigned to <code>value</code> attribute

   310          * @return { Number } Normalized and constrained value

   311          * @protected

   312          */

   313         _setNewValue: function ( value ) {

   314             return round( this._nearestValue( value ) );

   315         },

   316 

   317         /**

   318          * Returns the nearest valid value to the value input.  If the provided

   319          * value is outside the min - max range, accounting for min > max

   320          * scenarios, the nearest of either min or max is returned.  Otherwise,

   321          * the provided value is returned.

   322          *

   323          * @method _nearestValue

   324          * @param value { mixed } Value to test against current min - max range

   325          * @return { Number } Current min, max, or value if within range

   326          * @protected

   327          */

   328         _nearestValue: function ( value ) {

   329             var min = this.get( MIN ),

   330                 max = this.get( MAX ),

   331                 tmp;

   332 

   333             // Account for reverse value range (min > max)

   334             tmp = ( max > min ) ? max : min;

   335             min = ( max > min ) ? min : max;

   336             max = tmp;

   337 

   338             return ( value < min ) ?

   339                     min :

   340                     ( value > max ) ?

   341                         max :

   342                         value;

   343         }

   344 

   345     },

   346 

   347     /**

   348      * Attributes that will be added onto host class.

   349      *

   350      * @property ATTRS

   351      * @type {Object}

   352      * @static

   353      * @protected

   354      */

   355     ATTRS: {

   356         /**

   357          * The value associated with the farthest top, left position of the

   358          * rail.  Can be greater than the configured <code>max</code> if you

   359          * want values to increase from right-to-left or bottom-to-top.

   360          *

   361          * @attribute min

   362          * @type { Number }

   363          * @default 0

   364          */

   365         min: {

   366             value    : 0,

   367             validator: '_validateNewMin'

   368         },

   369 

   370         /**

   371          * The value associated with the farthest bottom, right position of

   372          * the rail.  Can be less than the configured <code>min</code> if

   373          * you want values to increase from right-to-left or bottom-to-top.

   374          *

   375          * @attribute max

   376          * @type { Number }

   377          * @default 100

   378          */

   379         max: {

   380             value    : 100,

   381             validator: '_validateNewMax'

   382         },

   383         

   384         /**

   385          * amount to increment/decrement the Slider value

   386          * when the arrow up/down/left/right keys are pressed

   387          *

   388          * @attribute minorStep

   389          * @type {Number}

   390          * @default 1

   391          */

   392         minorStep : {

   393             value: 1

   394         },

   395 

   396         /**

   397          * amount to increment/decrement the Slider value

   398          * when the page up/down keys are pressed

   399          *

   400          * @attribute majorStep

   401          * @type {Number}

   402          * @default 10

   403          */

   404         majorStep : {

   405             value: 10

   406         },

   407 

   408         /**

   409          * The value associated with the thumb's current position on the

   410          * rail. Defaults to the value inferred from the thumb's current

   411          * position. Specifying value in the constructor will move the

   412          * thumb to the position that corresponds to the supplied value.

   413          *

   414          * @attribute value

   415          * @type { Number }

   416          * @default (inferred from current thumb position)

   417          */

   418         value: {

   419             value : 0,

   420             setter: '_setNewValue'

   421         }

   422     }

   423 }, true );

   424 

   425 

   426 }, '3.10.3', {"requires": ["slider-base"]});