Improved a lot of docs, adding description to examples, merging methods with optional...
[jquery.git] / src / event / event.js
1 /*
2  * A number of helper functions used for managing events.
3  * Many of the ideas behind this code orignated from 
4  * Dean Edwards' addEvent library.
5  */
6 jQuery.event = {
7
8         // Bind an event to an element
9         // Original by Dean Edwards
10         add: function(element, type, handler, data) {
11                 // For whatever reason, IE has trouble passing the window object
12                 // around, causing it to be cloned in the process
13                 if ( jQuery.browser.msie && element.setInterval != undefined )
14                         element = window;
15
16                 // if data is passed, bind to handler
17                 if( data ) 
18                         handler.data = data;
19
20                 // Make sure that the function being executed has a unique ID
21                 if ( !handler.guid )
22                         handler.guid = this.guid++;
23
24                 // Init the element's event structure
25                 if (!element.events)
26                         element.events = {};
27
28                 // Get the current list of functions bound to this event
29                 var handlers = element.events[type];
30
31                 // If it hasn't been initialized yet
32                 if (!handlers) {
33                         // Init the event handler queue
34                         handlers = element.events[type] = {};
35
36                         // Remember an existing handler, if it's already there
37                         if (element["on" + type])
38                                 handlers[0] = element["on" + type];
39                 }
40
41                 // Add the function to the element's handler list
42                 handlers[handler.guid] = handler;
43
44                 // And bind the global event handler to the element
45                 element["on" + type] = this.handle;
46
47                 // Remember the function in a global list (for triggering)
48                 if (!this.global[type])
49                         this.global[type] = [];
50                 this.global[type].push( element );
51         },
52
53         guid: 1,
54         global: {},
55
56         // Detach an event or set of events from an element
57         remove: function(element, type, handler) {
58                 if (element.events)
59                         if ( type && type.type )
60                                 delete element.events[ type.type ][ type.handler.guid ];
61                         else if (type && element.events[type])
62                                 if ( handler )
63                                         delete element.events[type][handler.guid];
64                                 else
65                                         for ( var i in element.events[type] )
66                                                 delete element.events[type][i];
67                         else
68                                 for ( var j in element.events )
69                                         this.remove( element, j );
70         },
71
72         trigger: function(type,data,element) {
73                 // Clone the incoming data, if any
74                 data = jQuery.makeArray(data || []);
75
76                 // Handle a global trigger
77                 if ( !element ) {
78                         var g = this.global[type];
79                         if ( g )
80                                 for ( var i = 0, gl = g.length; i < gl; i++ )
81                                         this.trigger( type, data, g[i] );
82
83                 // Handle triggering a single element
84                 } else if ( element["on" + type] ) {
85                         if ( element[ type ] && element[ type ].constructor == Function )
86                                 element[ type ]();
87                         else {
88                                 // Pass along a fake event
89                                 data.unshift( this.fix({ type: type, target: element }) );
90         
91                                 // Trigger the event
92                                 element["on" + type].apply( element, data );
93                         }
94                 }
95         },
96
97         handle: function(event) {
98                 if ( typeof jQuery == "undefined" ) return false;
99
100                 // Empty object is for triggered events with no data
101                 event = jQuery.event.fix( event || window.event || {} ); 
102
103                 // returned undefined or false
104                 var returnValue;
105
106                 var c = this.events[event.type];
107
108                 var args = [].slice.call( arguments, 1 );
109                 args.unshift( event );
110
111                 for ( var j in c ) {
112                         // Pass in a reference to the handler function itself
113                         // So that we can later remove it
114                         args[0].handler = c[j];
115                         args[0].data = c[j].data;
116
117                         if ( c[j].apply( this, args ) === false ) {
118                                 event.preventDefault();
119                                 event.stopPropagation();
120                                 returnValue = false;
121                         }
122                 }
123
124                 // Clean up added properties in IE to prevent memory leak
125                 if (jQuery.browser.msie) event.target = event.preventDefault = event.stopPropagation = event.handler = event.data = null;
126
127                 return returnValue;
128         },
129
130         fix: function(event) {
131                 // Fix target property, if necessary
132                 if ( !event.target && event.srcElement )
133                         event.target = event.srcElement;
134
135                 // Calculate pageX/Y if missing and clientX/Y available
136                 if ( typeof event.pageX == "undefined" && typeof event.clientX != "undefined" ) {
137                         var e = document.documentElement, b = document.body;
138                         event.pageX = event.clientX + (e.scrollLeft || b.scrollLeft);
139                         event.pageY = event.clientY + (e.scrollTop || b.scrollTop);
140                 }
141                                 
142                 // check if target is a textnode (safari)
143                 if (jQuery.browser.safari && event.target.nodeType == 3) {
144                         // store a copy of the original event object 
145                         // and clone because target is read only
146                         var originalEvent = event;
147                         event = jQuery.extend({}, originalEvent);
148                         
149                         // get parentnode from textnode
150                         event.target = originalEvent.target.parentNode;
151                         
152                         // add preventDefault and stopPropagation since 
153                         // they will not work on the clone
154                         event.preventDefault = function() {
155                                 return originalEvent.preventDefault();
156                         };
157                         event.stopPropagation = function() {
158                                 return originalEvent.stopPropagation();
159                         };
160                 }
161                 
162                 // fix preventDefault and stopPropagation
163                 if (!event.preventDefault)
164                         event.preventDefault = function() {
165                                 this.returnValue = false;
166                         };
167                         
168                 if (!event.stopPropagation)
169                         event.stopPropagation = function() {
170                                 this.cancelBubble = true;
171                         };
172                         
173                 return event;
174         }
175 };
176
177 jQuery.fn.extend({
178
179         /**
180          * Binds a handler to a particular event (like click) for each matched element.
181          * The event handler is passed an event object that you can use to prevent
182          * default behaviour. To stop both default action and event bubbling, your handler
183          * has to return false.
184          *
185          * In most cases, you can define your event handlers as anonymous functions
186          * (see first example). In cases where that is not possible, you can pass additional
187          * data as the second paramter (and the handler function as the third), see 
188          * second example.
189          *
190          * @example $("p").bind( "click", function() {
191          *   alert( $(this).text() );
192          * } )
193          * @before <p>Hello</p>
194          * @result alert("Hello")
195          *
196          * @example var handler = function(event) {
197          *   alert(event.data.foo);
198          * };
199          * $("p").bind( "click", {foo: "bar"}, handler)
200          * @result alert("bar")
201          * @desc Pass some additional data to the event handler.
202          *
203          * @example $("form").bind( "submit", function() { return false; } )
204          * @desc Cancel a default action and prevent it from bubbling by returning false
205          * from your function.
206          *
207          * @example $("form").bind( "submit", function(event) {
208          *   event.preventDefault();
209          * } );
210          * @desc Cancel only the default action by using the preventDefault method.
211          *
212          *
213          * @example $("form").bind( "submit", function(event) {
214          *   event.stopPropagation();
215          * } )
216          * @desc Stop only an event from bubbling by using the stopPropagation method.
217          *
218          * @name bind
219          * @type jQuery
220          * @param String type An event type
221          * @param Object data (optional) Additional data passed to the event handler as event.data
222          * @param Function fn A function to bind to the event on each of the set of matched elements
223          * @cat Events
224          */
225         bind: function( type, data, fn ) {
226                 return this.each(function(){
227                         jQuery.event.add( this, type, fn || data, data );
228                 });
229         },
230         
231         /**
232          * Binds a handler to a particular event (like click) for each matched element.
233          * The handler is executed only once for each element. Otherwise, the same rules
234          * as described in bind() apply.
235          The event handler is passed an event object that you can use to prevent
236          * default behaviour. To stop both default action and event bubbling, your handler
237          * has to return false.
238          *
239          * In most cases, you can define your event handlers as anonymous functions
240          * (see first example). In cases where that is not possible, you can pass additional
241          * data as the second paramter (and the handler function as the third), see 
242          * second example.
243          *
244          * @example $("p").one( "click", function() {
245          *   alert( $(this).text() );
246          * } )
247          * @before <p>Hello</p>
248          * @result alert("Hello")
249          *
250          * @name one
251          * @type jQuery
252          * @param String type An event type
253          * @param Object data (optional) Additional data passed to the event handler as event.data
254          * @param Function fn A function to bind to the event on each of the set of matched elements
255          * @cat Events
256          */
257         one: function( type, data, fn ) {
258                 return this.each(function(){
259                         jQuery.event.add( this, type, function(event) {
260                                 jQuery(this).unbind(event);
261                                 return (fn || data).apply( this, arguments);
262                         }, data);
263                 });
264         },
265
266         /**
267          * The opposite of bind, removes a bound event from each of the matched
268          * elements.
269          *
270          * Without any arguments, all bound events are removed.
271          *
272          * If the type is provided, all bound events of that type are removed.
273          *
274          * If the function that was passed to bind is provided as the second argument,
275          * only that specific event handler is removed.
276          *
277          * @example $("p").unbind()
278          * @before <p onclick="alert('Hello');">Hello</p>
279          * @result [ <p>Hello</p> ]
280          *
281          * @example $("p").unbind( "click" )
282          * @before <p onclick="alert('Hello');">Hello</p>
283          * @result [ <p>Hello</p> ]
284          *
285          * @example $("p").unbind( "click", function() { alert("Hello"); } )
286          * @before <p onclick="alert('Hello');">Hello</p>
287          * @result [ <p>Hello</p> ]
288          *
289          * @name unbind
290          * @type jQuery
291          * @param String type (optional) An event type
292          * @param Function fn (optional) A function to unbind from the event on each of the set of matched elements
293          * @cat Events
294          */
295         unbind: function( type, fn ) {
296                 return this.each(function(){
297                         jQuery.event.remove( this, type, fn );
298                 });
299         },
300
301         /**
302          * Trigger a type of event on every matched element.
303          *
304          * @example $("p").trigger("click")
305          * @before <p click="alert('hello')">Hello</p>
306          * @result alert('hello')
307          *
308          * @name trigger
309          * @type jQuery
310          * @param String type An event type to trigger.
311          * @cat Events
312          */
313         trigger: function( type, data ) {
314                 return this.each(function(){
315                         jQuery.event.trigger( type, data, this );
316                 });
317         },
318
319         // We're overriding the old toggle function, so
320         // remember it for later
321         _toggle: jQuery.fn.toggle,
322         
323         /**
324          * Toggle between two function calls every other click.
325          * Whenever a matched element is clicked, the first specified function 
326          * is fired, when clicked again, the second is fired. All subsequent 
327          * clicks continue to rotate through the two functions.
328          *
329          * Use unbind("click") to remove.
330          *
331          * @example $("p").toggle(function(){
332          *   $(this).addClass("selected");
333          * },function(){
334          *   $(this).removeClass("selected");
335          * });
336          * 
337          * @name toggle
338          * @type jQuery
339          * @param Function even The function to execute on every even click.
340          * @param Function odd The function to execute on every odd click.
341          * @cat Events
342          */
343         toggle: function() {
344                 // save reference to arguments for access in closure
345                 var a = arguments;
346                 return typeof a[0] == "function" && typeof a[1] == "function" ? this.click(function(e) {
347                         // Figure out which function to execute
348                         this.lastToggle = this.lastToggle == 0 ? 1 : 0;
349                         
350                         // Make sure that clicks stop
351                         e.preventDefault();
352                         
353                         // and execute the function
354                         return a[this.lastToggle].apply( this, [e] ) || false;
355                 }) :
356                 
357                 // Otherwise, execute the old toggle function
358                 this._toggle.apply( this, arguments );
359         },
360         
361         /**
362          * A method for simulating hovering (moving the mouse on, and off,
363          * an object). This is a custom method which provides an 'in' to a 
364          * frequent task.
365          *
366          * Whenever the mouse cursor is moved over a matched 
367          * element, the first specified function is fired. Whenever the mouse 
368          * moves off of the element, the second specified function fires. 
369          * Additionally, checks are in place to see if the mouse is still within 
370          * the specified element itself (for example, an image inside of a div), 
371          * and if it is, it will continue to 'hover', and not move out 
372          * (a common error in using a mouseout event handler).
373          *
374          * @example $("p").hover(function(){
375          *   $(this).addClass("over");
376          * },function(){
377          *   $(this).addClass("out");
378          * });
379          *
380          * @name hover
381          * @type jQuery
382          * @param Function over The function to fire whenever the mouse is moved over a matched element.
383          * @param Function out The function to fire whenever the mouse is moved off of a matched element.
384          * @cat Events
385          */
386         hover: function(f,g) {
387                 
388                 // A private function for handling mouse 'hovering'
389                 function handleHover(e) {
390                         // Check if mouse(over|out) are still within the same parent element
391                         var p = (e.type == "mouseover" ? e.fromElement : e.toElement) || e.relatedTarget;
392         
393                         // Traverse up the tree
394                         while ( p && p != this ) try { p = p.parentNode } catch(e) { p = this; };
395                         
396                         // If we actually just moused on to a sub-element, ignore it
397                         if ( p == this ) return false;
398                         
399                         // Execute the right function
400                         return (e.type == "mouseover" ? f : g).apply(this, [e]);
401                 }
402                 
403                 // Bind the function to the two event listeners
404                 return this.mouseover(handleHover).mouseout(handleHover);
405         },
406         
407         /**
408          * Bind a function to be executed whenever the DOM is ready to be
409          * traversed and manipulated. This is probably the most important 
410          * function included in the event module, as it can greatly improve
411          * the response times of your web applications.
412          *
413          * In a nutshell, this is a solid replacement for using window.onload, 
414          * and attaching a function to that. By using this method, your bound Function 
415          * will be called the instant the DOM is ready to be read and manipulated, 
416          * which is exactly what 99.99% of all Javascript code needs to run.
417          * 
418          * Please ensure you have no code in your &lt;body&gt; onload event handler, 
419          * otherwise $(document).ready() may not fire.
420          *
421          * You can have as many $(document).ready events on your page as you like.
422          * The functions are then executed in the order they were added.
423          *
424          * @example $(document).ready(function(){ Your code here... });
425          *
426          * @name ready
427          * @type jQuery
428          * @param Function fn The function to be executed when the DOM is ready.
429          * @cat Events
430          */
431         ready: function(f) {
432                 // If the DOM is already ready
433                 if ( jQuery.isReady )
434                         // Execute the function immediately
435                         f.apply( document );
436                         
437                 // Otherwise, remember the function for later
438                 else {
439                         // Add the function to the wait list
440                         jQuery.readyList.push( f );
441                 }
442         
443                 return this;
444         }
445 });
446
447 jQuery.extend({
448         /*
449          * All the code that makes DOM Ready work nicely.
450          */
451         isReady: false,
452         readyList: [],
453         
454         // Handle when the DOM is ready
455         ready: function() {
456                 // Make sure that the DOM is not already loaded
457                 if ( !jQuery.isReady ) {
458                         // Remember that the DOM is ready
459                         jQuery.isReady = true;
460                         
461                         // If there are functions bound, to execute
462                         if ( jQuery.readyList ) {
463                                 // Execute all of them
464                                 for ( var i = 0; i < jQuery.readyList.length; i++ )
465                                         jQuery.readyList[i].apply( document );
466                                 
467                                 // Reset the list of functions
468                                 jQuery.readyList = null;
469                         }
470                         // Remove event lisenter to avoid memory leak
471                         if ( jQuery.browser.mozilla || jQuery.browser.opera )
472                                 document.removeEventListener( "DOMContentLoaded", jQuery.ready, false );
473                 }
474         }
475 });
476
477 new function(){
478
479         /**
480          * Bind a function to the scroll event of each matched element.
481          *
482          * @example $("p").scroll( function() { alert("Hello"); } );
483          * @before <p>Hello</p>
484          * @result <p onscroll="alert('Hello');">Hello</p>
485          *
486          * @name scroll
487          * @type jQuery
488          * @param Function fn A function to bind to the scroll event on each of the matched elements.
489          * @cat Events/Browser
490          */
491
492         /**
493          * Trigger the scroll event of each matched element. This causes all of the functions
494          * that have been bound to thet scroll event to be executed.
495          *
496          * @example $("p").scroll();
497          * @before <p onscroll="alert('Hello');">Hello</p>
498          * @result alert('Hello');
499          *
500          * @name scroll
501          * @type jQuery
502          * @cat Events/Browser
503          */
504
505         /**
506          * Bind a function to the submit event of each matched element.
507          *
508          * @example $("#myform").submit( function() {
509          *   return $("input", this).val().length > 0;
510          * } );
511          * @before <form id="myform"><input /></form>
512          * @desc Prevents the form submission when the input has no value entered.
513          *
514          * @name submit
515          * @type jQuery
516          * @param Function fn A function to bind to the submit event on each of the matched elements.
517          * @cat Events/Form
518          */
519
520         /**
521          * Trigger the submit event of each matched element. This causes all of the functions
522          * that have been bound to thet submit event to be executed.
523          *
524          * Note: This does not execute the submit method of the form element! If you need to
525          * submit the form via code, you have to use the DOM method, eg. $("form")[0].submit();
526          *
527          * @example $("form").submit();
528          * @desc Triggers all submit events registered for forms, but does not submit the form
529          *
530          * @name submit
531          * @type jQuery
532          * @cat Events/Form
533          */
534
535         /**
536          * Bind a function to the focus event of each matched element.
537          *
538          * @example $("p").focus( function() { alert("Hello"); } );
539          * @before <p>Hello</p>
540          * @result <p onfocus="alert('Hello');">Hello</p>
541          *
542          * @name focus
543          * @type jQuery
544          * @param Function fn A function to bind to the focus event on each of the matched elements.
545          * @cat Events/UI
546          */
547
548         /**
549          * Trigger the focus event of each matched element. This causes all of the functions
550          * that have been bound to thet focus event to be executed.
551          *
552          * Note: This does not execute the focus method of the underlying elements! If you need to
553          * focus an element via code, you have to use the DOM method, eg. $("#myinput")[0].focus();
554          *
555          * @example $("p").focus();
556          * @before <p onfocus="alert('Hello');">Hello</p>
557          * @result alert('Hello');
558          *
559          * @name focus
560          * @type jQuery
561          * @cat Events/UI
562          */
563
564         /**
565          * Bind a function to the keydown event of each matched element.
566          *
567          * @example $("p").keydown( function() { alert("Hello"); } );
568          * @before <p>Hello</p>
569          * @result <p onkeydown="alert('Hello');">Hello</p>
570          *
571          * @name keydown
572          * @type jQuery
573          * @param Function fn A function to bind to the keydown event on each of the matched elements.
574          * @cat Events/Keyboard
575          */
576
577         /**
578          * Trigger the keydown event of each matched element. This causes all of the functions
579          * that have been bound to thet keydown event to be executed.
580          *
581          * @example $("p").keydown();
582          * @before <p onkeydown="alert('Hello');">Hello</p>
583          * @result alert('Hello');
584          *
585          * @name keydown
586          * @type jQuery
587          * @cat Events/Keyboard
588          */
589
590         /**
591          * Bind a function to the dblclick event of each matched element.
592          *
593          * @example $("p").dblclick( function() { alert("Hello"); } );
594          * @before <p>Hello</p>
595          * @result <p ondblclick="alert('Hello');">Hello</p>
596          *
597          * @name dblclick
598          * @type jQuery
599          * @param Function fn A function to bind to the dblclick event on each of the matched elements.
600          * @cat Events/Mouse
601          */
602
603         /**
604          * Trigger the dblclick event of each matched element. This causes all of the functions
605          * that have been bound to thet dblclick event to be executed.
606          *
607          * @example $("p").dblclick();
608          * @before <p ondblclick="alert('Hello');">Hello</p>
609          * @result alert('Hello');
610          *
611          * @name dblclick
612          * @type jQuery
613          * @cat Events/Mouse
614          */
615
616         /**
617          * Bind a function to the keypress event of each matched element.
618          *
619          * @example $("p").keypress( function() { alert("Hello"); } );
620          * @before <p>Hello</p>
621          * @result <p onkeypress="alert('Hello');">Hello</p>
622          *
623          * @name keypress
624          * @type jQuery
625          * @param Function fn A function to bind to the keypress event on each of the matched elements.
626          * @cat Events/Keyboard
627          */
628
629         /**
630          * Trigger the keypress event of each matched element. This causes all of the functions
631          * that have been bound to thet keypress event to be executed.
632          *
633          * @example $("p").keypress();
634          * @before <p onkeypress="alert('Hello');">Hello</p>
635          * @result alert('Hello');
636          *
637          * @name keypress
638          * @type jQuery
639          * @cat Events/Keyboard
640          */
641
642         /**
643          * Bind a function to the error event of each matched element.
644          *
645          * @example $("p").error( function() { alert("Hello"); } );
646          * @before <p>Hello</p>
647          * @result <p onerror="alert('Hello');">Hello</p>
648          *
649          * @name error
650          * @type jQuery
651          * @param Function fn A function to bind to the error event on each of the matched elements.
652          * @cat Events/Browser
653          */
654
655         /**
656          * Trigger the error event of each matched element. This causes all of the functions
657          * that have been bound to thet error event to be executed.
658          *
659          * @example $("p").error();
660          * @before <p onerror="alert('Hello');">Hello</p>
661          * @result alert('Hello');
662          *
663          * @name error
664          * @type jQuery
665          * @cat Events/Browser
666          */
667
668         /**
669          * Bind a function to the blur event of each matched element.
670          *
671          * @example $("p").blur( function() { alert("Hello"); } );
672          * @before <p>Hello</p>
673          * @result <p onblur="alert('Hello');">Hello</p>
674          *
675          * @name blur
676          * @type jQuery
677          * @param Function fn A function to bind to the blur event on each of the matched elements.
678          * @cat Events/UI
679          */
680
681         /**
682          * Trigger the blur event of each matched element. This causes all of the functions
683          * that have been bound to thet blur event to be executed.
684          *
685          * Note: This does not execute the blur method of the underlying elements! If you need to
686          * blur an element via code, you have to use the DOM method, eg. $("#myinput")[0].blur();
687          *
688          * @example $("p").blur();
689          * @before <p onblur="alert('Hello');">Hello</p>
690          * @result alert('Hello');
691          *
692          * @name blur
693          * @type jQuery
694          * @cat Events/UI
695          */
696
697         /**
698          * Bind a function to the load event of each matched element.
699          *
700          * @example $("p").load( function() { alert("Hello"); } );
701          * @before <p>Hello</p>
702          * @result <p onload="alert('Hello');">Hello</p>
703          *
704          * @name load
705          * @type jQuery
706          * @param Function fn A function to bind to the load event on each of the matched elements.
707          * @cat Events/Browser
708          */
709
710         /**
711          * Trigger the load event of each matched element. This causes all of the functions
712          * that have been bound to thet load event to be executed.
713          *
714          * Marked as private: Calling load() without arguments throws exception because the ajax load
715          * does not handle it.
716          *
717          * @example $("p").load();
718          * @before <p onload="alert('Hello');">Hello</p>
719          * @result alert('Hello');
720          *
721          * @name load
722          * @private
723          * @type jQuery
724          * @cat Events/Browser
725          */
726
727         /**
728          * Bind a function to the select event of each matched element.
729          *
730          * @example $("p").select( function() { alert("Hello"); } );
731          * @before <p>Hello</p>
732          * @result <p onselect="alert('Hello');">Hello</p>
733          *
734          * @name select
735          * @type jQuery
736          * @param Function fn A function to bind to the select event on each of the matched elements.
737          * @cat Events/Form
738          */
739
740         /**
741          * Trigger the select event of each matched element. This causes all of the functions
742          * that have been bound to thet select event to be executed.
743          *
744          * @example $("p").select();
745          * @before <p onselect="alert('Hello');">Hello</p>
746          * @result alert('Hello');
747          *
748          * @name select
749          * @type jQuery
750          * @cat Events/Form
751          */
752
753         /**
754          * Bind a function to the mouseup event of each matched element.
755          *
756          * @example $("p").mouseup( function() { alert("Hello"); } );
757          * @before <p>Hello</p>
758          * @result <p onmouseup="alert('Hello');">Hello</p>
759          *
760          * @name mouseup
761          * @type jQuery
762          * @param Function fn A function to bind to the mouseup event on each of the matched elements.
763          * @cat Events/Mouse
764          */
765
766         /**
767          * Trigger the mouseup event of each matched element. This causes all of the functions
768          * that have been bound to thet mouseup event to be executed.
769          *
770          * @example $("p").mouseup();
771          * @before <p onmouseup="alert('Hello');">Hello</p>
772          * @result alert('Hello');
773          *
774          * @name mouseup
775          * @type jQuery
776          * @cat Events/Mouse
777          */
778
779         /**
780          * Bind a function to the unload event of each matched element.
781          *
782          * @example $("p").unload( function() { alert("Hello"); } );
783          * @before <p>Hello</p>
784          * @result <p onunload="alert('Hello');">Hello</p>
785          *
786          * @name unload
787          * @type jQuery
788          * @param Function fn A function to bind to the unload event on each of the matched elements.
789          * @cat Events/Browser
790          */
791
792         /**
793          * Trigger the unload event of each matched element. This causes all of the functions
794          * that have been bound to thet unload event to be executed.
795          *
796          * @example $("p").unload();
797          * @before <p onunload="alert('Hello');">Hello</p>
798          * @result alert('Hello');
799          *
800          * @name unload
801          * @type jQuery
802          * @cat Events/Browser
803          */
804
805         /**
806          * Bind a function to the change event of each matched element.
807          *
808          * @example $("p").change( function() { alert("Hello"); } );
809          * @before <p>Hello</p>
810          * @result <p onchange="alert('Hello');">Hello</p>
811          *
812          * @name change
813          * @type jQuery
814          * @param Function fn A function to bind to the change event on each of the matched elements.
815          * @cat Events/Form
816          */
817
818         /**
819          * Trigger the change event of each matched element. This causes all of the functions
820          * that have been bound to thet change event to be executed.
821          *
822          * @example $("p").change();
823          * @before <p onchange="alert('Hello');">Hello</p>
824          * @result alert('Hello');
825          *
826          * @name change
827          * @type jQuery
828          * @cat Events/Form
829          */
830
831         /**
832          * Bind a function to the mouseout event of each matched element.
833          *
834          * @example $("p").mouseout( function() { alert("Hello"); } );
835          * @before <p>Hello</p>
836          * @result <p onmouseout="alert('Hello');">Hello</p>
837          *
838          * @name mouseout
839          * @type jQuery
840          * @param Function fn A function to bind to the mouseout event on each of the matched elements.
841          * @cat Events/Mouse
842          */
843
844         /**
845          * Trigger the mouseout event of each matched element. This causes all of the functions
846          * that have been bound to thet mouseout event to be executed.
847          *
848          * @example $("p").mouseout();
849          * @before <p onmouseout="alert('Hello');">Hello</p>
850          * @result alert('Hello');
851          *
852          * @name mouseout
853          * @type jQuery
854          * @cat Events/Mouse
855          */
856
857         /**
858          * Bind a function to the keyup event of each matched element.
859          *
860          * @example $("p").keyup( function() { alert("Hello"); } );
861          * @before <p>Hello</p>
862          * @result <p onkeyup="alert('Hello');">Hello</p>
863          *
864          * @name keyup
865          * @type jQuery
866          * @param Function fn A function to bind to the keyup event on each of the matched elements.
867          * @cat Events/Keyboard
868          */
869
870         /**
871          * Trigger the keyup event of each matched element. This causes all of the functions
872          * that have been bound to thet keyup event to be executed.
873          *
874          * @example $("p").keyup();
875          * @before <p onkeyup="alert('Hello');">Hello</p>
876          * @result alert('Hello');
877          *
878          * @name keyup
879          * @type jQuery
880          * @cat Events/Keyboard
881          */
882
883         /**
884          * Bind a function to the click event of each matched element.
885          *
886          * @example $("p").click( function() { alert("Hello"); } );
887          * @before <p>Hello</p>
888          * @result <p onclick="alert('Hello');">Hello</p>
889          *
890          * @name click
891          * @type jQuery
892          * @param Function fn A function to bind to the click event on each of the matched elements.
893          * @cat Events/Mouse
894          */
895
896         /**
897          * Trigger the click event of each matched element. This causes all of the functions
898          * that have been bound to thet click event to be executed.
899          *
900          * @example $("p").click();
901          * @before <p onclick="alert('Hello');">Hello</p>
902          * @result alert('Hello');
903          *
904          * @name click
905          * @type jQuery
906          * @cat Events/Mouse
907          */
908
909         /**
910          * Bind a function to the resize event of each matched element.
911          *
912          * @example $("p").resize( function() { alert("Hello"); } );
913          * @before <p>Hello</p>
914          * @result <p onresize="alert('Hello');">Hello</p>
915          *
916          * @name resize
917          * @type jQuery
918          * @param Function fn A function to bind to the resize event on each of the matched elements.
919          * @cat Events/Browser
920          */
921
922         /**
923          * Trigger the resize event of each matched element. This causes all of the functions
924          * that have been bound to thet resize event to be executed.
925          *
926          * @example $("p").resize();
927          * @before <p onresize="alert('Hello');">Hello</p>
928          * @result alert('Hello');
929          *
930          * @name resize
931          * @type jQuery
932          * @cat Events/Browser
933          */
934
935         /**
936          * Bind a function to the mousemove event of each matched element.
937          *
938          * @example $("p").mousemove( function() { alert("Hello"); } );
939          * @before <p>Hello</p>
940          * @result <p onmousemove="alert('Hello');">Hello</p>
941          *
942          * @name mousemove
943          * @type jQuery
944          * @param Function fn A function to bind to the mousemove event on each of the matched elements.
945          * @cat Events/Mouse
946          */
947
948         /**
949          * Trigger the mousemove event of each matched element. This causes all of the functions
950          * that have been bound to thet mousemove event to be executed.
951          *
952          * @example $("p").mousemove();
953          * @before <p onmousemove="alert('Hello');">Hello</p>
954          * @result alert('Hello');
955          *
956          * @name mousemove
957          * @type jQuery
958          * @cat Events/Mouse
959          */
960
961         /**
962          * Bind a function to the mousedown event of each matched element.
963          *
964          * @example $("p").mousedown( function() { alert("Hello"); } );
965          * @before <p>Hello</p>
966          * @result <p onmousedown="alert('Hello');">Hello</p>
967          *
968          * @name mousedown
969          * @type jQuery
970          * @param Function fn A function to bind to the mousedown event on each of the matched elements.
971          * @cat Events/Mouse
972          */
973
974         /**
975          * Trigger the mousedown event of each matched element. This causes all of the functions
976          * that have been bound to thet mousedown event to be executed.
977          *
978          * @example $("p").mousedown();
979          * @before <p onmousedown="alert('Hello');">Hello</p>
980          * @result alert('Hello');
981          *
982          * @name mousedown
983          * @type jQuery
984          * @cat Events/Mouse
985          */
986          
987         /**
988          * Bind a function to the mouseover event of each matched element.
989          *
990          * @example $("p").mouseover( function() { alert("Hello"); } );
991          * @before <p>Hello</p>
992          * @result <p onmouseover="alert('Hello');">Hello</p>
993          *
994          * @name mouseover
995          * @type jQuery
996          * @param Function fn A function to bind to the mousedown event on each of the matched elements.
997          * @cat Events/Mouse
998          */
999
1000         /**
1001          * Trigger the mouseover event of each matched element. This causes all of the functions
1002          * that have been bound to thet mousedown event to be executed.
1003          *
1004          * @example $("p").mouseover();
1005          * @before <p onmouseover="alert('Hello');">Hello</p>
1006          * @result alert('Hello');
1007          *
1008          * @name mouseover
1009          * @type jQuery
1010          * @cat Events/Mouse
1011          */
1012
1013         var e = ("blur,focus,load,resize,scroll,unload,click,dblclick," +
1014                 "mousedown,mouseup,mousemove,mouseover,mouseout,change,select," + 
1015                 "submit,keydown,keypress,keyup,error").split(",");
1016
1017         // Go through all the event names, but make sure that
1018         // it is enclosed properly
1019         for ( var i = 0; i < e.length; i++ ) new function(){
1020                         
1021                 var o = e[i];
1022                 
1023                 // Handle event binding
1024                 jQuery.fn[o] = function(f){
1025                         return f ? this.bind(o, f) : this.trigger(o);
1026                 };
1027                         
1028         };
1029         
1030         // If Mozilla is used
1031         if ( jQuery.browser.mozilla || jQuery.browser.opera )
1032                 // Use the handy event callback
1033                 document.addEventListener( "DOMContentLoaded", jQuery.ready, false );
1034         
1035         // If IE is used, use the excellent hack by Matthias Miller
1036         // http://www.outofhanwell.com/blog/index.php?title=the_window_onload_problem_revisited
1037         else if ( jQuery.browser.msie ) {
1038         
1039                 // Only works if you document.write() it
1040                 document.write("<scr" + "ipt id=__ie_init defer=true " + 
1041                         "src=//:><\/script>");
1042         
1043                 // Use the defer script hack
1044                 var script = document.getElementById("__ie_init");
1045                 
1046                 // script does not exist if jQuery is loaded dynamically
1047                 if ( script ) 
1048                         script.onreadystatechange = function() {
1049                                 if ( this.readyState != "complete" ) return;
1050                                 this.parentNode.removeChild( this );
1051                                 jQuery.ready();
1052                         };
1053         
1054                 // Clear from memory
1055                 script = null;
1056         
1057         // If Safari  is used
1058         } else if ( jQuery.browser.safari )
1059                 // Continually check to see if the document.readyState is valid
1060                 jQuery.safariTimer = setInterval(function(){
1061                         // loaded and complete are both valid states
1062                         if ( document.readyState == "loaded" || 
1063                                 document.readyState == "complete" ) {
1064         
1065                                 // If either one are found, remove the timer
1066                                 clearInterval( jQuery.safariTimer );
1067                                 jQuery.safariTimer = null;
1068         
1069                                 // and execute any waiting functions
1070                                 jQuery.ready();
1071                         }
1072                 }, 10); 
1073
1074         // A fallback to window.onload, that will always work
1075         jQuery.event.add( window, "load", jQuery.ready );
1076         
1077 };
1078
1079 // Clean up after IE to avoid memory leaks
1080 if (jQuery.browser.msie)
1081         jQuery(window).one("unload", function() {
1082                 var global = jQuery.event.global;
1083                 for ( var type in global ) {
1084                         var els = global[type], i = els.length;
1085                         if ( i && type != 'unload' )
1086                                 do
1087                                         jQuery.event.remove(els[i-1], type);
1088                                 while (--i);
1089                 }
1090         });