Implemented #753
[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.each(function(){
42                                 this.style.display = this.oldblock ? this.oldblock : "";
43                                 if ( jQuery.css(this,"display") == "none" )
44                                         this.style.display = "block";
45                         });
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.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                         });
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 fn ?
112                         this._toggle( fn, fn2 ) :
113                         this.each(function(){
114                                 jQuery(this)[ jQuery(this).is(":hidden") ? "show" : "hide" ]
115                                         .apply( jQuery(this), arguments );
116                         });
117         },
118         
119         /**
120          * Reveal all matched elements by adjusting their height and firing an
121          * optional callback after completion.
122          *
123          * Only the height is adjusted for this animation, causing all matched
124          * elements to be revealed in a "sliding" manner.
125          *
126          * @example $("p").slideDown("slow");
127          *
128          * @example $("p").slideDown("slow",function(){
129          *   alert("Animation Done.");
130          * });
131          *
132          * @name slideDown
133          * @type jQuery
134          * @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).
135          * @param Function callback (optional) A function to be executed whenever the animation completes.
136          * @cat Effects
137          * @see slideUp(String|Number,Function)
138          * @see slideToggle(String|Number,Function)
139          */
140         slideDown: function(speed,callback){
141                 return this.animate({height: "show"}, speed, callback);
142         },
143         
144         /**
145          * Hide all matched elements by adjusting their height and firing an
146          * optional callback after completion.
147          *
148          * Only the height is adjusted for this animation, causing all matched
149          * elements to be hidden in a "sliding" manner.
150          *
151          * @example $("p").slideUp("slow");
152          *
153          * @example $("p").slideUp("slow",function(){
154          *   alert("Animation Done.");
155          * });
156          *
157          * @name slideUp
158          * @type jQuery
159          * @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).
160          * @param Function callback (optional) A function to be executed whenever the animation completes.
161          * @cat Effects
162          * @see slideDown(String|Number,Function)
163          * @see slideToggle(String|Number,Function)
164          */
165         slideUp: function(speed,callback){
166                 return this.animate({height: "hide"}, speed, callback);
167         },
168
169         /**
170          * Toggle the visibility of all matched elements by adjusting their height and firing an
171          * optional callback after completion.
172          *
173          * Only the height is adjusted for this animation, causing all matched
174          * elements to be hidden in a "sliding" manner.
175          *
176          * @example $("p").slideToggle("slow");
177          *
178          * @example $("p").slideToggle("slow",function(){
179          *   alert("Animation Done.");
180          * });
181          *
182          * @name slideToggle
183          * @type jQuery
184          * @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).
185          * @param Function callback (optional) A function to be executed whenever the animation completes.
186          * @cat Effects
187          * @see slideDown(String|Number,Function)
188          * @see slideUp(String|Number,Function)
189          */
190         slideToggle: function(speed, callback){
191                 return this.each(function(){
192                         var state = jQuery(this).is(":hidden") ? "show" : "hide";
193                         jQuery(this).animate({height: state}, speed, callback);
194                 });
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          * The value associated with the key represents to what end the property
283          * will be animated. If a number is provided as the value, then the style
284          * property will be transitioned from its current state to that new number.
285          * Oterwise if the string "hide", "show", or "toggle" is provided, a default
286          * animation will be constructed for that property.
287          *
288          * @example $("p").animate({
289          *   height: 'toggle', opacity: 'toggle'
290          * }, "slow");
291          *
292          * @example $("p").animate({
293          *   left: 50, opacity: 'show'
294          * }, 500);
295          *
296          * @example $("p").animate({
297          *   opacity: 'show'
298          * }, "slow", "easein");
299          * @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).
300          *
301          * @name animate
302          * @type jQuery
303          * @param Hash params A set of style attributes that you wish to animate, and to what end.
304          * @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).
305          * @param String easing (optional) The name of the easing effect that you want to use (Plugin Required).
306          * @param Function callback (optional) A function to be executed whenever the animation completes.
307          * @cat Effects
308          */
309         animate: function( prop, speed, easing, callback ) {
310                 return this.queue(function(){
311                 
312                         this.curAnim = jQuery.extend({}, prop);
313                         var opt = jQuery.speed(speed, easing, callback);
314                         
315                         for ( var p in prop ) {
316                                 var e = new jQuery.fx( this, opt, p );
317                                 if ( prop[p].constructor == Number )
318                                         e.custom( e.cur(), prop[p] );
319                                 else
320                                         e[ prop[p] ]( prop );
321                         }
322                         
323                 });
324         },
325         
326         /**
327          *
328          * @private
329          */
330         queue: function(type,fn){
331                 if ( !fn ) {
332                         fn = type;
333                         type = "fx";
334                 }
335         
336                 return this.each(function(){
337                         if ( !this.queue )
338                                 this.queue = {};
339         
340                         if ( !this.queue[type] )
341                                 this.queue[type] = [];
342         
343                         this.queue[type].push( fn );
344                 
345                         if ( this.queue[type].length == 1 )
346                                 fn.apply(this);
347                 });
348         }
349
350 });
351
352 jQuery.extend({
353         
354         speed: function(speed, easing, fn) {
355                 var opt = speed.constructor == Object ? speed : {
356                         complete: fn || !fn && easing || 
357                                 speed.constructor == Function && speed,
358                         duration: speed,
359                         easing: fn && easing || easing && easing.constructor != Function && easing
360                 };
361
362                 opt.duration = (opt.duration.constructor == Number ? 
363                         opt.duration : 
364                         { slow: 600, fast: 200 }[opt.duration]) || 400;
365         
366                 // Queueing
367                 opt.oldComplete = opt.complete;
368                 opt.complete = function(){
369                         jQuery.dequeue(this, "fx");
370                         if ( opt.oldComplete && opt.oldComplete.constructor == Function )
371                                 opt.oldComplete.apply( this );
372                 };
373         
374                 return opt;
375         },
376         
377         easing: {},
378         
379         queue: {},
380         
381         dequeue: function(elem,type){
382                 type = type || "fx";
383         
384                 if ( elem.queue && elem.queue[type] ) {
385                         // Remove self
386                         elem.queue[type].shift();
387         
388                         // Get next function
389                         var f = elem.queue[type][0];
390                 
391                         if ( f ) f.apply( elem );
392                 }
393         },
394
395         /*
396          * I originally wrote fx() as a clone of moo.fx and in the process
397          * of making it small in size the code became illegible to sane
398          * people. You've been warned.
399          */
400         
401         fx: function( elem, options, prop ){
402
403                 var z = this;
404
405                 // The styles
406                 var y = elem.style;
407                 
408                 // Store display property
409                 var oldDisplay = jQuery.css(elem, 'display');
410                 // Set display property to block for animation
411                 y.display = "block";
412                 // Make sure that nothing sneaks out
413                 y.overflow = "hidden";
414
415                 // Simple function for setting a style value
416                 z.a = function(){
417                         if ( options.step )
418                                 options.step.apply( elem, [ z.now ] );
419
420                         if ( prop == "opacity" )
421                                 jQuery.attr(y, "opacity", z.now); // Let attr handle opacity
422                         else if ( parseInt(z.now) ) // My hate for IE will never die
423                                 y[prop] = parseInt(z.now) + "px";
424                 };
425
426                 // Figure out the maximum number to run to
427                 z.max = function(){
428                         return parseFloat( jQuery.css(elem,prop) );
429                 };
430
431                 // Get the current size
432                 z.cur = function(){
433                         var r = parseFloat( jQuery.curCSS(elem, prop) );
434                         return r && r > -10000 ? r : z.max();
435                 };
436
437                 // Start an animation from one number to another
438                 z.custom = function(from,to){
439                         z.startTime = (new Date()).getTime();
440                         z.now = from;
441                         z.a();
442
443                         z.timer = setInterval(function(){
444                                 z.step(from, to);
445                         }, 13);
446                 };
447
448                 // Simple 'show' function
449                 z.show = function(){
450                         if ( !elem.orig ) elem.orig = {};
451
452                         // Remember where we started, so that we can go back to it later
453                         elem.orig[prop] = this.cur();
454
455                         options.show = true;
456
457                         // Begin the animation
458                         z.custom(0, elem.orig[prop]);
459
460                         // Stupid IE, look what you made me do
461                         if ( prop != "opacity" )
462                                 y[prop] = "1px";
463                 };
464
465                 // Simple 'hide' function
466                 z.hide = function(){
467                         if ( !elem.orig ) elem.orig = {};
468
469                         // Remember where we started, so that we can go back to it later
470                         elem.orig[prop] = this.cur();
471
472                         options.hide = true;
473
474                         // Begin the animation
475                         z.custom(elem.orig[prop], 0);
476                 };
477                 
478                 //Simple 'toggle' function
479                 z.toggle = function() {
480                         if ( !elem.orig ) elem.orig = {};
481
482                         // Remember where we started, so that we can go back to it later
483                         elem.orig[prop] = this.cur();
484
485                         if(oldDisplay == 'none')  {
486                                 options.show = true;
487                                 
488                                 // Stupid IE, look what you made me do
489                                 if ( prop != "opacity" )
490                                         y[prop] = "1px";
491
492                                 // Begin the animation
493                                 z.custom(0, elem.orig[prop]);   
494                         } else {
495                                 options.hide = true;
496
497                                 // Begin the animation
498                                 z.custom(elem.orig[prop], 0);
499                         }               
500                 };
501
502                 // Each step of an animation
503                 z.step = function(firstNum, lastNum){
504                         var t = (new Date()).getTime();
505
506                         if (t > options.duration + z.startTime) {
507                                 // Stop the timer
508                                 clearInterval(z.timer);
509                                 z.timer = null;
510
511                                 z.now = lastNum;
512                                 z.a();
513
514                                 if (elem.curAnim) elem.curAnim[ prop ] = true;
515
516                                 var done = true;
517                                 for ( var i in elem.curAnim )
518                                         if ( elem.curAnim[i] !== true )
519                                                 done = false;
520
521                                 if ( done ) {
522                                         // Reset the overflow
523                                         y.overflow = '';
524                                         
525                                         // Reset the display
526                                         y.display = oldDisplay;
527                                         if (jQuery.css(elem, 'display') == 'none')
528                                                 y.display = 'block';
529
530                                         // Hide the element if the "hide" operation was done
531                                         if ( options.hide ) 
532                                                 y.display = 'none';
533
534                                         // Reset the properties, if the item has been hidden or shown
535                                         if ( options.hide || options.show )
536                                                 for ( var p in elem.curAnim )
537                                                         if (p == "opacity")
538                                                                 jQuery.attr(y, p, elem.orig[p]);
539                                                         else
540                                                                 y[p] = '';
541                                 }
542
543                                 // If a callback was provided, execute it
544                                 if ( done && options.complete && options.complete.constructor == Function )
545                                         // Execute the complete function
546                                         options.complete.apply( elem );
547                         } else {
548                                 var n = t - this.startTime;
549                                 // Figure out where in the animation we are and set the number
550                                 var p = n / options.duration;
551                                 
552                                 // If the easing function exists, then use it 
553                                 z.now = options.easing && jQuery.easing[options.easing] ?
554                                         jQuery.easing[options.easing](p, n,  firstNum, (lastNum-firstNum), options.duration) :
555                                         // else use default linear easing
556                                         ((-Math.cos(p*Math.PI)/2) + 0.5) * (lastNum-firstNum) + firstNum;
557
558                                 // Perform the next step of the animation
559                                 z.a();
560                         }
561                 };
562         
563         }
564 });