69885e8900c555303f27962f0cb38a648fd83bb9
[jquery.git] / src / fx / fx.js
1 jQuery.fn.extend({
2
3         /**
4          * Displays each of the set of matched elements if they are hidden.
5          *
6          * @example $("p").show()
7          * @before <p style="display: none">Hello</p>
8          * @result [ <p style="display: block">Hello</p> ]
9          *
10          * @name show
11          * @type jQuery
12          * @cat Effects
13          */
14         
15         /**
16          * Show all matched elements using a graceful animation and firing an
17          * optional callback after completion.
18          *
19          * The height, width, and opacity of each of the matched elements 
20          * are changed dynamically according to the specified speed.
21          *
22          * @example $("p").show("slow");
23          *
24          * @example $("p").show("slow",function(){
25          *   alert("Animation Done.");
26          * });
27          *
28          * @name show
29          * @type jQuery
30          * @param String|Number speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
31          * @param Function callback (optional) A function to be executed whenever the animation completes.
32          * @cat Effects
33          * @see hide(String|Number,Function)
34          */
35         show: function(speed,callback){
36                 return speed ?
37                         this.animate({
38                                 height: "show", width: "show", opacity: "show"
39                         }, speed, callback) :
40                         
41                         this.filter(":hidden").each(function(){
42                                 this.style.display = this.oldblock ? this.oldblock : "";
43                                 if ( jQuery.css(this,"display") == "none" )
44                                         this.style.display = "block";
45                         }).end();
46         },
47         
48         /**
49          * Hides each of the set of matched elements if they are shown.
50          *
51          * @example $("p").hide()
52          * @before <p>Hello</p>
53          * @result [ <p style="display: none">Hello</p> ]
54          *
55          * @name hide
56          * @type jQuery
57          * @cat Effects
58          */
59         
60         /**
61          * Hide all matched elements using a graceful animation and firing an
62          * optional callback after completion.
63          *
64          * The height, width, and opacity of each of the matched elements 
65          * are changed dynamically according to the specified speed.
66          *
67          * @example $("p").hide("slow");
68          *
69          * @example $("p").hide("slow",function(){
70          *   alert("Animation Done.");
71          * });
72          *
73          * @name hide
74          * @type jQuery
75          * @param String|Number speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
76          * @param Function callback (optional) A function to be executed whenever the animation completes.
77          * @cat Effects
78          * @see show(String|Number,Function)
79          */
80         hide: function(speed,callback){
81                 return speed ?
82                         this.animate({
83                                 height: "hide", width: "hide", opacity: "hide"
84                         }, speed, callback) :
85                         
86                         this.filter(":visible").each(function(){
87                                 this.oldblock = this.oldblock || jQuery.css(this,"display");
88                                 if ( this.oldblock == "none" )
89                                         this.oldblock = "block";
90                                 this.style.display = "none";
91                         }).end();
92         },
93
94         // Save the old toggle function
95         _toggle: jQuery.fn.toggle,
96         
97         /**
98          * Toggles each of the set of matched elements. If they are shown,
99          * toggle makes them hidden. If they are hidden, toggle
100          * makes them shown.
101          *
102          * @example $("p").toggle()
103          * @before <p>Hello</p><p style="display: none">Hello Again</p>
104          * @result [ <p style="display: none">Hello</p>, <p style="display: block">Hello Again</p> ]
105          *
106          * @name toggle
107          * @type jQuery
108          * @cat Effects
109          */
110         toggle: function( fn, fn2 ){
111                 return jQuery.isFunction(fn) && jQuery.isFunction(fn2) ?
112                         this._toggle( fn, fn2 ) :
113                         fn ?
114                                 this.animate({
115                                         height: "toggle", width: "toggle", opacity: "toggle"
116                                 }, fn, fn2) :
117                                 this.each(function(){
118                                         jQuery(this)[ jQuery(this).is(":hidden") ? "show" : "hide" ]();
119                                 });
120         },
121         
122         /**
123          * Reveal all matched elements by adjusting their height and firing an
124          * optional callback after completion.
125          *
126          * Only the height is adjusted for this animation, causing all matched
127          * elements to be revealed in a "sliding" manner.
128          *
129          * @example $("p").slideDown("slow");
130          *
131          * @example $("p").slideDown("slow",function(){
132          *   alert("Animation Done.");
133          * });
134          *
135          * @name slideDown
136          * @type jQuery
137          * @param String|Number speed (optional) A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
138          * @param Function callback (optional) A function to be executed whenever the animation completes.
139          * @cat Effects
140          * @see slideUp(String|Number,Function)
141          * @see slideToggle(String|Number,Function)
142          */
143         slideDown: function(speed,callback){
144                 return this.animate({height: "show"}, speed, callback);
145         },
146         
147         /**
148          * Hide all matched elements by adjusting their height and firing an
149          * optional callback after completion.
150          *
151          * Only the height is adjusted for this animation, causing all matched
152          * elements to be hidden in a "sliding" manner.
153          *
154          * @example $("p").slideUp("slow");
155          *
156          * @example $("p").slideUp("slow",function(){
157          *   alert("Animation Done.");
158          * });
159          *
160          * @name slideUp
161          * @type jQuery
162          * @param String|Number speed (optional) A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
163          * @param Function callback (optional) A function to be executed whenever the animation completes.
164          * @cat Effects
165          * @see slideDown(String|Number,Function)
166          * @see slideToggle(String|Number,Function)
167          */
168         slideUp: function(speed,callback){
169                 return this.animate({height: "hide"}, speed, callback);
170         },
171
172         /**
173          * Toggle the visibility of all matched elements by adjusting their height and firing an
174          * optional callback after completion.
175          *
176          * Only the height is adjusted for this animation, causing all matched
177          * elements to be hidden in a "sliding" manner.
178          *
179          * @example $("p").slideToggle("slow");
180          *
181          * @example $("p").slideToggle("slow",function(){
182          *   alert("Animation Done.");
183          * });
184          *
185          * @name slideToggle
186          * @type jQuery
187          * @param String|Number speed (optional) A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
188          * @param Function callback (optional) A function to be executed whenever the animation completes.
189          * @cat Effects
190          * @see slideDown(String|Number,Function)
191          * @see slideUp(String|Number,Function)
192          */
193         slideToggle: function(speed, callback){
194                 return this.animate({height: "toggle"}, speed, callback);
195         },
196         
197         /**
198          * Fade in all matched elements by adjusting their opacity and firing an
199          * optional callback after completion.
200          *
201          * Only the opacity is adjusted for this animation, meaning that
202          * all of the matched elements should already have some form of height
203          * and width associated with them.
204          *
205          * @example $("p").fadeIn("slow");
206          *
207          * @example $("p").fadeIn("slow",function(){
208          *   alert("Animation Done.");
209          * });
210          *
211          * @name fadeIn
212          * @type jQuery
213          * @param String|Number speed (optional) A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
214          * @param Function callback (optional) A function to be executed whenever the animation completes.
215          * @cat Effects
216          * @see fadeOut(String|Number,Function)
217          * @see fadeTo(String|Number,Number,Function)
218          */
219         fadeIn: function(speed, callback){
220                 return this.animate({opacity: "show"}, speed, callback);
221         },
222         
223         /**
224          * Fade out all matched elements by adjusting their opacity and firing an
225          * optional callback after completion.
226          *
227          * Only the opacity is adjusted for this animation, meaning that
228          * all of the matched elements should already have some form of height
229          * and width associated with them.
230          *
231          * @example $("p").fadeOut("slow");
232          *
233          * @example $("p").fadeOut("slow",function(){
234          *   alert("Animation Done.");
235          * });
236          *
237          * @name fadeOut
238          * @type jQuery
239          * @param String|Number speed (optional) A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
240          * @param Function callback (optional) A function to be executed whenever the animation completes.
241          * @cat Effects
242          * @see fadeIn(String|Number,Function)
243          * @see fadeTo(String|Number,Number,Function)
244          */
245         fadeOut: function(speed, callback){
246                 return this.animate({opacity: "hide"}, speed, callback);
247         },
248         
249         /**
250          * Fade the opacity of all matched elements to a specified opacity and firing an
251          * optional callback after completion.
252          *
253          * Only the opacity is adjusted for this animation, meaning that
254          * all of the matched elements should already have some form of height
255          * and width associated with them.
256          *
257          * @example $("p").fadeTo("slow", 0.5);
258          *
259          * @example $("p").fadeTo("slow", 0.5, function(){
260          *   alert("Animation Done.");
261          * });
262          *
263          * @name fadeTo
264          * @type jQuery
265          * @param String|Number speed A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
266          * @param Number opacity The opacity to fade to (a number from 0 to 1).
267          * @param Function callback (optional) A function to be executed whenever the animation completes.
268          * @cat Effects
269          * @see fadeIn(String|Number,Function)
270          * @see fadeOut(String|Number,Function)
271          */
272         fadeTo: function(speed,to,callback){
273                 return this.animate({opacity: to}, speed, callback);
274         },
275         
276         /**
277          * A function for making your own, custom animations. The key aspect of
278          * this function is the object of style properties that will be animated,
279          * and to what end. Each key within the object represents a style property
280          * that will also be animated (for example: "height", "top", or "opacity").
281          *
282          * Note that properties should be specified using camel case
283          * eg. marginLeft instead of margin-left.
284          *
285          * The value associated with the key represents to what end the property
286          * will be animated. If a number is provided as the value, then the style
287          * property will be transitioned from its current state to that new number.
288          * Otherwise if the string "hide", "show", or "toggle" is provided, a default
289          * animation will be constructed for that property.
290          *
291          * @example $("p").animate({
292          *   height: 'toggle', opacity: 'toggle'
293          * }, "slow");
294          *
295          * @example $("p").animate({
296          *   left: 50, opacity: 'show'
297          * }, 500);
298          *
299          * @example $("p").animate({
300          *   opacity: 'show'
301          * }, "slow", "easein");
302          * @desc An example of using an 'easing' function to provide a different style of animation. This will only work if you have a plugin that provides this easing function (Only "swing" and "linear" are provided by default, with jQuery).
303          *
304          * @name animate
305          * @type jQuery
306          * @param Hash params A set of style attributes that you wish to animate, and to what end.
307          * @param String|Number speed (optional) A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).
308          * @param String easing (optional) The name of the easing effect that you want to use (e.g. "swing" or "linear"). Defaults to "swing".
309          * @param Function callback (optional) A function to be executed whenever the animation completes.
310          * @cat Effects
311          */
312         animate: function( prop, speed, easing, callback ) {
313                 return this.queue(function(){
314                         var hidden = jQuery(this).is(":hidden"),
315                                 opt = jQuery.speed(speed, easing, callback),
316                                 self = this;
317                         
318                         for ( var p in prop ) {
319                                 if ( prop[p] == "hide" && hidden || prop[p] == "show" && !hidden )
320                                         return jQuery.isFunction(opt.complete) && opt.complete.apply(this);
321
322                                 if ( p == "height" || p == "width" ) {
323                                         // Store display property
324                                         opt.display = jQuery.css(this, "display");
325
326                                         // Make sure that nothing sneaks out
327                                         opt.overflow = this.style.overflow;
328                                 }
329                         }
330
331                         if ( opt.overflow != null )
332                                 this.style.overflow = "hidden";
333
334                         this.curAnim = jQuery.extend({}, prop);
335                         
336                         jQuery.each( prop, function(name, val){
337                                 var e = new jQuery.fx( self, opt, name );
338                                 if ( val.constructor == Number )
339                                         e.custom( e.cur() || 0, val );
340                                 else
341                                         e[ val == "toggle" ? hidden ? "show" : "hide" : val ]( prop );
342                         });
343
344                         // For JS strict compliance
345                         return true;
346                 });
347         },
348         
349         /**
350          *
351          * @private
352          */
353         queue: function(type,fn){
354                 if ( !fn ) {
355                         fn = type;
356                         type = "fx";
357                 }
358         
359                 return this.each(function(){
360                         if ( !this.queue )
361                                 this.queue = {};
362         
363                         if ( !this.queue[type] )
364                                 this.queue[type] = [];
365         
366                         this.queue[type].push( fn );
367                 
368                         if ( this.queue[type].length == 1 )
369                                 fn.apply(this);
370                 });
371         },
372
373         stop: function(){
374                 var timers = jQuery.timers;
375
376                 return this.each(function(){
377                         for ( var i = 0; i < timers.length; i++ )
378                                 if ( timers[i].elem == this )
379                                         timers.splice(i--, 1);
380                 });
381         }
382
383 });
384
385 jQuery.extend({
386         
387         speed: function(speed, easing, fn) {
388                 var opt = speed && speed.constructor == Object ? speed : {
389                         complete: fn || !fn && easing || 
390                                 jQuery.isFunction( speed ) && speed,
391                         duration: speed,
392                         easing: fn && easing || easing && easing.constructor != Function && easing
393                 };
394
395                 opt.duration = (opt.duration && opt.duration.constructor == Number ? 
396                         opt.duration : 
397                         { slow: 600, fast: 200 }[opt.duration]) || 400;
398         
399                 // Queueing
400                 opt.old = opt.complete;
401                 opt.complete = function(){
402                         jQuery.dequeue(this, "fx");
403                         if ( jQuery.isFunction( opt.old ) )
404                                 opt.old.apply( this );
405                 };
406         
407                 return opt;
408         },
409         
410         easing: {
411                 linear: function( p, n, firstNum, diff ) {
412                         return firstNum + diff * p;
413                 },
414                 swing: function( p, n, firstNum, diff ) {
415                         return ((-Math.cos(p*Math.PI)/2) + 0.5) * diff + firstNum;
416                 }
417         },
418         
419         queue: {},
420         
421         dequeue: function(elem,type){
422                 type = type || "fx";
423         
424                 if ( elem.queue && elem.queue[type] ) {
425                         // Remove self
426                         elem.queue[type].shift();
427         
428                         // Get next function
429                         var f = elem.queue[type][0];
430                 
431                         if ( f ) f.apply( elem );
432                 }
433         },
434
435         timers: [],
436
437         fx: function( elem, options, prop ){
438
439                 var z = this, y = elem.style,
440                         isprop = elem[prop] != null && y[prop] == null;
441                 
442                 // Simple function for setting a style value
443                 z.a = function(){
444                         if ( options.step )
445                                 options.step.apply( elem, [ z.now ] );
446
447                         if ( prop == "opacity" )
448                                 jQuery.attr(y, "opacity", z.now); // Let attr handle opacity
449                         else {
450                                 if ( isprop )
451                                         elem[prop] = parseInt(z.now);
452                                 else
453                                         y[prop] = parseInt(z.now) + "px";
454
455                                 // Set display property to block for height/width animations
456                                 if ( prop == "height" || prop == "width" )
457                                         y.display = "block";
458                         }
459                 };
460
461                 // Figure out the maximum number to run to
462                 z.max = function(){
463                         return parseFloat( jQuery.css(elem,prop) );
464                 };
465
466                 // Get the current size
467                 z.cur = function(){
468                         if ( isprop ) return elem[prop];
469                         var r = parseFloat( jQuery.curCSS(elem, prop) );
470                         return r && r > -10000 ? r : z.max();
471                 };
472
473                 // Start an animation from one number to another
474                 z.custom = function(from,to){
475                         z.startTime = (new Date()).getTime();
476                         z.now = from;
477                         z.a();
478
479                         function t(){
480                                 return z.step(from, to);
481                         }
482
483                         t.elem = elem;
484
485                         jQuery.timers.push(t);
486
487                         if ( jQuery.timers.length == 1 ) {
488                                 var timer = setInterval(function(){
489                                         var timers = jQuery.timers;
490                                         
491                                         for ( var i = 0; i < timers.length; i++ )
492                                                 if ( !timers[i]() )
493                                                         timers.splice(i--, 1);
494
495                                         if ( !timers.length )
496                                                 clearInterval( timer );
497                                 }, 13);
498                         }
499                 };
500
501                 // Simple 'show' function
502                 z.show = function(){
503                         if ( !elem.orig ) elem.orig = {};
504
505                         // Remember where we started, so that we can go back to it later
506                         elem.orig[prop] = jQuery.attr( elem.style, prop );
507
508                         options.show = true;
509
510                         // Begin the animation
511                         z.custom(0, this.cur());
512
513                         // Make sure that we start at a small width/height to avoid any
514                         // flash of content
515                         if ( prop != "opacity" )
516                                 y[prop] = "1px";
517                         
518                         // Start by showing the element
519                         jQuery(elem).show();
520                 };
521
522                 // Simple 'hide' function
523                 z.hide = function(){
524                         if ( !elem.orig ) elem.orig = {};
525
526                         // Remember where we started, so that we can go back to it later
527                         elem.orig[prop] = jQuery.attr( elem.style, prop );
528
529                         options.hide = true;
530
531                         // Begin the animation
532                         z.custom(this.cur(), 0);
533                 };
534
535                 // Each step of an animation
536                 z.step = function(firstNum, lastNum){
537                         var t = (new Date()).getTime();
538
539                         if (t > options.duration + z.startTime) {
540                                 z.now = lastNum;
541                                 z.a();
542
543                                 if (elem.curAnim) elem.curAnim[ prop ] = true;
544
545                                 var done = true;
546                                 for ( var i in elem.curAnim )
547                                         if ( elem.curAnim[i] !== true )
548                                                 done = false;
549
550                                 if ( done ) {
551                                         if ( options.display != null ) {
552                                                 // Reset the overflow
553                                                 y.overflow = options.overflow;
554                                         
555                                                 // Reset the display
556                                                 y.display = options.display;
557                                                 if ( jQuery.css(elem, "display") == "none" )
558                                                         y.display = "block";
559                                         }
560
561                                         // Hide the element if the "hide" operation was done
562                                         if ( options.hide )
563                                                 y.display = "none";
564
565                                         // Reset the properties, if the item has been hidden or shown
566                                         if ( options.hide || options.show )
567                                                 for ( var p in elem.curAnim )
568                                                         jQuery.attr(y, p, elem.orig[p]);
569                                 }
570
571                                 // If a callback was provided, execute it
572                                 if ( done && jQuery.isFunction( options.complete ) )
573                                         // Execute the complete function
574                                         options.complete.apply( elem );
575
576                                 return false;
577                         } else {
578                                 var n = t - this.startTime;
579                                 // Figure out where in the animation we are and set the number
580                                 var p = n / options.duration;
581                                 
582                                 // Perform the easing function, defaults to swing
583                                 z.now = jQuery.easing[options.easing || (jQuery.easing.swing ? "swing" : "linear")](p, n, firstNum, (lastNum-firstNum), options.duration);
584
585                                 // Perform the next step of the animation
586                                 z.a();
587                         }
588
589                         return true;
590                 };
591         
592         }
593 });