3 * Copyright(c) 2006-2010 Sencha Inc.
5 * http://www.sencha.com/license
10 * @class Ext.slider.Thumb
12 * Represents a single thumb element on a Slider. This would not usually be created manually and would instead
13 * be created internally by an {@link Ext.slider.MultiSlider Ext.Slider}.
15 Ext.slider.Thumb = Ext.extend(Object, {
18 * True while the thumb is in a drag operation
25 * @cfg {Ext.slider.MultiSlider} slider The Slider to render to (required)
27 constructor: function(config) {
30 * @type Ext.slider.MultiSlider
31 * The slider this thumb is contained within
33 Ext.apply(this, config || {}, {
34 cls: 'x-slider-thumb',
37 * @cfg {Boolean} constrain True to constrain the thumb so that it cannot overlap its siblings
42 Ext.slider.Thumb.superclass.constructor.call(this, config);
44 if (this.slider.vertical) {
45 Ext.apply(this, Ext.slider.Thumb.Vertical);
50 * Renders the thumb into a slider
53 this.el = this.slider.innerEl.insertFirst({cls: this.cls});
59 * Enables the thumb if it is currently disabled
62 this.disabled = false;
63 this.el.removeClass(this.slider.disabledClass);
67 * Disables the thumb if it is currently enabled
71 this.el.addClass(this.slider.disabledClass);
75 * Sets up an Ext.dd.DragTracker for this thumb
77 initEvents: function() {
80 el.addClassOnOver('x-slider-thumb-over');
82 this.tracker = new Ext.dd.DragTracker({
83 onBeforeStart: this.onBeforeDragStart.createDelegate(this),
84 onStart : this.onDragStart.createDelegate(this),
85 onDrag : this.onDrag.createDelegate(this),
86 onEnd : this.onDragEnd.createDelegate(this),
91 this.tracker.initEl(el);
96 * This is tied into the internal Ext.dd.DragTracker. If the slider is currently disabled,
97 * this returns false to disable the DragTracker too.
98 * @return {Boolean} False if the slider is currently disabled
100 onBeforeDragStart : function(e) {
104 this.slider.promoteThumb(this);
111 * This is tied into the internal Ext.dd.DragTracker's onStart template method. Adds the drag CSS class
112 * to the thumb and fires the 'dragstart' event
114 onDragStart: function(e){
115 this.el.addClass('x-slider-thumb-drag');
116 this.dragging = true;
117 this.dragStartValue = this.value;
119 this.slider.fireEvent('dragstart', this.slider, e, this);
124 * This is tied into the internal Ext.dd.DragTracker's onDrag template method. This is called every time
125 * the DragTracker detects a drag movement. It updates the Slider's value using the position of the drag
127 onDrag: function(e) {
128 var slider = this.slider,
130 newValue = this.getNewValue();
132 if (this.constrain) {
133 var above = slider.thumbs[index + 1],
134 below = slider.thumbs[index - 1];
136 if (below != undefined && newValue <= below.value) newValue = below.value;
137 if (above != undefined && newValue >= above.value) newValue = above.value;
140 slider.setValue(index, newValue, false);
141 slider.fireEvent('drag', slider, e, this);
144 getNewValue: function() {
145 var slider = this.slider,
146 pos = slider.innerEl.translatePoints(this.tracker.getXY());
148 return Ext.util.Format.round(slider.reverseValue(pos.left), slider.decimalPrecision);
153 * This is tied to the internal Ext.dd.DragTracker's onEnd template method. Removes the drag CSS class and
154 * fires the 'changecomplete' event with the new value
156 onDragEnd: function(e) {
157 var slider = this.slider,
160 this.el.removeClass('x-slider-thumb-drag');
162 this.dragging = false;
163 slider.fireEvent('dragend', slider, e);
165 if (this.dragStartValue != value) {
166 slider.fireEvent('changecomplete', slider, value, this);
175 Ext.destroyMembers(this, 'tracker', 'el');
180 * @class Ext.slider.MultiSlider
181 * @extends Ext.BoxComponent
182 * Slider which supports vertical or horizontal orientation, keyboard adjustments, configurable snapping, axis clicking and animation. Can be added as an item to any container. Example usage:
185 renderTo: Ext.getBody(),
193 * Sliders can be created with more than one thumb handle by passing an array of values instead of a single one:
196 renderTo: Ext.getBody(),
198 values: [25, 50, 75],
202 //this defaults to true, setting to false allows the thumbs to pass each other
203 {@link #constrainThumbs}: false
207 Ext.slider.MultiSlider = Ext.extend(Ext.BoxComponent, {
209 * @cfg {Number} value The value to initialize the slider with. Defaults to minValue.
212 * @cfg {Boolean} vertical Orient the Slider vertically rather than horizontally, defaults to false.
216 * @cfg {Number} minValue The minimum value for the Slider. Defaults to 0.
220 * @cfg {Number} maxValue The maximum value for the Slider. Defaults to 100.
224 * @cfg {Number/Boolean} decimalPrecision.
225 * <p>The number of decimal places to which to round the Slider's value. Defaults to 0.</p>
226 * <p>To disable rounding, configure as <tt><b>false</b></tt>.</p>
230 * @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.
234 * @cfg {Number} increment How many units to change the slider when adjusting by drag and drop. Use this option to enable 'snapping'.
240 * @property clickRange
242 * 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],
243 * 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'
244 * 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
249 * @cfg {Boolean} clickToChange Determines whether or not clicking on the Slider axis will change the slider. Defaults to true
251 clickToChange : true,
253 * @cfg {Boolean} animate Turn on or off animation. Defaults to true
257 * @cfg {Boolean} constrainThumbs True to disallow thumbs from overlapping one another. Defaults to true
259 constrainThumbs: true,
263 * @property topThumbZIndex
265 * The number used internally to set the z index of the top thumb (see promoteThumb for details)
267 topThumbZIndex: 10000,
270 initComponent : function(){
271 if(!Ext.isDefined(this.value)){
272 this.value = this.minValue;
278 * Array containing references to each thumb
282 Ext.slider.MultiSlider.superclass.initComponent.call(this);
284 this.keyIncrement = Math.max(this.increment, this.keyIncrement);
287 * @event beforechange
288 * Fires before the slider value is changed. By returning false from an event handler,
289 * you can cancel the event and prevent the slider from changing.
290 * @param {Ext.slider.MultiSlider} slider The slider
291 * @param {Number} newValue The new value which the slider is being changed to.
292 * @param {Number} oldValue The old value which the slider was previously.
298 * Fires when the slider value is changed.
299 * @param {Ext.slider.MultiSlider} slider The slider
300 * @param {Number} newValue The new value which the slider has been changed to.
301 * @param {Ext.slider.Thumb} thumb The thumb that was changed
306 * @event changecomplete
307 * Fires when the slider value is changed by the user and any drag operations have completed.
308 * @param {Ext.slider.MultiSlider} slider The slider
309 * @param {Number} newValue The new value which the slider has been changed to.
310 * @param {Ext.slider.Thumb} thumb The thumb that was changed
316 * Fires after a drag operation has started.
317 * @param {Ext.slider.MultiSlider} slider The slider
318 * @param {Ext.EventObject} e The event fired from Ext.dd.DragTracker
324 * Fires continuously during the drag operation while the mouse is moving.
325 * @param {Ext.slider.MultiSlider} slider The slider
326 * @param {Ext.EventObject} e The event fired from Ext.dd.DragTracker
332 * Fires after the drag operation has completed.
333 * @param {Ext.slider.MultiSlider} slider The slider
334 * @param {Ext.EventObject} e The event fired from Ext.dd.DragTracker
342 * Array of values to initalize the thumbs with
344 if (this.values == undefined || Ext.isEmpty(this.values)) this.values = [0];
346 var values = this.values;
348 for (var i=0; i < values.length; i++) {
349 this.addThumb(values[i]);
353 Ext.apply(this, Ext.slider.Vertical);
358 * Creates a new thumb and adds it to the slider
359 * @param {Number} value The initial value to set on the thumb. Defaults to 0
361 addThumb: function(value) {
362 var thumb = new Ext.slider.Thumb({
365 index : this.thumbs.length,
366 constrain: this.constrainThumbs
368 this.thumbs.push(thumb);
370 //render the thumb now if needed
371 if (this.rendered) thumb.render();
376 * Moves the given thumb above all other by increasing its z-index. This is called when as drag
377 * any thumb, so that the thumb that was just dragged is always at the highest z-index. This is
378 * required when the thumbs are stacked on top of each other at one of the ends of the slider's
379 * range, which can result in the user not being able to move any of them.
380 * @param {Ext.slider.Thumb} topThumb The thumb to move to the top
382 promoteThumb: function(topThumb) {
383 var thumbs = this.thumbs,
386 for (var i = 0, j = thumbs.length; i < j; i++) {
389 if (thumb == topThumb) {
390 zIndex = this.topThumbZIndex;
395 thumb.el.setStyle('zIndex', zIndex);
400 onRender : function() {
402 cls: 'x-slider ' + (this.vertical ? 'x-slider-vert' : 'x-slider-horz'),
406 cls:'x-slider-inner',
407 cn : [{tag:'a', cls:'x-slider-focus', href:"#", tabIndex: '-1', hidefocus:'on'}]
412 Ext.slider.MultiSlider.superclass.onRender.apply(this, arguments);
414 this.endEl = this.el.first();
415 this.innerEl = this.endEl.first();
416 this.focusEl = this.innerEl.child('.x-slider-focus');
419 for (var i=0; i < this.thumbs.length; i++) {
420 this.thumbs[i].render();
423 //calculate the size of half a thumb
424 var thumb = this.innerEl.child('.x-slider-thumb');
425 this.halfThumb = (this.vertical ? thumb.getHeight() : thumb.getWidth()) / 2;
432 * Adds keyboard and mouse listeners on this.el. Ignores click events on the internal focus element.
433 * Creates a new DragTracker which is used to control what happens when the user drags the thumb around.
435 initEvents : function(){
438 mousedown: this.onMouseDown,
439 keydown : this.onKeyDown
442 this.focusEl.swallowEvent("click", true);
447 * Mousedown handler for the slider. If the clickToChange is enabled and the click was not on the draggable 'thumb',
448 * this calculates the new value of the slider and tells the implementation (Horizontal or Vertical) to move the thumb
449 * @param {Ext.EventObject} e The click event
451 onMouseDown : function(e){
456 //see if the click was on any of the thumbs
457 var thumbClicked = false;
458 for (var i=0; i < this.thumbs.length; i++) {
459 thumbClicked = thumbClicked || e.target == this.thumbs[i].el.dom;
462 if (this.clickToChange && !thumbClicked) {
463 var local = this.innerEl.translatePoints(e.getXY());
464 this.onClickChange(local);
471 * Moves the thumb to the indicated position. Note that a Vertical implementation is provided in Ext.slider.Vertical.
472 * Only changes the value if the click was within this.clickRange.
473 * @param {Object} local Object containing top and left values for the click event.
475 onClickChange : function(local) {
476 if (local.top > this.clickRange[0] && local.top < this.clickRange[1]) {
477 //find the nearest thumb to the click event
478 var thumb = this.getNearest(local, 'left'),
481 this.setValue(index, Ext.util.Format.round(this.reverseValue(local.left), this.decimalPrecision), undefined, true);
487 * Returns the nearest thumb to a click event, along with its distance
488 * @param {Object} local Object containing top and left values from a click event
489 * @param {String} prop The property of local to compare on. Use 'left' for horizontal sliders, 'top' for vertical ones
490 * @return {Object} The closest thumb object and its distance from the click event
492 getNearest: function(local, prop) {
493 var localValue = prop == 'top' ? this.innerEl.getHeight() - local[prop] : local[prop],
494 clickValue = this.reverseValue(localValue),
495 nearestDistance = (this.maxValue - this.minValue) + 5, //add a small fudge for the end of the slider
499 for (var i=0; i < this.thumbs.length; i++) {
500 var thumb = this.thumbs[i],
502 dist = Math.abs(value - clickValue);
504 if (Math.abs(dist <= nearestDistance)) {
507 nearestDistance = dist;
515 * Handler for any keypresses captured by the slider. If the key is UP or RIGHT, the thumb is moved along to the right
516 * by this.keyIncrement. If DOWN or LEFT it is moved left. Pressing CTRL moves the slider to the end in either direction
517 * @param {Ext.EventObject} e The Event object
519 onKeyDown : function(e){
521 * The behaviour for keyboard handling with multiple thumbs is currently undefined.
522 * There's no real sane default for it, so leave it like this until we come up
523 * with a better way of doing it.
525 if(this.disabled || this.thumbs.length !== 1){
535 val = e.ctrlKey ? this.maxValue : this.getValue(0) + this.keyIncrement;
536 this.setValue(0, val, undefined, true);
541 val = e.ctrlKey ? this.minValue : this.getValue(0) - this.keyIncrement;
542 this.setValue(0, val, undefined, true);
551 * If using snapping, this takes a desired new value and returns the closest snapped
553 * @param {Number} value The unsnapped value
554 * @return {Number} The value of the nearest snap target
556 doSnap : function(value){
557 if (!(this.increment && value)) {
560 var newValue = value,
561 inc = this.increment,
567 } else if (m * 2 < -inc) {
571 return newValue.constrain(this.minValue, this.maxValue);
575 afterRender : function(){
576 Ext.slider.MultiSlider.superclass.afterRender.apply(this, arguments);
578 for (var i=0; i < this.thumbs.length; i++) {
579 var thumb = this.thumbs[i];
581 if (thumb.value !== undefined) {
582 var v = this.normalizeValue(thumb.value);
584 if (v !== thumb.value) {
585 // delete this.value;
586 this.setValue(i, v, false);
588 this.moveThumb(i, this.translateValue(v), false);
596 * Returns the ratio of pixels to mapped values. e.g. if the slider is 200px wide and maxValue - minValue is 100,
598 * @return {Number} The ratio of pixels to mapped values
600 getRatio : function(){
601 var w = this.innerEl.getWidth(),
602 v = this.maxValue - this.minValue;
603 return v == 0 ? w : (w/v);
608 * Returns a snapped, constrained value when given a desired value
609 * @param {Number} value Raw number value
610 * @return {Number} The raw value rounded to the correct d.p. and constrained within the set max and min values
612 normalizeValue : function(v){
614 v = Ext.util.Format.round(v, this.decimalPrecision);
615 v = v.constrain(this.minValue, this.maxValue);
620 * Sets the minimum value for the slider instance. If the current value is less than the
621 * minimum value, the current value will be changed.
622 * @param {Number} val The new minimum value
624 setMinValue : function(val){
627 thumbs = this.thumbs,
633 t.value = t.value < val ? val : t.value;
639 * Sets the maximum value for the slider instance. If the current value is more than the
640 * maximum value, the current value will be changed.
641 * @param {Number} val The new maximum value
643 setMaxValue : function(val){
646 thumbs = this.thumbs,
652 t.value = t.value > val ? val : t.value;
658 * Programmatically sets the value of the Slider. Ensures that the value is constrained within
659 * the minValue and maxValue.
660 * @param {Number} index Index of the thumb to move
661 * @param {Number} value The value to set the slider to. (This will be constrained within minValue and maxValue)
662 * @param {Boolean} animate Turn on or off animation, defaults to true
664 setValue : function(index, v, animate, changeComplete) {
665 var thumb = this.thumbs[index],
668 v = this.normalizeValue(v);
670 if (v !== thumb.value && this.fireEvent('beforechange', this, v, thumb.value, thumb) !== false) {
673 this.moveThumb(index, this.translateValue(v), animate !== false);
674 this.fireEvent('change', this, v, thumb);
676 this.fireEvent('changecomplete', this, v, thumb);
685 translateValue : function(v) {
686 var ratio = this.getRatio();
687 return (v * ratio) - (this.minValue * ratio) - this.halfThumb;
692 * Given a pixel location along the slider, returns the mapped slider value for that pixel.
693 * E.g. if we have a slider 200px wide with minValue = 100 and maxValue = 500, reverseValue(50)
695 * @param {Number} pos The position along the slider to return a mapped value for
696 * @return {Number} The mapped value for the given position
698 reverseValue : function(pos){
699 var ratio = this.getRatio();
700 return (pos + (this.minValue * ratio)) / ratio;
705 * @param {Number} index Index of the thumb to move
707 moveThumb: function(index, v, animate){
708 var thumb = this.thumbs[index].el;
710 if(!animate || this.animate === false){
713 thumb.shift({left: v, stopFx: true, duration:.35});
719 this.focusEl.focus(10);
723 onResize : function(w, h){
724 var thumbs = this.thumbs,
729 * If we happen to be animating during a resize, the position of the thumb will likely be off
730 * when the animation stops. As such, just stop any animations before syncing the thumbs.
733 thumbs[i].el.stopFx();
735 // check to see if we're using an auto width
737 this.innerEl.setWidth(w - (this.el.getPadding('l') + this.endEl.getPadding('r')));
740 Ext.slider.MultiSlider.superclass.onResize.apply(this, arguments);
744 onDisable: function(){
745 Ext.slider.MultiSlider.superclass.onDisable.call(this);
747 for (var i=0; i < this.thumbs.length; i++) {
748 var thumb = this.thumbs[i],
754 //IE breaks when using overflow visible and opacity other than 1.
755 //Create a place holder for the thumb and display it.
759 this.innerEl.addClass(this.disabledClass).dom.disabled = true;
761 if (!this.thumbHolder) {
762 this.thumbHolder = this.endEl.createChild({cls: 'x-slider-thumb ' + this.disabledClass});
765 this.thumbHolder.show().setXY(xy);
771 onEnable: function(){
772 Ext.slider.MultiSlider.superclass.onEnable.call(this);
774 for (var i=0; i < this.thumbs.length; i++) {
775 var thumb = this.thumbs[i],
781 this.innerEl.removeClass(this.disabledClass).dom.disabled = false;
783 if (this.thumbHolder) this.thumbHolder.hide();
792 * Synchronizes the thumb position to the proper proportion of the total component width based
793 * on the current slider {@link #value}. This will be called automatically when the Slider
794 * is resized by a layout, but if it is rendered auto width, this method can be called from
795 * another resize handler to sync the Slider if necessary.
797 syncThumb : function() {
799 for (var i=0; i < this.thumbs.length; i++) {
800 this.moveThumb(i, this.translateValue(this.thumbs[i].value));
806 * Returns the current value of the slider
807 * @param {Number} index The index of the thumb to return a value for
808 * @return {Number} The current value of the slider
810 getValue : function(index) {
811 return this.thumbs[index].value;
815 * Returns an array of values - one for the location of each thumb
816 * @return {Array} The set of thumb values
818 getValues: function() {
821 for (var i=0; i < this.thumbs.length; i++) {
822 values.push(this.thumbs[i].value);
829 beforeDestroy : function(){
830 var thumbs = this.thumbs;
831 for(var i = 0, len = thumbs.length; i < len; ++i){
835 Ext.destroyMembers(this, 'endEl', 'innerEl', 'focusEl', 'thumbHolder');
836 Ext.slider.MultiSlider.superclass.beforeDestroy.call(this);
840 Ext.reg('multislider', Ext.slider.MultiSlider);
843 * @class Ext.slider.SingleSlider
844 * @extends Ext.slider.MultiSlider
845 * Slider which supports vertical or horizontal orientation, keyboard adjustments,
846 * configurable snapping, axis clicking and animation. Can be added as an item to
847 * any container. Example usage:
849 new Ext.slider.SingleSlider({
850 renderTo: Ext.getBody(),
858 * The class Ext.slider.SingleSlider is aliased to Ext.Slider for backwards compatibility.
860 Ext.slider.SingleSlider = Ext.extend(Ext.slider.MultiSlider, {
861 constructor: function(config) {
862 config = config || {};
864 Ext.applyIf(config, {
865 values: [config.value || 0]
868 Ext.slider.SingleSlider.superclass.constructor.call(this, config);
872 * Returns the current value of the slider
873 * @return {Number} The current value of the slider
875 getValue: function() {
876 //just returns the value of the first thumb, which should be the only one in a single slider
877 return Ext.slider.SingleSlider.superclass.getValue.call(this, 0);
881 * Programmatically sets the value of the Slider. Ensures that the value is constrained within
882 * the minValue and maxValue.
883 * @param {Number} value The value to set the slider to. (This will be constrained within minValue and maxValue)
884 * @param {Boolean} animate Turn on or off animation, defaults to true
886 setValue: function(value, animate) {
887 var args = Ext.toArray(arguments),
890 //this is to maintain backwards compatiblity for sliders with only one thunb. Usually you must pass the thumb
891 //index to setValue, but if we only have one thumb we inject the index here first if given the multi-slider
892 //signature without the required index. The index will always be 0 for a single slider
893 if (len == 1 || (len <= 3 && typeof arguments[1] != 'number')) {
897 return Ext.slider.SingleSlider.superclass.setValue.apply(this, args);
901 * Synchronizes the thumb position to the proper proportion of the total component width based
902 * on the current slider {@link #value}. This will be called automatically when the Slider
903 * is resized by a layout, but if it is rendered auto width, this method can be called from
904 * another resize handler to sync the Slider if necessary.
906 syncThumb : function() {
907 return Ext.slider.SingleSlider.superclass.syncThumb.apply(this, [0].concat(arguments));
911 getNearest : function(){
912 // Since there's only 1 thumb, it's always the nearest
913 return this.thumbs[0];
917 //backwards compatibility
918 Ext.Slider = Ext.slider.SingleSlider;
920 Ext.reg('slider', Ext.slider.SingleSlider);
922 // private class to support vertical sliders
923 Ext.slider.Vertical = {
924 onResize : function(w, h){
925 this.innerEl.setHeight(h - (this.el.getPadding('t') + this.endEl.getPadding('b')));
929 getRatio : function(){
930 var h = this.innerEl.getHeight(),
931 v = this.maxValue - this.minValue;
935 moveThumb: function(index, v, animate) {
936 var thumb = this.thumbs[index],
939 if (!animate || this.animate === false) {
942 el.shift({bottom: v, stopFx: true, duration:.35});
946 onClickChange : function(local) {
947 if (local.left > this.clickRange[0] && local.left < this.clickRange[1]) {
948 var thumb = this.getNearest(local, 'top'),
950 value = this.minValue + this.reverseValue(this.innerEl.getHeight() - local.top);
952 this.setValue(index, Ext.util.Format.round(value, this.decimalPrecision), undefined, true);
957 //private class to support vertical dragging of thumbs within a slider
958 Ext.slider.Thumb.Vertical = {
959 getNewValue: function() {
960 var slider = this.slider,
961 innerEl = slider.innerEl,
962 pos = innerEl.translatePoints(this.tracker.getXY()),
963 bottom = innerEl.getHeight() - pos.top;
965 return slider.minValue + Ext.util.Format.round(bottom / slider.getRatio(), slider.decimalPrecision);