4 * Copyright(c) 2006-2007, Ext JS, LLC.
6 * Originally Released Under LGPL - original licence link has changed is not relivant.
9 * <script type="text/javascript">
14 //Notifies Element that fx methods are available
19 * <p>A class to provide basic animation and visual effects support. <b>Note:</b> This class is automatically applied
20 * to the {@link Roo.Element} interface when included, so all effects calls should be performed via Element.
21 * Conversely, since the effects are not actually defined in Element, Roo.Fx <b>must</b> be included in order for the
22 * Element effects to work.</p><br/>
24 * <p>It is important to note that although the Fx methods and many non-Fx Element methods support "method chaining" in that
25 * they return the Element object itself as the method return value, it is not always possible to mix the two in a single
26 * method chain. The Fx methods use an internal effects queue so that each effect can be properly timed and sequenced.
27 * Non-Fx methods, on the other hand, have no such internal queueing and will always execute immediately. For this reason,
28 * while it may be possible to mix certain Fx and non-Fx method calls in a single chain, it may not always provide the
29 * expected results and should be done with care.</p><br/>
31 * <p>Motion effects support 8-way anchoring, meaning that you can choose one of 8 different anchor points on the Element
32 * that will serve as either the start or end point of the animation. Following are all of the supported anchor positions:</p>
35 ----- -----------------------------
36 tl The top left corner
37 t The center of the top edge
38 tr The top right corner
39 l The center of the left edge
40 r The center of the right edge
41 bl The bottom left corner
42 b The center of the bottom edge
43 br The bottom right corner
45 * <b>Although some Fx methods accept specific custom config parameters, the ones shown in the Config Options section
46 * below are common options that can be passed to any Fx method.</b>
47 * @cfg {Function} callback A function called when the effect is finished
48 * @cfg {Object} scope The scope of the effect function
49 * @cfg {String} easing A valid Easing value for the effect
50 * @cfg {String} afterCls A css class to apply after the effect
51 * @cfg {Number} duration The length of time (in seconds) that the effect should last
52 * @cfg {Boolean} remove Whether the Element should be removed from the DOM and destroyed after the effect finishes
53 * @cfg {Boolean} useDisplay Whether to use the <i>display</i> CSS property instead of <i>visibility</i> when hiding Elements (only applies to
54 * effects that end with the element being visually hidden, ignored otherwise)
55 * @cfg {String/Object/Function} afterStyle A style specification string, e.g. "width:100px", or an object in the form {width:"100px"}, or
56 * a function which returns such a specification that will be applied to the Element after the effect finishes
57 * @cfg {Boolean} block Whether the effect should block other effects from queueing while it runs
58 * @cfg {Boolean} concurrent Whether to allow subsequently-queued effects to run at the same time as the current effect, or to ensure that they run in sequence
59 * @cfg {Boolean} stopFx Whether subsequent effects should be stopped and removed after the current effect finishes
63 * Slides the element into view. An anchor point can be optionally passed to set the point of
64 * origin for the slide effect. This function automatically handles wrapping the element with
65 * a fixed-size container if needed. See the Fx class overview for valid anchor point options.
68 // default: slide the element in from the top
71 // custom: slide the element in from the right with a 2-second duration
72 el.slideIn('r', { duration: 2 });
74 // common config options shown with default values
80 * @param {String} anchor (optional) One of the valid Fx anchor positions (defaults to top: 't')
81 * @param {Object} options (optional) Object literal with any of the Fx config options
82 * @return {Roo.Element} The Element
84 slideIn : function(anchor, o){
85 var el = this.getFxEl();
88 el.queueFx(o, function(){
90 anchor = anchor || "t";
92 // fix display to visibility
95 // restore values after effect
96 var r = this.getFxRestore();
97 var b = this.getBox();
98 // fixed size for slide
102 var wrap = this.fxWrap(r.pos, o, "hidden");
104 var st = this.dom.style;
105 st.visibility = "visible";
106 st.position = "absolute";
108 // clear out temp styles after slide and unwrap
109 var after = function(){
110 el.fxUnwrap(wrap, r.pos, o);
112 st.height = r.height;
115 // time to calc the positions
116 var a, pt = {to: [b.x, b.y]}, bw = {to: b.width}, bh = {to: b.height};
118 switch(anchor.toLowerCase()){
120 wrap.setSize(b.width, 0);
121 st.left = st.bottom = "0";
125 wrap.setSize(0, b.height);
126 st.right = st.top = "0";
130 wrap.setSize(0, b.height);
132 st.left = st.top = "0";
133 a = {width: bw, points: pt};
136 wrap.setSize(b.width, 0);
138 st.left = st.top = "0";
139 a = {height: bh, points: pt};
143 st.right = st.bottom = "0";
144 a = {width: bw, height: bh};
148 wrap.setY(b.y+b.height);
149 st.right = st.top = "0";
150 a = {width: bw, height: bh, points: pt};
154 wrap.setXY([b.right, b.bottom]);
155 st.left = st.top = "0";
156 a = {width: bw, height: bh, points: pt};
160 wrap.setX(b.x+b.width);
161 st.left = st.bottom = "0";
162 a = {width: bw, height: bh, points: pt};
165 this.dom.style.visibility = "visible";
168 arguments.callee.anim = wrap.fxanim(a,
178 * Slides the element out of view. An anchor point can be optionally passed to set the end point
179 * for the slide effect. When the effect is completed, the element will be hidden (visibility =
180 * 'hidden') but block elements will still take up space in the document. The element must be removed
181 * from the DOM using the 'remove' config option if desired. This function automatically handles
182 * wrapping the element with a fixed-size container if needed. See the Fx class overview for valid anchor point options.
185 // default: slide the element out to the top
188 // custom: slide the element out to the right with a 2-second duration
189 el.slideOut('r', { duration: 2 });
191 // common config options shown with default values
199 * @param {String} anchor (optional) One of the valid Fx anchor positions (defaults to top: 't')
200 * @param {Object} options (optional) Object literal with any of the Fx config options
201 * @return {Roo.Element} The Element
203 slideOut : function(anchor, o){
204 var el = this.getFxEl();
207 el.queueFx(o, function(){
209 anchor = anchor || "t";
211 // restore values after effect
212 var r = this.getFxRestore();
214 var b = this.getBox();
215 // fixed size for slide
219 var wrap = this.fxWrap(r.pos, o, "visible");
221 var st = this.dom.style;
222 st.visibility = "visible";
223 st.position = "absolute";
227 var after = function(){
229 el.setDisplayed(false);
234 el.fxUnwrap(wrap, r.pos, o);
237 st.height = r.height;
242 var a, zero = {to: 0};
243 switch(anchor.toLowerCase()){
245 st.left = st.bottom = "0";
249 st.right = st.top = "0";
253 st.left = st.top = "0";
254 a = {width: zero, points: {to:[b.right, b.y]}};
257 st.left = st.top = "0";
258 a = {height: zero, points: {to:[b.x, b.bottom]}};
261 st.right = st.bottom = "0";
262 a = {width: zero, height: zero};
265 st.right = st.top = "0";
266 a = {width: zero, height: zero, points: {to:[b.x, b.bottom]}};
269 st.left = st.top = "0";
270 a = {width: zero, height: zero, points: {to:[b.x+b.width, b.bottom]}};
273 st.left = st.bottom = "0";
274 a = {width: zero, height: zero, points: {to:[b.right, b.y]}};
278 arguments.callee.anim = wrap.fxanim(a,
288 * Fades the element out while slowly expanding it in all directions. When the effect is completed, the
289 * element will be hidden (visibility = 'hidden') but block elements will still take up space in the document.
290 * The element must be removed from the DOM using the 'remove' config option if desired.
296 // common config options shown with default values
304 * @param {Object} options (optional) Object literal with any of the Fx config options
305 * @return {Roo.Element} The Element
308 var el = this.getFxEl();
311 el.queueFx(o, function(){
315 // restore values after effect
316 var r = this.getFxRestore();
317 var st = this.dom.style;
319 var after = function(){
321 el.setDisplayed(false);
328 el.setPositioning(r.pos);
330 st.height = r.height;
335 var width = this.getWidth();
336 var height = this.getHeight();
338 arguments.callee.anim = this.fxanim({
339 width : {to: this.adjustWidth(width * 2)},
340 height : {to: this.adjustHeight(height * 2)},
341 points : {by: [-(width * .5), -(height * .5)]},
343 fontSize: {to:200, unit: "%"}
354 * Blinks the element as if it was clicked and then collapses on its center (similar to switching off a television).
355 * When the effect is completed, the element will be hidden (visibility = 'hidden') but block elements will still
356 * take up space in the document. The element must be removed from the DOM using the 'remove' config option if desired.
362 // all config options shown with default values
370 * @param {Object} options (optional) Object literal with any of the Fx config options
371 * @return {Roo.Element} The Element
373 switchOff : function(o){
374 var el = this.getFxEl();
377 el.queueFx(o, function(){
381 // restore values after effect
382 var r = this.getFxRestore();
383 var st = this.dom.style;
385 var after = function(){
387 el.setDisplayed(false);
393 el.setPositioning(r.pos);
395 st.height = r.height;
400 this.fxanim({opacity:{to:0.3}}, null, null, .1, null, function(){
405 points:{by:[0, this.getHeight() * .5]}
406 }, o, 'motion', 0.3, 'easeIn', after);
414 * Highlights the Element by setting a color (applies to the background-color by default, but can be
415 * changed using the "attr" config option) and then fading back to the original color. If no original
416 * color is available, you should provide the "endColor" config option which will be cleared after the animation.
419 // default: highlight background to yellow
422 // custom: highlight foreground text to blue for 2 seconds
423 el.highlight("0000ff", { attr: 'color', duration: 2 });
425 // common config options shown with default values
426 el.highlight("ffff9c", {
427 attr: "background-color", //can be any valid CSS property (attribute) that supports a color value
428 endColor: (current color) or "ffffff",
433 * @param {String} color (optional) The highlight color. Should be a 6 char hex color without the leading # (defaults to yellow: 'ffff9c')
434 * @param {Object} options (optional) Object literal with any of the Fx config options
435 * @return {Roo.Element} The Element
437 highlight : function(color, o){
438 var el = this.getFxEl();
441 el.queueFx(o, function(){
442 color = color || "ffff9c";
443 attr = o.attr || "backgroundColor";
448 var origColor = this.getColor(attr);
449 var restoreColor = this.dom.style[attr];
450 endColor = (o.endColor || origColor) || "ffffff";
452 var after = function(){
453 el.dom.style[attr] = restoreColor;
458 a[attr] = {from: color, to: endColor};
459 arguments.callee.anim = this.fxanim(a,
469 * Shows a ripple of exploding, attenuating borders to draw attention to an Element.
472 // default: a single light blue ripple
475 // custom: 3 red ripples lasting 3 seconds total
476 el.frame("ff0000", 3, { duration: 3 });
478 // common config options shown with default values
479 el.frame("C3DAF9", 1, {
480 duration: 1 //duration of entire animation (not each individual ripple)
481 // Note: Easing is not configurable and will be ignored if included
484 * @param {String} color (optional) The color of the border. Should be a 6 char hex color without the leading # (defaults to light blue: 'C3DAF9').
485 * @param {Number} count (optional) The number of ripples to display (defaults to 1)
486 * @param {Object} options (optional) Object literal with any of the Fx config options
487 * @return {Roo.Element} The Element
489 frame : function(color, count, o){
490 var el = this.getFxEl();
493 el.queueFx(o, function(){
494 color = color || "#C3DAF9";
495 if(color.length == 6){
499 duration = o.duration || 1;
502 var b = this.getBox();
503 var animFn = function(){
504 var proxy = this.createProxy({
509 "z-index":"35000", // yee haw
510 border:"0px solid " + color
513 var scale = Roo.isBorderBox ? 2 : 1;
515 top:{from:b.y, to:b.y - 20},
516 left:{from:b.x, to:b.x - 20},
517 borderWidth:{from:0, to:10},
518 opacity:{from:1, to:0},
519 height:{from:b.height, to:(b.height + (20*scale))},
520 width:{from:b.width, to:(b.width + (20*scale))}
521 }, duration, function(){
525 animFn.defer((duration/2)*1000, this);
536 * Creates a pause before any subsequent queued effects begin. If there are
537 * no effects queued after the pause it will have no effect.
542 * @param {Number} seconds The length of time to pause (in seconds)
543 * @return {Roo.Element} The Element
545 pause : function(seconds){
546 var el = this.getFxEl();
549 el.queueFx(o, function(){
550 setTimeout(function(){
558 * Fade an element in (from transparent to opaque). The ending opacity can be specified
559 * using the "endOpacity" config option.
562 // default: fade in from opacity 0 to 100%
565 // custom: fade in from opacity 0 to 75% over 2 seconds
566 el.fadeIn({ endOpacity: .75, duration: 2});
568 // common config options shown with default values
570 endOpacity: 1, //can be any value between 0 and 1 (e.g. .5)
575 * @param {Object} options (optional) Object literal with any of the Fx config options
576 * @return {Roo.Element} The Element
578 fadeIn : function(o){
579 var el = this.getFxEl();
581 el.queueFx(o, function(){
584 this.dom.style.visibility = 'visible';
585 var to = o.endOpacity || 1;
586 arguments.callee.anim = this.fxanim({opacity:{to:to}},
587 o, null, .5, "easeOut", function(){
598 * Fade an element out (from opaque to transparent). The ending opacity can be specified
599 * using the "endOpacity" config option.
602 // default: fade out from the element's current opacity to 0
605 // custom: fade out from the element's current opacity to 25% over 2 seconds
606 el.fadeOut({ endOpacity: .25, duration: 2});
608 // common config options shown with default values
610 endOpacity: 0, //can be any value between 0 and 1 (e.g. .5)
617 * @param {Object} options (optional) Object literal with any of the Fx config options
618 * @return {Roo.Element} The Element
620 fadeOut : function(o){
621 var el = this.getFxEl();
623 el.queueFx(o, function(){
624 arguments.callee.anim = this.fxanim({opacity:{to:o.endOpacity || 0}},
625 o, null, .5, "easeOut", function(){
626 if(this.visibilityMode == Roo.Element.DISPLAY || o.useDisplay){
627 this.dom.style.display = "none";
629 this.dom.style.visibility = "hidden";
639 * Animates the transition of an element's dimensions from a starting height/width
640 * to an ending height/width.
643 // change height and width to 100x100 pixels
646 // common config options shown with default values. The height and width will default to
647 // the element's existing values if passed as null.
650 [element's height], {
655 * @param {Number} width The new width (pass undefined to keep the original width)
656 * @param {Number} height The new height (pass undefined to keep the original height)
657 * @param {Object} options (optional) Object literal with any of the Fx config options
658 * @return {Roo.Element} The Element
660 scale : function(w, h, o){
661 this.shift(Roo.apply({}, o, {
669 * Animates the transition of any combination of an element's dimensions, xy position and/or opacity.
670 * Any of these properties not specified in the config object will not be changed. This effect
671 * requires that at least one new dimension, position or opacity setting must be passed in on
672 * the config object in order for the function to have any effect.
675 // slide the element horizontally to x position 200 while changing the height and opacity
676 el.shift({ x: 200, height: 50, opacity: .8 });
678 // common config options shown with default values.
680 width: [element's width],
681 height: [element's height],
682 x: [element's x position],
683 y: [element's y position],
684 opacity: [element's opacity],
689 * @param {Object} options Object literal with any of the Fx config options
690 * @return {Roo.Element} The Element
693 var el = this.getFxEl();
695 el.queueFx(o, function(){
696 var a = {}, w = o.width, h = o.height, x = o.x, y = o.y, op = o.opacity;
698 a.width = {to: this.adjustWidth(w)};
701 a.height = {to: this.adjustHeight(h)};
703 if(x !== undefined || y !== undefined){
705 x !== undefined ? x : this.getX(),
706 y !== undefined ? y : this.getY()
709 if(op !== undefined){
710 a.opacity = {to: op};
712 if(o.xy !== undefined){
713 a.points = {to: o.xy};
715 arguments.callee.anim = this.fxanim(a,
716 o, 'motion', .35, "easeOut", function(){
724 * Slides the element while fading it out of view. An anchor point can be optionally passed to set the
725 * ending point of the effect.
728 // default: slide the element downward while fading out
731 // custom: slide the element out to the right with a 2-second duration
732 el.ghost('r', { duration: 2 });
734 // common config options shown with default values
742 * @param {String} anchor (optional) One of the valid Fx anchor positions (defaults to bottom: 'b')
743 * @param {Object} options (optional) Object literal with any of the Fx config options
744 * @return {Roo.Element} The Element
746 ghost : function(anchor, o){
747 var el = this.getFxEl();
750 el.queueFx(o, function(){
751 anchor = anchor || "b";
753 // restore values after effect
754 var r = this.getFxRestore();
755 var w = this.getWidth(),
756 h = this.getHeight();
758 var st = this.dom.style;
760 var after = function(){
762 el.setDisplayed(false);
768 el.setPositioning(r.pos);
770 st.height = r.height;
775 var a = {opacity: {to: 0}, points: {}}, pt = a.points;
776 switch(anchor.toLowerCase()){
803 arguments.callee.anim = this.fxanim(a,
813 * Ensures that all effects queued after syncFx is called on the element are
814 * run concurrently. This is the opposite of {@link #sequenceFx}.
815 * @return {Roo.Element} The Element
818 this.fxDefaults = Roo.apply(this.fxDefaults || {}, {
827 * Ensures that all effects queued after sequenceFx is called on the element are
828 * run in sequence. This is the opposite of {@link #syncFx}.
829 * @return {Roo.Element} The Element
831 sequenceFx : function(){
832 this.fxDefaults = Roo.apply(this.fxDefaults || {}, {
842 var ef = this.fxQueue[0];
849 * Returns true if the element has any effects actively running or queued, else returns false.
850 * @return {Boolean} True if element has active effects, else false
852 hasActiveFx : function(){
853 return this.fxQueue && this.fxQueue[0];
857 * Stops any running effects and clears the element's internal effects queue if it contains
858 * any additional effects that haven't started yet.
859 * @return {Roo.Element} The Element
862 if(this.hasActiveFx()){
863 var cur = this.fxQueue[0];
864 if(cur && cur.anim && cur.anim.isAnimated()){
865 this.fxQueue = [cur]; // clear out others
873 beforeFx : function(o){
874 if(this.hasActiveFx() && !o.concurrent){
885 * Returns true if the element is currently blocking so that no other effect can be queued
886 * until this effect is finished, else returns false if blocking is not set. This is commonly
887 * used to ensure that an effect initiated by a user action runs to completion prior to the
888 * same effect being restarted (e.g., firing only one effect even if the user clicks several times).
889 * @return {Boolean} True if blocking, else false
891 hasFxBlock : function(){
892 var q = this.fxQueue;
893 return q && q[0] && q[0].block;
897 queueFx : function(o, fn){
901 if(!this.hasFxBlock()){
902 Roo.applyIf(o, this.fxDefaults);
904 var run = this.beforeFx(o);
906 this.fxQueue.push(fn);
918 fxWrap : function(pos, o, vis){
920 if(!o.wrap || !(wrap = Roo.get(o.wrap))){
923 wrapXY = this.getXY();
925 var div = document.createElement("div");
926 div.style.visibility = vis;
927 wrap = Roo.get(this.dom.parentNode.insertBefore(div, this.dom));
928 wrap.setPositioning(pos);
929 if(wrap.getStyle("position") == "static"){
930 wrap.position("relative");
932 this.clearPositioning('auto');
934 wrap.dom.appendChild(this.dom);
943 fxUnwrap : function(wrap, pos, o){
944 this.clearPositioning();
945 this.setPositioning(pos);
947 wrap.dom.parentNode.insertBefore(this.dom, wrap.dom);
953 getFxRestore : function(){
954 var st = this.dom.style;
955 return {pos: this.getPositioning(), width: st.width, height : st.height};
959 afterFx : function(o){
961 this.applyStyles(o.afterStyle);
964 this.addClass(o.afterCls);
966 if(o.remove === true){
969 Roo.callback(o.callback, o.scope, [this]);
971 this.fxQueue.shift();
977 getFxEl : function(){ // support for composite element fx
978 return Roo.get(this.dom);
982 fxanim : function(args, opt, animType, defaultDur, defaultEase, cb){
983 animType = animType || 'run';
985 var anim = Roo.lib.Anim[animType](
987 (opt.duration || defaultDur) || .35,
988 (opt.easing || defaultEase) || 'easeOut',
990 Roo.callback(cb, this);
1000 Roo.Fx.resize = Roo.Fx.scale;
1002 //When included, Roo.Fx is automatically applied to Element so that all basic
1003 //effects are available directly via the Element API
1004 Roo.apply(Roo.Element.prototype, Roo.Fx);