src/widgets/Slider.js

   1 /*!
   2  * Ext JS Library 3.1.1
   3  * Copyright(c) 2006-2010 Ext JS, LLC
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**\r
   8  * @class Ext.Slider\r
   9  * @extends Ext.BoxComponent\r
  10  * Slider which supports vertical or horizontal orientation, keyboard adjustments,\r
  11  * configurable snapping, axis clicking and animation. Can be added as an item to\r
  12  * any container. Example usage:\r
  13 <pre><code>\r
  14 new Ext.Slider({\r
  15     renderTo: Ext.getBody(),\r
  16     width: 200,\r
  17     value: 50,\r
  18     increment: 10,\r
  19     minValue: 0,\r
  20     maxValue: 100\r
  21 });\r
  22 </code></pre>\r
  23  */\r
  24 Ext.Slider = Ext.extend(Ext.BoxComponent, {\r
  25     /**\r
  26      * @cfg {Number} value The value to initialize the slider with. Defaults to minValue.\r
  27      */\r
  28     /**\r
  29      * @cfg {Boolean} vertical Orient the Slider vertically rather than horizontally, defaults to false.\r
  30      */\r
  31     vertical: false,\r
  32     /**\r
  33      * @cfg {Number} minValue The minimum value for the Slider. Defaults to 0.\r
  34      */\r
  35     minValue: 0,\r
  36     /**\r
  37      * @cfg {Number} maxValue The maximum value for the Slider. Defaults to 100.\r
  38      */\r
  39     maxValue: 100,\r
  40     /**\r
  41      * @cfg {Number/Boolean} decimalPrecision.\r
  42      * <p>The number of decimal places to which to round the Slider's value. Defaults to 0.</p>\r
  43      * <p>To disable rounding, configure as <tt><b>false</b></tt>.</p>\r
  44      */\r
  45     decimalPrecision: 0,\r
  46     /**\r
  47      * @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.\r
  48      */\r
  49     keyIncrement: 1,\r
  50     /**\r
  51      * @cfg {Number} increment How many units to change the slider when adjusting by drag and drop. Use this option to enable 'snapping'.\r
  52      */\r
  53     increment: 0,\r
  54     // private\r
  55     clickRange: [5,15],\r
  56     /**\r
  57      * @cfg {Boolean} clickToChange Determines whether or not clicking on the Slider axis will change the slider. Defaults to true\r
  58      */\r
  59     clickToChange : true,\r
  60     /**\r
  61      * @cfg {Boolean} animate Turn on or off animation. Defaults to true\r
  62      */\r
  63     animate: true,\r
  64 \r
  65     /**\r
  66      * True while the thumb is in a drag operation\r
  67      * @type boolean\r
  68      */\r
  69     dragging: false,\r
  70 \r
  71     // private override\r
  72     initComponent : function(){\r
  73         if(!Ext.isDefined(this.value)){\r
  74             this.value = this.minValue;\r
  75         }\r
  76         Ext.Slider.superclass.initComponent.call(this);\r
  77         this.keyIncrement = Math.max(this.increment, this.keyIncrement);\r
  78         this.addEvents(\r
  79             /**\r
  80              * @event beforechange\r
  81              * Fires before the slider value is changed. By returning false from an event handler,\r
  82              * you can cancel the event and prevent the slider from changing.\r
  83              * @param {Ext.Slider} slider The slider\r
  84              * @param {Number} newValue The new value which the slider is being changed to.\r
  85              * @param {Number} oldValue The old value which the slider was previously.\r
  86              */\r
  87             'beforechange',\r
  88             /**\r
  89              * @event change\r
  90              * Fires when the slider value is changed.\r
  91              * @param {Ext.Slider} slider The slider\r
  92              * @param {Number} newValue The new value which the slider has been changed to.\r
  93              */\r
  94             'change',\r
  95             /**\r
  96              * @event changecomplete\r
  97              * Fires when the slider value is changed by the user and any drag operations have completed.\r
  98              * @param {Ext.Slider} slider The slider\r
  99              * @param {Number} newValue The new value which the slider has been changed to.\r
 100              */\r
 101             'changecomplete',\r
 102             /**\r
 103              * @event dragstart\r
 104              * Fires after a drag operation has started.\r
 105              * @param {Ext.Slider} slider The slider\r
 106              * @param {Ext.EventObject} e The event fired from Ext.dd.DragTracker\r
 107              */\r
 108             'dragstart',\r
 109             /**\r
 110              * @event drag\r
 111              * Fires continuously during the drag operation while the mouse is moving.\r
 112              * @param {Ext.Slider} slider The slider\r
 113              * @param {Ext.EventObject} e The event fired from Ext.dd.DragTracker\r
 114              */\r
 115             'drag',\r
 116             /**\r
 117              * @event dragend\r
 118              * Fires after the drag operation has completed.\r
 119              * @param {Ext.Slider} slider The slider\r
 120              * @param {Ext.EventObject} e The event fired from Ext.dd.DragTracker\r
 121              */\r
 122             'dragend'\r
 123         );\r
 124 \r
 125         if(this.vertical){\r
 126             Ext.apply(this, Ext.Slider.Vertical);\r
 127         }\r
 128     },\r
 129 \r
 130     // private override\r
 131     onRender : function(){\r
 132         this.autoEl = {\r
 133             cls: 'x-slider ' + (this.vertical ? 'x-slider-vert' : 'x-slider-horz'),\r
 134             cn:{cls:'x-slider-end',cn:{cls:'x-slider-inner',cn:[{cls:'x-slider-thumb'},{tag:'a', cls:'x-slider-focus', href:"#", tabIndex: '-1', hidefocus:'on'}]}}\r
 135         };\r
 136         Ext.Slider.superclass.onRender.apply(this, arguments);\r
 137         this.endEl = this.el.first();\r
 138         this.innerEl = this.endEl.first();\r
 139         this.thumb = this.innerEl.first();\r
 140         this.halfThumb = (this.vertical ? this.thumb.getHeight() : this.thumb.getWidth())/2;\r
 141         this.focusEl = this.thumb.next();\r
 142         this.initEvents();\r
 143     },\r
 144 \r
 145     // private override\r
 146     initEvents : function(){\r
 147         this.thumb.addClassOnOver('x-slider-thumb-over');\r
 148         this.mon(this.el, {\r
 149             scope: this,\r
 150             mousedown: this.onMouseDown,\r
 151             keydown: this.onKeyDown\r
 152         });\r
 153 \r
 154         this.focusEl.swallowEvent("click", true);\r
 155 \r
 156         this.tracker = new Ext.dd.DragTracker({\r
 157             onBeforeStart: this.onBeforeDragStart.createDelegate(this),\r
 158             onStart: this.onDragStart.createDelegate(this),\r
 159             onDrag: this.onDrag.createDelegate(this),\r
 160             onEnd: this.onDragEnd.createDelegate(this),\r
 161             tolerance: 3,\r
 162             autoStart: 300\r
 163         });\r
 164         this.tracker.initEl(this.thumb);\r
 165     },\r
 166 \r
 167     // private override\r
 168     onMouseDown : function(e){\r
 169         if(this.disabled){\r
 170             return;\r
 171         }\r
 172         if(this.clickToChange && e.target != this.thumb.dom){\r
 173             var local = this.innerEl.translatePoints(e.getXY());\r
 174             this.onClickChange(local);\r
 175         }\r
 176         this.focus();\r
 177     },\r
 178 \r
 179     // private\r
 180     onClickChange : function(local){\r
 181         if(local.top > this.clickRange[0] && local.top < this.clickRange[1]){\r
 182             this.setValue(Ext.util.Format.round(this.reverseValue(local.left), this.decimalPrecision), undefined, true);\r
 183         }\r
 184     },\r
 185 \r
 186     // private\r
 187     onKeyDown : function(e){\r
 188         if(this.disabled){e.preventDefault();return;}\r
 189         var k = e.getKey();\r
 190         switch(k){\r
 191             case e.UP:\r
 192             case e.RIGHT:\r
 193                 e.stopEvent();\r
 194                 if(e.ctrlKey){\r
 195                     this.setValue(this.maxValue, undefined, true);\r
 196                 }else{\r
 197                     this.setValue(this.value+this.keyIncrement, undefined, true);\r
 198                 }\r
 199             break;\r
 200             case e.DOWN:\r
 201             case e.LEFT:\r
 202                 e.stopEvent();\r
 203                 if(e.ctrlKey){\r
 204                     this.setValue(this.minValue, undefined, true);\r
 205                 }else{\r
 206                     this.setValue(this.value-this.keyIncrement, undefined, true);\r
 207                 }\r
 208             break;\r
 209             default:\r
 210                 e.preventDefault();\r
 211         }\r
 212     },\r
 213 \r
 214     // private\r
 215     doSnap : function(value){\r
 216         if(!(this.increment && value)){\r
 217             return value;\r
 218         }\r
 219         var newValue = value,\r
 220             inc = this.increment,\r
 221             m = value % inc;\r
 222         if(m != 0){\r
 223             newValue -= m;\r
 224             if(m * 2 > inc){\r
 225                 newValue += inc;\r
 226             }else if(m * 2 < -inc){\r
 227                 newValue -= inc;\r
 228             }\r
 229         }\r
 230         return newValue.constrain(this.minValue,  this.maxValue);\r
 231     },\r
 232 \r
 233     // private\r
 234     afterRender : function(){\r
 235         Ext.Slider.superclass.afterRender.apply(this, arguments);\r
 236         if(this.value !== undefined){\r
 237             var v = this.normalizeValue(this.value);\r
 238             if(v !== this.value){\r
 239                 delete this.value;\r
 240                 this.setValue(v, false);\r
 241             }else{\r
 242                 this.moveThumb(this.translateValue(v), false);\r
 243             }\r
 244         }\r
 245     },\r
 246 \r
 247     // private\r
 248     getRatio : function(){\r
 249         var w = this.innerEl.getWidth(),\r
 250             v = this.maxValue - this.minValue;\r
 251         return v == 0 ? w : (w/v);\r
 252     },\r
 253 \r
 254     // private\r
 255     normalizeValue : function(v){\r
 256         v = this.doSnap(v);\r
 257         v = Ext.util.Format.round(v, this.decimalPrecision);\r
 258         v = v.constrain(this.minValue, this.maxValue);\r
 259         return v;\r
 260     },\r
 261     \r
 262     /**\r
 263      * Sets the minimum value for the slider instance. If the current value is less than the \r
 264      * minimum value, the current value will be changed.\r
 265      * @param {Number} val The new minimum value\r
 266      */\r
 267     setMinValue : function(val){\r
 268         this.minValue = val;\r
 269         this.syncThumb();\r
 270         if(this.value < val){\r
 271             this.setValue(val);\r
 272         }\r
 273     },\r
 274     \r
 275     /**\r
 276      * Sets the maximum value for the slider instance. If the current value is more than the \r
 277      * maximum value, the current value will be changed.\r
 278      * @param {Number} val The new maximum value\r
 279      */\r
 280     setMaxValue : function(val){\r
 281         this.maxValue = val;\r
 282         this.syncThumb();\r
 283         if(this.value > val){\r
 284             this.setValue(val);\r
 285         }\r
 286     },\r
 287 \r
 288     /**\r
 289      * Programmatically sets the value of the Slider. Ensures that the value is constrained within\r
 290      * the minValue and maxValue.\r
 291      * @param {Number} value The value to set the slider to. (This will be constrained within minValue and maxValue)\r
 292      * @param {Boolean} animate Turn on or off animation, defaults to true\r
 293      */\r
 294     setValue : function(v, animate, changeComplete){\r
 295         v = this.normalizeValue(v);\r
 296         if(v !== this.value && this.fireEvent('beforechange', this, v, this.value) !== false){\r
 297             this.value = v;\r
 298             this.moveThumb(this.translateValue(v), animate !== false);\r
 299             this.fireEvent('change', this, v);\r
 300             if(changeComplete){\r
 301                 this.fireEvent('changecomplete', this, v);\r
 302             }\r
 303         }\r
 304     },\r
 305 \r
 306     // private\r
 307     translateValue : function(v){\r
 308         var ratio = this.getRatio();\r
 309         return (v * ratio) - (this.minValue * ratio) - this.halfThumb;\r
 310     },\r
 311 \r
 312     reverseValue : function(pos){\r
 313         var ratio = this.getRatio();\r
 314         return (pos + (this.minValue * ratio)) / ratio;\r
 315     },\r
 316 \r
 317     // private\r
 318     moveThumb: function(v, animate){\r
 319         if(!animate || this.animate === false){\r
 320             this.thumb.setLeft(v);\r
 321         }else{\r
 322             this.thumb.shift({left: v, stopFx: true, duration:.35});\r
 323         }\r
 324     },\r
 325 \r
 326     // private\r
 327     focus : function(){\r
 328         this.focusEl.focus(10);\r
 329     },\r
 330 \r
 331     // private\r
 332     onBeforeDragStart : function(e){\r
 333         return !this.disabled;\r
 334     },\r
 335 \r
 336     // private\r
 337     onDragStart: function(e){\r
 338         this.thumb.addClass('x-slider-thumb-drag');\r
 339         this.dragging = true;\r
 340         this.dragStartValue = this.value;\r
 341         this.fireEvent('dragstart', this, e);\r
 342     },\r
 343 \r
 344     // private\r
 345     onDrag: function(e){\r
 346         var pos = this.innerEl.translatePoints(this.tracker.getXY());\r
 347         this.setValue(Ext.util.Format.round(this.reverseValue(pos.left), this.decimalPrecision), false);\r
 348         this.fireEvent('drag', this, e);\r
 349     },\r
 350 \r
 351     // private\r
 352     onDragEnd: function(e){\r
 353         this.thumb.removeClass('x-slider-thumb-drag');\r
 354         this.dragging = false;\r
 355         this.fireEvent('dragend', this, e);\r
 356         if(this.dragStartValue != this.value){\r
 357             this.fireEvent('changecomplete', this, this.value);\r
 358         }\r
 359     },\r
 360 \r
 361     // private\r
 362     onResize : function(w, h){\r
 363         this.innerEl.setWidth(w - (this.el.getPadding('l') + this.endEl.getPadding('r')));\r
 364         this.syncThumb();\r
 365         Ext.Slider.superclass.onResize.apply(this, arguments);\r
 366     },\r
 367 \r
 368     //private\r
 369     onDisable: function(){\r
 370         Ext.Slider.superclass.onDisable.call(this);\r
 371         this.thumb.addClass(this.disabledClass);\r
 372         if(Ext.isIE){\r
 373             //IE breaks when using overflow visible and opacity other than 1.\r
 374             //Create a place holder for the thumb and display it.\r
 375             var xy = this.thumb.getXY();\r
 376             this.thumb.hide();\r
 377             this.innerEl.addClass(this.disabledClass).dom.disabled = true;\r
 378             if (!this.thumbHolder){\r
 379                 this.thumbHolder = this.endEl.createChild({cls: 'x-slider-thumb ' + this.disabledClass});\r
 380             }\r
 381             this.thumbHolder.show().setXY(xy);\r
 382         }\r
 383     },\r
 384 \r
 385     //private\r
 386     onEnable: function(){\r
 387         Ext.Slider.superclass.onEnable.call(this);\r
 388         this.thumb.removeClass(this.disabledClass);\r
 389         if(Ext.isIE){\r
 390             this.innerEl.removeClass(this.disabledClass).dom.disabled = false;\r
 391             if(this.thumbHolder){\r
 392                 this.thumbHolder.hide();\r
 393             }\r
 394             this.thumb.show();\r
 395             this.syncThumb();\r
 396         }\r
 397     },\r
 398 \r
 399     /**\r
 400      * Synchronizes the thumb position to the proper proportion of the total component width based\r
 401      * on the current slider {@link #value}.  This will be called automatically when the Slider\r
 402      * is resized by a layout, but if it is rendered auto width, this method can be called from\r
 403      * another resize handler to sync the Slider if necessary.\r
 404      */\r
 405     syncThumb : function(){\r
 406         if(this.rendered){\r
 407             this.moveThumb(this.translateValue(this.value));\r
 408         }\r
 409     },\r
 410 \r
 411     /**\r
 412      * Returns the current value of the slider\r
 413      * @return {Number} The current value of the slider\r
 414      */\r
 415     getValue : function(){\r
 416         return this.value;\r
 417     },\r
 418 \r
 419     // private\r
 420     beforeDestroy : function(){\r
 421         Ext.destroyMembers(this, 'endEl', 'innerEl', 'thumb', 'halfThumb', 'focusEl', 'tracker', 'thumbHolder');\r
 422         Ext.Slider.superclass.beforeDestroy.call(this);\r
 423     }\r
 424 });\r
 425 Ext.reg('slider', Ext.Slider);\r
 426 \r
 427 // private class to support vertical sliders\r
 428 Ext.Slider.Vertical = {\r
 429     onResize : function(w, h){\r
 430         this.innerEl.setHeight(h - (this.el.getPadding('t') + this.endEl.getPadding('b')));\r
 431         this.syncThumb();\r
 432     },\r
 433 \r
 434     getRatio : function(){\r
 435         var h = this.innerEl.getHeight(),\r
 436             v = this.maxValue - this.minValue;\r
 437         return h/v;\r
 438     },\r
 439 \r
 440     moveThumb: function(v, animate){\r
 441         if(!animate || this.animate === false){\r
 442             this.thumb.setBottom(v);\r
 443         }else{\r
 444             this.thumb.shift({bottom: v, stopFx: true, duration:.35});\r
 445         }\r
 446     },\r
 447 \r
 448     onDrag: function(e){\r
 449         var pos = this.innerEl.translatePoints(this.tracker.getXY()),\r
 450             bottom = this.innerEl.getHeight()-pos.top;\r
 451         this.setValue(this.minValue + Ext.util.Format.round(bottom/this.getRatio(), this.decimalPrecision), false);\r
 452         this.fireEvent('drag', this, e);\r
 453     },\r
 454 \r
 455     onClickChange : function(local){\r
 456         if(local.left > this.clickRange[0] && local.left < this.clickRange[1]){\r
 457             var bottom = this.innerEl.getHeight() - local.top;\r
 458             this.setValue(this.minValue + Ext.util.Format.round(bottom/this.getRatio(), this.decimalPrecision), undefined, true);\r
 459         }\r
 460     }\r
 461 };