ceeb6d13f5b6d7288325cb935ee961d87ab0824e
[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                         this.animate({
114                                 height: "toggle", width: "toggle", opacity: "toggle"
115                         }, fn, fn2);
116         },
117         
118         /**
119          * Reveal all matched elements by adjusting their height and firing an
120          * optional callback after completion.
121          *
122          * Only the height is adjusted for this animation, causing all matched
123          * elements to be revealed in a "sliding" manner.
124          *
125          * @example $("p").slideDown("slow");
126          *
127          * @example $("p").slideDown("slow",function(){
128          *   alert("Animation Done.");
129          * });
130          *
131          * @name slideDown
132          * @type jQuery
133          * @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).
134          * @param Function callback (optional) A function to be executed whenever the animation completes.
135          * @cat Effects
136          * @see slideUp(String|Number,Function)
137          * @see slideToggle(String|Number,Function)
138          */
139         slideDown: function(speed,callback){
140                 return this.animate({height: "show"}, speed, callback);
141         },
142         
143         /**
144          * Hide all matched elements by adjusting their height and firing an
145          * optional callback after completion.
146          *
147          * Only the height is adjusted for this animation, causing all matched
148          * elements to be hidden in a "sliding" manner.
149          *
150          * @example $("p").slideUp("slow");
151          *
152          * @example $("p").slideUp("slow",function(){
153          *   alert("Animation Done.");
154          * });
155          *
156          * @name slideUp
157          * @type jQuery
158          * @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).
159          * @param Function callback (optional) A function to be executed whenever the animation completes.
160          * @cat Effects
161          * @see slideDown(String|Number,Function)
162          * @see slideToggle(String|Number,Function)
163          */
164         slideUp: function(speed,callback){
165                 return this.animate({height: "hide"}, speed, callback);
166         },
167
168         /**
169          * Toggle the visibility of all matched elements by adjusting their height and firing an
170          * optional callback after completion.
171          *
172          * Only the height is adjusted for this animation, causing all matched
173          * elements to be hidden in a "sliding" manner.
174          *
175          * @example $("p").slideToggle("slow");
176          *
177          * @example $("p").slideToggle("slow",function(){
178          *   alert("Animation Done.");
179          * });
180          *
181          * @name slideToggle
182          * @type jQuery
183          * @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).
184          * @param Function callback (optional) A function to be executed whenever the animation completes.
185          * @cat Effects
186          * @see slideDown(String|Number,Function)
187          * @see slideUp(String|Number,Function)
188          */
189         slideToggle: function(speed, callback){
190                 return this.animate({height: "toggle"}, speed, callback);
191         },
192         
193         /**
194          * Fade in all matched elements by adjusting their opacity and firing an
195          * optional callback after completion.
196          *
197          * Only the opacity is adjusted for this animation, meaning that
198          * all of the matched elements should already have some form of height
199          * and width associated with them.
200          *
201          * @example $("p").fadeIn("slow");
202          *
203          * @example $("p").fadeIn("slow",function(){
204          *   alert("Animation Done.");
205          * });
206          *
207          * @name fadeIn
208          * @type jQuery
209          * @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).
210          * @param Function callback (optional) A function to be executed whenever the animation completes.
211          * @cat Effects
212          * @see fadeOut(String|Number,Function)
213          * @see fadeTo(String|Number,Number,Function)
214          */
215         fadeIn: function(speed, callback){
216                 return this.animate({opacity: "show"}, speed, callback);
217         },
218         
219         /**
220          * Fade out all matched elements by adjusting their opacity and firing an
221          * optional callback after completion.
222          *
223          * Only the opacity is adjusted for this animation, meaning that
224          * all of the matched elements should already have some form of height
225          * and width associated with them.
226          *
227          * @example $("p").fadeOut("slow");
228          *
229          * @example $("p").fadeOut("slow",function(){
230          *   alert("Animation Done.");
231          * });
232          *
233          * @name fadeOut
234          * @type jQuery
235          * @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).
236          * @param Function callback (optional) A function to be executed whenever the animation completes.
237          * @cat Effects
238          * @see fadeIn(String|Number,Function)
239          * @see fadeTo(String|Number,Number,Function)
240          */
241         fadeOut: function(speed, callback){
242                 return this.animate({opacity: "hide"}, speed, callback);
243         },
244         
245         /**
246          * Fade the opacity of all matched elements to a specified opacity and firing an
247          * optional callback after completion.
248          *
249          * Only the opacity is adjusted for this animation, meaning that
250          * all of the matched elements should already have some form of height
251          * and width associated with them.
252          *
253          * @example $("p").fadeTo("slow", 0.5);
254          *
255          * @example $("p").fadeTo("slow", 0.5, function(){
256          *   alert("Animation Done.");
257          * });
258          *
259          * @name fadeTo
260          * @type jQuery
261          * @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).
262          * @param Number opacity The opacity to fade to (a number from 0 to 1).
263          * @param Function callback (optional) A function to be executed whenever the animation completes.
264          * @cat Effects
265          * @see fadeIn(String|Number,Function)
266          * @see fadeOut(String|Number,Function)
267          */
268         fadeTo: function(speed,to,callback){
269                 return this.animate({opacity: to}, speed, callback);
270         },
271         
272         /**
273          * A function for making your own, custom animations. The key aspect of
274          * this function is the object of style properties that will be animated,
275          * and to what end. Each key within the object represents a style property
276          * that will also be animated (for example: "height", "top", or "opacity").
277          *
278          * Note that properties should be specified using camel case
279          * eg. marginLeft instead of margin-left.
280          *
281          * The value associated with the key represents to what end the property
282          * will be animated. If a number is provided as the value, then the style
283          * property will be transitioned from its current state to that new number.
284          * Otherwise if the string "hide", "show", or "toggle" is provided, a default
285          * animation will be constructed for that property.
286          *
287          * @example $("p").animate({
288          *   height: 'toggle', opacity: 'toggle'
289          * }, "slow");
290          *
291          * @example $("p").animate({
292          *   left: 50, opacity: 'show'
293          * }, 500);
294          *
295          * @example $("p").animate({
296          *   opacity: 'show'
297          * }, "slow", "easein");
298          * @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 'linear' is provided by default, with jQuery).
299          *
300          * @name animate
301          * @type jQuery
302          * @param Hash params A set of style attributes that you wish to animate, and to what end.
303          * @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).
304          * @param String easing (optional) The name of the easing effect that you want to use (e.g. swing or linear). Defaults to "swing".
305          * @param Function callback (optional) A function to be executed whenever the animation completes.
306          * @cat Effects
307          */
308         animate: function( prop, speed, easing, callback ) {
309                 return this.queue(function(){
310                         var hidden = jQuery(this).is(":hidden");
311                         
312                         for ( var p in prop )
313                                 if ( prop[p] == "hide" && hidden ||
314                                         prop[p] == "show" && !hidden )
315                                                 return;
316                 
317                         this.curAnim = jQuery.extend({}, prop);
318                         var opt = jQuery.speed(speed, easing, callback);
319                         var self = this;
320                         
321                         jQuery.each( prop, function(name, val){
322                                 var e = new jQuery.fx( self, opt, name );
323                                 if ( val.constructor == Number )
324                                         e.custom( e.cur(), val );
325                                 else
326                                         e[ val == "toggle" ? hidden ? "show" : "hide" : val ]( prop );
327                         });
328                 });
329         },
330         
331         /**
332          *
333          * @private
334          */
335         queue: function(type,fn){
336                 if ( !fn ) {
337                         fn = type;
338                         type = "fx";
339                 }
340         
341                 return this.each(function(){
342                         if ( !this.queue )
343                                 this.queue = {};
344         
345                         if ( !this.queue[type] )
346                                 this.queue[type] = [];
347         
348                         this.queue[type].push( fn );
349                 
350                         if ( this.queue[type].length == 1 )
351                                 fn.apply(this);
352                 });
353         }
354
355 });
356
357 jQuery.extend({
358         
359         speed: function(speed, easing, fn) {
360                 var opt = speed && speed.constructor == Object ? speed : {
361                         complete: fn || !fn && easing || 
362                                 jQuery.isFunction( speed ) && speed,
363                         duration: speed,
364                         easing: fn && easing || easing && easing.constructor != Function && easing || "swing"
365                 };
366
367                 opt.duration = (opt.duration && opt.duration.constructor == Number ? 
368                         opt.duration : 
369                         { slow: 600, fast: 200 }[opt.duration]) || 400;
370         
371                 // Queueing
372                 opt.old = opt.complete;
373                 opt.complete = function(){
374                         jQuery.dequeue(this, "fx");
375                         if ( jQuery.isFunction( opt.old ) )
376                                 opt.old.apply( this );
377                 };
378         
379                 return opt;
380         },
381         
382         easing: {
383                 linear: function( p, n, firstNum, diff ) {
384                         return firstNum + diff * p;
385                 },
386                 swing: function( p, n, firstNum, diff ) {
387                         return ((-Math.cos(p*Math.PI)/2) + 0.5) * diff + firstNum;
388                 }
389         },
390         
391         queue: {},
392         
393         dequeue: function(elem,type){
394                 type = type || "fx";
395         
396                 if ( elem.queue && elem.queue[type] ) {
397                         // Remove self
398                         elem.queue[type].shift();
399         
400                         // Get next function
401                         var f = elem.queue[type][0];
402                 
403                         if ( f ) f.apply( elem );
404                 }
405         },
406
407         timers: [],
408
409         /*
410          * I originally wrote fx() as a clone of moo.fx and in the process
411          * of making it small in size the code became illegible to sane
412          * people. You've been warned.
413          */
414         
415         fx: function( elem, options, prop ){
416
417                 var z = this;
418
419                 // The styles
420                 var y = elem.style;
421                 
422                 if ( prop == "height" || prop == "width" ) {
423                         // Store display property
424                         var oldDisplay = jQuery.css(elem, "display");
425
426                         // Make sure that nothing sneaks out
427                         var oldOverflow = y.overflow;
428                         y.overflow = "hidden";
429                 }
430
431                 // Simple function for setting a style value
432                 z.a = function(){
433                         if ( options.step )
434                                 options.step.apply( elem, [ z.now ] );
435
436                         if ( prop == "opacity" )
437                                 jQuery.attr(y, "opacity", z.now); // Let attr handle opacity
438                         else {
439                                 y[prop] = parseInt(z.now) + "px";
440                                 y.display = "block"; // Set display property to block for animation
441                         }
442                 };
443
444                 // Figure out the maximum number to run to
445                 z.max = function(){
446                         return parseFloat( jQuery.css(elem,prop) );
447                 };
448
449                 // Get the current size
450                 z.cur = function(){
451                         var r = parseFloat( jQuery.curCSS(elem, prop) );
452                         return r && r > -10000 ? r : z.max();
453                 };
454
455                 // Start an animation from one number to another
456                 z.custom = function(from,to){
457                         z.startTime = (new Date()).getTime();
458                         z.now = from;
459                         z.a();
460
461                         jQuery.timers.push(function(){
462                                 return z.step(from, to);
463                         });
464
465                         if ( jQuery.timers.length == 1 ) {
466                                 var timer = setInterval(function(){
467                                         var timers = jQuery.timers;
468                                         
469                                         for ( var i = 0; i < timers.length; i++ )
470                                                 if ( !timers[i]() )
471                                                         timers.splice(i--, 1);
472
473                                         if ( !timers.length )
474                                                 clearInterval( timer );
475                                 }, 13);
476                         }
477                 };
478
479                 // Simple 'show' function
480                 z.show = function(){
481                         if ( !elem.orig ) elem.orig = {};
482
483                         // Remember where we started, so that we can go back to it later
484                         elem.orig[prop] = jQuery.attr( elem.style, prop );
485
486                         options.show = true;
487
488                         // Begin the animation
489                         z.custom(0, this.cur());
490
491                         // Make sure that we start at a small width/height to avoid any
492                         // flash of content
493                         if ( prop != "opacity" )
494                                 y[prop] = "1px";
495                         
496                         // Start by showing the element
497                         jQuery(elem).show();
498                 };
499
500                 // Simple 'hide' function
501                 z.hide = function(){
502                         if ( !elem.orig ) elem.orig = {};
503
504                         // Remember where we started, so that we can go back to it later
505                         elem.orig[prop] = jQuery.attr( elem.style, prop );
506
507                         options.hide = true;
508
509                         // Begin the animation
510                         z.custom(this.cur(), 0);
511                 };
512
513                 // Each step of an animation
514                 z.step = function(firstNum, lastNum){
515                         var t = (new Date()).getTime();
516
517                         if (t > options.duration + z.startTime) {
518                                 z.now = lastNum;
519                                 z.a();
520
521                                 if (elem.curAnim) elem.curAnim[ prop ] = true;
522
523                                 var done = true;
524                                 for ( var i in elem.curAnim )
525                                         if ( elem.curAnim[i] !== true )
526                                                 done = false;
527
528                                 if ( done ) {
529                                         if ( oldDisplay != null ) {
530                                                 // Reset the overflow
531                                                 y.overflow = oldOverflow;
532                                         
533                                                 // Reset the display
534                                                 y.display = oldDisplay;
535                                                 if ( jQuery.css(elem, "display") == "none" )
536                                                         y.display = "block";
537                                         }
538
539                                         // Hide the element if the "hide" operation was done
540                                         if ( options.hide )
541                                                 y.display = "none";
542
543                                         // Reset the properties, if the item has been hidden or shown
544                                         if ( options.hide || options.show )
545                                                 for ( var p in elem.curAnim )
546                                                         jQuery.attr(y, p, elem.orig[p]);
547                                 }
548
549                                 // If a callback was provided, execute it
550                                 if ( done && jQuery.isFunction( options.complete ) )
551                                         // Execute the complete function
552                                         options.complete.apply( elem );
553
554                                 return false;
555                         } else {
556                                 var n = t - this.startTime;
557                                 // Figure out where in the animation we are and set the number
558                                 var p = n / options.duration;
559                                 
560                                 // Perform the easing function, defaults to swing
561                                 z.now = jQuery.easing[options.easing](p, n,  firstNum, (lastNum-firstNum), options.duration);
562
563                                 // Perform the next step of the animation
564                                 z.a();
565                         }
566
567                         return true;
568                 };
569         
570         }
571 });