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