X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/7a654f8d43fdb43d78b63d90528bed6e86b608cc..f562e4c6e5fac7bcb445985b99acbea4d706e6f0:/docs/source/Multi.html diff --git a/docs/source/Multi.html b/docs/source/Multi.html index 8ebcbe88..bcbcdb13 100644 --- a/docs/source/Multi.html +++ b/docs/source/Multi.html @@ -1,25 +1,38 @@ -Sencha Documentation Project
/**
- * @class Ext.slider.Multi
- * @extends Ext.form.field.Base
- * <p>Slider which supports vertical or horizontal orientation, keyboard adjustments, configurable snapping, axis
- * clicking and animation. Can be added as an item to any container. In addition,  
- * {@img Ext.slider.Multi/Ext.slider.Multi.png Ext.slider.Multi component}
- * <p>Example usage:</p>
+
+
+
+  
+  The source code
+  
+  
+  
+  
+
+
+  
/**
+ * Slider which supports vertical or horizontal orientation, keyboard adjustments, configurable snapping, axis clicking
+ * and animation. Can be added as an item to any container.
+ *
  * Sliders can be created with more than one thumb handle by passing an array of values instead of a single one:
-<pre>
-    Ext.create('Ext.slider.Multi', {
-        width: 200,
-        values: [25, 50, 75],
-        increment: 5,
-        minValue: 0,
-        maxValue: 100,
-
-        //this defaults to true, setting to false allows the thumbs to pass each other
-        {@link #constrainThumbs}: false,
-        renderTo: Ext.getBody()
-    });  
-</pre>
- * @xtype multislider
+ *
+ *     @example
+ *     Ext.create('Ext.slider.Multi', {
+ *         width: 200,
+ *         values: [25, 50, 75],
+ *         increment: 5,
+ *         minValue: 0,
+ *         maxValue: 100,
+ *
+ *         // this defaults to true, setting to false allows the thumbs to pass each other
+ *         constrainThumbs: false,
+ *         renderTo: Ext.getBody()
+ *     });
  */
 Ext.define('Ext.slider.Multi', {
     extend: 'Ext.form.field.Base',
@@ -35,11 +48,12 @@ Ext.define('Ext.slider.Multi', {
         'Ext.layout.component.field.Slider'
     ],
 
+    // note: {id} here is really {inputId}, but {cmpId} is available
     fieldSubTpl: [
-        '<div class="' + Ext.baseCSSPrefix + 'slider {fieldCls} {vertical}" aria-valuemin="{minValue}" aria-valuemax="{maxValue}" aria-valuenow="{value}" aria-valuetext="{value}">',
-            '<div class="' + Ext.baseCSSPrefix + 'slider-end" role="presentation">',
-                '<div class="' + Ext.baseCSSPrefix + 'slider-inner" role="presentation">',
-                    '<a class="' + Ext.baseCSSPrefix + 'slider-focus" href="#" tabIndex="-1" hidefocus="on" role="presentation"></a>',
+        '<div id="{id}" class="' + Ext.baseCSSPrefix + 'slider {fieldCls} {vertical}" aria-valuemin="{minValue}" aria-valuemax="{maxValue}" aria-valuenow="{value}" aria-valuetext="{value}">',
+            '<div id="{cmpId}-endEl" class="' + Ext.baseCSSPrefix + 'slider-end" role="presentation">',
+                '<div id="{cmpId}-innerEl" class="' + Ext.baseCSSPrefix + 'slider-inner" role="presentation">',
+                    '<a id="{cmpId}-focusEl" class="' + Ext.baseCSSPrefix + 'slider-focus" href="#" tabIndex="-1" hidefocus="on" role="presentation"></a>',
                 '</div>',
             '</div>',
         '</div>',
@@ -49,88 +63,101 @@ Ext.define('Ext.slider.Multi', {
         }
     ],
 
-    /**
+    /**
      * @cfg {Number} value
-     * A value with which to initialize the slider. Defaults to minValue. Setting this will only
-     * result in the creation of a single slider thumb; if you want multiple thumbs then use the
-     * {@link #values} config instead.
+     * A value with which to initialize the slider. Defaults to minValue. Setting this will only result in the creation
+     * of a single slider thumb; if you want multiple thumbs then use the {@link #values} config instead.
      */
 
-    /**
-     * @cfg {Array} values
-     * Array of Number values with which to initalize the slider. A separate slider thumb will be created for
-     * each value in this array. This will take precedence over the single {@link #value} config.
+    /**
+     * @cfg {Number[]} values
+     * Array of Number values with which to initalize the slider. A separate slider thumb will be created for each value
+     * in this array. This will take precedence over the single {@link #value} config.
      */
 
-    /**
-     * @cfg {Boolean} vertical Orient the Slider vertically rather than horizontally, defaults to false.
+    /**
+     * @cfg {Boolean} vertical
+     * Orient the Slider vertically rather than horizontally.
      */
     vertical: false,
-    /**
-     * @cfg {Number} minValue The minimum value for the Slider. Defaults to 0.
+
+    /**
+     * @cfg {Number} minValue
+     * The minimum value for the Slider.
      */
     minValue: 0,
-    /**
-     * @cfg {Number} maxValue The maximum value for the Slider. Defaults to 100.
+
+    /**
+     * @cfg {Number} maxValue
+     * The maximum value for the Slider.
      */
     maxValue: 100,
-    /**
-     * @cfg {Number/Boolean} decimalPrecision.
-     * <p>The number of decimal places to which to round the Slider's value. Defaults to 0.</p>
-     * <p>To disable rounding, configure as <tt><b>false</b></tt>.</p>
+
+    /**
+     * @cfg {Number/Boolean} decimalPrecision The number of decimal places to which to round the Slider's value.
+     *
+     * To disable rounding, configure as **false**.
      */
     decimalPrecision: 0,
-    /**
-     * @cfg {Number} keyIncrement How many units to change the Slider when adjusting with keyboard navigation. Defaults to 1. If the increment config is larger, it will be used instead.
+
+    /**
+     * @cfg {Number} keyIncrement
+     * How many units to change the Slider when adjusting with keyboard navigation. If the increment
+     * config is larger, it will be used instead.
      */
     keyIncrement: 1,
-    /**
-     * @cfg {Number} increment How many units to change the slider when adjusting by drag and drop. Use this option to enable 'snapping'.
+
+    /**
+     * @cfg {Number} increment
+     * How many units to change the slider when adjusting by drag and drop. Use this option to enable 'snapping'.
      */
     increment: 0,
 
-    /**
+    /**
      * @private
-     * @property clickRange
-     * @type Array
+     * @property {Number[]} clickRange
      * Determines whether or not a click to the slider component is considered to be a user request to change the value. Specified as an array of [top, bottom],
      * the click event's 'top' property is compared to these numbers and the click only considered a change request if it falls within them. e.g. if the 'top'
      * value of the click event is 4 or 16, the click is not considered a change request as it falls outside of the [5, 15] range
      */
     clickRange: [5,15],
 
-    /**
-     * @cfg {Boolean} clickToChange Determines whether or not clicking on the Slider axis will change the slider. Defaults to true
+    /**
+     * @cfg {Boolean} clickToChange
+     * Determines whether or not clicking on the Slider axis will change the slider.
      */
     clickToChange : true,
-    /**
-     * @cfg {Boolean} animate Turn on or off animation. Defaults to true
+
+    /**
+     * @cfg {Boolean} animate
+     * Turn on or off animation.
      */
     animate: true,
 
-    /**
-     * True while the thumb is in a drag operation
-     * @type Boolean
+    /**
+     * @property {Boolean} dragging
+     * True while the thumb is in a drag operation
      */
     dragging: false,
 
-    /**
-     * @cfg {Boolean} constrainThumbs True to disallow thumbs from overlapping one another. Defaults to true
+    /**
+     * @cfg {Boolean} constrainThumbs
+     * True to disallow thumbs from overlapping one another.
      */
     constrainThumbs: true,
 
     componentLayout: 'sliderfield',
 
-    /**
+    /**
      * @cfg {Boolean} useTips
-     * True to use an Ext.slider.Tip to display tips for the value. Defaults to <tt>true</tt>.
+     * True to use an Ext.slider.Tip to display tips for the value.
      */
     useTips : true,
 
-    /**
+    /**
      * @cfg {Function} tipText
-     * A function used to display custom text for the slider tip. Defaults to <tt>null</tt>, which will
-     * use the default on the plugin.
+     * A function used to display custom text for the slider tip. Defaults to null, which will use the default on the
+     * plugin.
      */
     tipText : null,
 
@@ -159,10 +186,9 @@ Ext.define('Ext.slider.Multi', {
         var me = this,
             tipPlug,
             hasTip;
-        
-        /**
-         * @property thumbs
-         * @type Array
+
+        /**
+         * @property {Array} thumbs
          * Array containing references to each thumb
          */
         me.thumbs = [];
@@ -170,17 +196,17 @@ Ext.define('Ext.slider.Multi', {
         me.keyIncrement = Math.max(me.increment, me.keyIncrement);
 
         me.addEvents(
-            /**
+            /**
              * @event beforechange
-             * Fires before the slider value is changed. By returning false from an event handler,
-             * you can cancel the event and prevent the slider from changing.
+             * Fires before the slider value is changed. By returning false from an event handler, you can cancel the
+             * event and prevent the slider from changing.
              * @param {Ext.slider.Multi} slider The slider
              * @param {Number} newValue The new value which the slider is being changed to.
              * @param {Number} oldValue The old value which the slider was previously.
              */
             'beforechange',
 
-            /**
+            /**
              * @event change
              * Fires when the slider value is changed.
              * @param {Ext.slider.Multi} slider The slider
@@ -189,7 +215,7 @@ Ext.define('Ext.slider.Multi', {
              */
             'change',
 
-            /**
+            /**
              * @event changecomplete
              * Fires when the slider value is changed by the user and any drag operations have completed.
              * @param {Ext.slider.Multi} slider The slider
@@ -198,7 +224,7 @@ Ext.define('Ext.slider.Multi', {
              */
             'changecomplete',
 
-            /**
+            /**
              * @event dragstart
              * Fires after a drag operation has started.
              * @param {Ext.slider.Multi} slider The slider
@@ -206,7 +232,7 @@ Ext.define('Ext.slider.Multi', {
              */
             'dragstart',
 
-            /**
+            /**
              * @event drag
              * Fires continuously during the drag operation while the mouse is moving.
              * @param {Ext.slider.Multi} slider The slider
@@ -214,7 +240,7 @@ Ext.define('Ext.slider.Multi', {
              */
             'drag',
 
-            /**
+            /**
              * @event dragend
              * Fires after the drag operation has completed.
              * @param {Ext.slider.Multi} slider The slider
@@ -245,7 +271,7 @@ Ext.define('Ext.slider.Multi', {
         }
     },
 
-    /**
+    /**
      * Creates a new thumb and adds it to the slider
      * @param {Number} value The initial value to set on the thumb. Defaults to 0
      * @return {Ext.slider.Thumb} The thumb
@@ -268,7 +294,7 @@ Ext.define('Ext.slider.Multi', {
         return thumb;
     },
 
-    /**
+    /**
      * @private
      * Moves the given thumb above all other by increasing its z-index. This is called when as drag
      * any thumb, so that the thumb that was just dragged is always at the highest z-index. This is
@@ -280,7 +306,7 @@ Ext.define('Ext.slider.Multi', {
         var thumbs = this.thumbs,
             ln = thumbs.length,
             zIndex, thumb, i;
-            
+
         for (i = 0; i < ln; i++) {
             thumb = thumbs[i];
 
@@ -307,11 +333,7 @@ Ext.define('Ext.slider.Multi', {
             value: me.value
         });
 
-        Ext.applyIf(me.renderSelectors, {
-            endEl: '.' + Ext.baseCSSPrefix + 'slider-end',
-            innerEl: '.' + Ext.baseCSSPrefix + 'slider-inner',
-            focusEl: '.' + Ext.baseCSSPrefix + 'slider-focus'
-        });
+        me.addChildEls('endEl', 'innerEl', 'focusEl');
 
         me.callParent(arguments);
 
@@ -326,7 +348,7 @@ Ext.define('Ext.slider.Multi', {
 
     },
 
-    /**
+    /**
      * Utility method to set the value of the field when the slider changes.
      * @param {Object} slider The slider object.
      * @param {Object} v The new value.
@@ -336,13 +358,13 @@ Ext.define('Ext.slider.Multi', {
         this.setValue(v, undefined, true);
     },
 
-    /**
+    /**
      * @private
      * Adds keyboard and mouse listeners on this.el. Ignores click events on the internal focus element.
      */
     initEvents : function() {
         var me = this;
-        
+
         me.mon(me.el, {
             scope    : me,
             mousedown: me.onMouseDown,
@@ -353,7 +375,7 @@ Ext.define('Ext.slider.Multi', {
         me.focusEl.swallowEvent("click", true);
     },
 
-    /**
+    /**
      * @private
      * Mousedown handler for the slider. If the clickToChange is enabled and the click was not on the draggable 'thumb',
      * this calculates the new value of the slider and tells the implementation (Horizontal or Vertical) to move the thumb
@@ -366,7 +388,7 @@ Ext.define('Ext.slider.Multi', {
             thumbs = me.thumbs,
             len = thumbs.length,
             local;
-            
+
         if (me.disabled) {
             return;
         }
@@ -383,7 +405,7 @@ Ext.define('Ext.slider.Multi', {
         me.focus();
     },
 
-    /**
+    /**
      * @private
      * Moves the thumb to the indicated position. Note that a Vertical implementation is provided in Ext.slider.Multi.Vertical.
      * Only changes the value if the click was within this.clickRange.
@@ -392,7 +414,7 @@ Ext.define('Ext.slider.Multi', {
     onClickChange : function(local) {
         var me = this,
             thumb, index;
-            
+
         if (local.top > me.clickRange[0] && local.top < me.clickRange[1]) {
             //find the nearest thumb to the click event
             thumb = me.getNearest(local, 'left');
@@ -403,7 +425,7 @@ Ext.define('Ext.slider.Multi', {
         }
     },
 
-    /**
+    /**
      * @private
      * Returns the nearest thumb to a click event, along with its distance
      * @param {Object} local Object containing top and left values from a click event
@@ -438,7 +460,7 @@ Ext.define('Ext.slider.Multi', {
         return nearest;
     },
 
-    /**
+    /**
      * @private
      * Handler for any keypresses captured by the slider. If the key is UP or RIGHT, the thumb is moved along to the right
      * by this.keyIncrement. If DOWN or LEFT it is moved left. Pressing CTRL moves the slider to the end in either direction
@@ -453,13 +475,13 @@ Ext.define('Ext.slider.Multi', {
         var me = this,
             k,
             val;
-        
+
         if(me.disabled || me.thumbs.length !== 1) {
             e.preventDefault();
             return;
         }
         k = e.getKey();
-        
+
         switch(k) {
             case e.UP:
             case e.RIGHT:
@@ -478,33 +500,6 @@ Ext.define('Ext.slider.Multi', {
         }
     },
 
-    /**
-     * @private
-     * If using snapping, this takes a desired new value and returns the closest snapped
-     * value to it
-     * @param {Number} value The unsnapped value
-     * @return {Number} The value of the nearest snap target
-     */
-    doSnap : function(value) {
-        var newValue = value,
-            inc = this.increment,
-            m;
-            
-        if (!(inc && value)) {
-            return value;
-        }
-        m = value % inc;
-        if (m !== 0) {
-            newValue -= m;
-            if (m * 2 >= inc) {
-                newValue += inc;
-            } else if (m * 2 < -inc) {
-                newValue -= inc;
-            }
-        }
-        return Ext.Number.constrain(newValue, this.minValue,  this.maxValue);
-    },
-
     // private
     afterRender : function() {
         var me = this,
@@ -513,7 +508,7 @@ Ext.define('Ext.slider.Multi', {
             len = thumbs.length,
             thumb,
             v;
-            
+
         me.callParent(arguments);
 
         for (; i < len; i++) {
@@ -531,7 +526,7 @@ Ext.define('Ext.slider.Multi', {
         }
     },
 
-    /**
+    /**
      * @private
      * Returns the ratio of pixels to mapped values. e.g. if the slider is 200px wide and maxValue - minValue is 100,
      * the ratio is 2
@@ -543,7 +538,7 @@ Ext.define('Ext.slider.Multi', {
         return v === 0 ? w : (w/v);
     },
 
-    /**
+    /**
      * @private
      * Returns a snapped, constrained value when given a desired value
      * @param {Number} value Raw number value
@@ -551,16 +546,16 @@ Ext.define('Ext.slider.Multi', {
      */
     normalizeValue : function(v) {
         var me = this;
-        
-        v = me.doSnap(v);
+
+        v = Ext.Number.snap(v, this.increment, this.minValue, this.maxValue);
         v = Ext.util.Format.round(v, me.decimalPrecision);
         v = Ext.Number.constrain(v, me.minValue, me.maxValue);
         return v;
     },
 
-    /**
-     * Sets the minimum value for the slider instance. If the current value is less than the
-     * minimum value, the current value will be changed.
+    /**
+     * Sets the minimum value for the slider instance. If the current value is less than the minimum value, the current
+     * value will be changed.
      * @param {Number} val The new minimum value
      */
     setMinValue : function(val) {
@@ -569,9 +564,11 @@ Ext.define('Ext.slider.Multi', {
             thumbs = me.thumbs,
             len = thumbs.length,
             t;
-            
+
         me.minValue = val;
-        me.inputEl.dom.setAttribute('aria-valuemin', val);
+        if (me.rendered) {
+            me.inputEl.dom.setAttribute('aria-valuemin', val);
+        }
 
         for (; i < len; ++i) {
             t = thumbs[i];
@@ -580,9 +577,9 @@ Ext.define('Ext.slider.Multi', {
         me.syncThumbs();
     },
 
-    /**
-     * Sets the maximum value for the slider instance. If the current value is more than the
-     * maximum value, the current value will be changed.
+    /**
+     * Sets the maximum value for the slider instance. If the current value is more than the maximum value, the current
+     * value will be changed.
      * @param {Number} val The new maximum value
      */
     setMaxValue : function(val) {
@@ -591,9 +588,11 @@ Ext.define('Ext.slider.Multi', {
             thumbs = me.thumbs,
             len = thumbs.length,
             t;
-            
+
         me.maxValue = val;
-        me.inputEl.dom.setAttribute('aria-valuemax', val);
+        if (me.rendered) {
+            me.inputEl.dom.setAttribute('aria-valuemax', val);
+        }
 
         for (; i < len; ++i) {
             t = thumbs[i];
@@ -602,12 +601,12 @@ Ext.define('Ext.slider.Multi', {
         me.syncThumbs();
     },
 
-    /**
-     * Programmatically sets the value of the Slider. Ensures that the value is constrained within
-     * the minValue and maxValue.
+    /**
+     * Programmatically sets the value of the Slider. Ensures that the value is constrained within the minValue and
+     * maxValue.
      * @param {Number} index Index of the thumb to move
      * @param {Number} value The value to set the slider to. (This will be constrained within minValue and maxValue)
-     * @param {Boolean} animate Turn on or off animation, defaults to true
+     * @param {Boolean} [animate=true] Turn on or off animation
      */
     setValue : function(index, value, animate, changeComplete) {
         var me = this,
@@ -636,7 +635,7 @@ Ext.define('Ext.slider.Multi', {
         }
     },
 
-    /**
+    /**
      * @private
      */
     translateValue : function(v) {
@@ -644,7 +643,7 @@ Ext.define('Ext.slider.Multi', {
         return (v * ratio) - (this.minValue * ratio) - this.halfThumb;
     },
 
-    /**
+    /**
      * @private
      * Given a pixel location along the slider, returns the mapped slider value for that pixel.
      * E.g. if we have a slider 200px wide with minValue = 100 and maxValue = 500, reverseValue(50)
@@ -671,7 +670,7 @@ Ext.define('Ext.slider.Multi', {
             thumb,
             el,
             xy;
-            
+
         me.callParent();
 
         for (; i < len; i++) {
@@ -705,7 +704,7 @@ Ext.define('Ext.slider.Multi', {
             len = thumbs.length,
             thumb,
             el;
-            
+
         this.callParent();
 
         for (; i < len; i++) {
@@ -727,11 +726,10 @@ Ext.define('Ext.slider.Multi', {
         }
     },
 
-    /**
-     * Synchronizes thumbs position to the proper proportion of the total component width based
-     * on the current slider {@link #value}.  This will be called automatically when the Slider
-     * is resized by a layout, but if it is rendered auto width, this method can be called from
-     * another resize handler to sync the Slider if necessary.
+    /**
+     * Synchronizes thumbs position to the proper proportion of the total component width based on the current slider
+     * {@link #value}. This will be called automatically when the Slider is resized by a layout, but if it is rendered
+     * auto width, this method can be called from another resize handler to sync the Slider if necessary.
      */
     syncThumbs : function() {
         if (this.rendered) {
@@ -745,19 +743,19 @@ Ext.define('Ext.slider.Multi', {
         }
     },
 
-    /**
+    /**
      * Returns the current value of the slider
      * @param {Number} index The index of the thumb to return a value for
-     * @return {Number/Array} The current value of the slider at the given index, or an array of
-     * all thumb values if no index is given.
+     * @return {Number/Number[]} The current value of the slider at the given index, or an array of all thumb values if
+     * no index is given.
      */
     getValue : function(index) {
         return Ext.isNumber(index) ? this.thumbs[index].value : this.getValues();
     },
 
-    /**
+    /**
      * Returns an array of values - one for the location of each thumb
-     * @return {Array} The set of thumb values
+     * @return {Number[]} The set of thumb values
      */
     getValues: function() {
         var values = [],
@@ -791,8 +789,8 @@ Ext.define('Ext.slider.Multi', {
     // private
     beforeDestroy : function() {
         var me = this;
-        
-        Ext.destroyMembers(me.innerEl, me.endEl, me.focusEl);
+
+        Ext.destroy(me.innerEl, me.endEl, me.focusEl);
         Ext.each(me.thumbs, function(thumb) {
             Ext.destroy(thumb);
         }, me);
@@ -826,4 +824,6 @@ Ext.define('Ext.slider.Multi', {
         }
     }
 });
-
\ No newline at end of file +
+ +