2 * A number of helper functions used for managing events.
3 * Many of the ideas behind this code originated from
4 * Dean Edwards' addEvent library.
8 // Bind an event to an element
9 // Original by Dean Edwards
10 add: function(elem, types, handler, data) {
11 if ( elem.nodeType == 3 || elem.nodeType == 8 )
14 // For whatever reason, IE has trouble passing the window object
15 // around, causing it to be cloned in the process
16 if ( jQuery.browser.msie && elem.setInterval )
19 // Make sure that the function being executed has a unique ID
21 handler.guid = this.guid++;
23 // if data is passed, bind to handler
24 if ( data !== undefined ) {
25 // Create temporary function pointer to original handler
28 // Create unique handler function, wrapped around original handler
29 handler = this.proxy( fn, function() {
30 // Pass arguments and context to original handler
31 return fn.apply(this, arguments);
34 // Store data in unique handler
38 // Init the element's event structure
39 var events = jQuery.data(elem, "events") || jQuery.data(elem, "events", {}),
40 handle = jQuery.data(elem, "handle") || jQuery.data(elem, "handle", function(){
41 // Handle the second event of a trigger and when
42 // an event is called after a page has unloaded
43 return typeof jQuery !== "undefined" && !jQuery.event.triggered ?
44 jQuery.event.handle.apply(arguments.callee.elem, arguments) :
47 // Add elem as a property of the handle function
48 // This is to prevent a memory leak with non-native
52 // Handle multiple events separated by a space
53 // jQuery(...).bind("mouseover mouseout", fn);
54 jQuery.each(types.split(/\s+/), function(index, type) {
55 // Namespaced event handlers
56 var parts = type.split(".");
58 handler.type = parts.sort().join(".");
60 // Get the current list of functions bound to this event
61 var handlers = events[type];
63 // Init the event handler queue
65 handlers = events[type] = {};
67 // Check for a special event handler
68 // Only use addEventListener/attachEvent if the special
69 // events handler returns false
70 if ( !jQuery.event.special[type] || jQuery.event.special[type].setup.call(elem,data) === false ) {
71 // Bind the global event handler to the element
72 if (elem.addEventListener)
73 elem.addEventListener(type, handle, false);
74 else if (elem.attachEvent)
75 elem.attachEvent("on" + type, handle);
79 // Add the function to the element's handler list
80 handlers[handler.guid] = handler;
82 // Keep track of which events have been used, for global triggering
83 jQuery.event.global[type] = true;
86 // Nullify elem to prevent memory leaks in IE
93 // Detach an event or set of events from an element
94 remove: function(elem, types, handler) {
95 // don't do events on text and comment nodes
96 if ( elem.nodeType == 3 || elem.nodeType == 8 )
99 var events = jQuery.data(elem, "events"), ret, index;
102 // Unbind all events for the element
103 if ( types === undefined || (typeof types === "string" && types.charAt(0) == ".") )
104 for ( var type in events )
105 this.remove( elem, type + (types || "") );
107 // types is actually an event object here
109 handler = types.handler;
113 // Handle multiple events seperated by a space
114 // jQuery(...).unbind("mouseover mouseout", fn);
115 jQuery.each(types.split(/\s+/), function(index, type){
116 // Namespaced event handlers
117 var namespace = type.split(".");
118 type = namespace.shift();
119 namespace = RegExp(namespace.sort().join(".*\\.") + "(\\.|$)");
121 if ( events[type] ) {
122 // remove the given handler for the given type
124 delete events[type][handler.guid];
126 // remove all handlers for the given type
128 for ( handler in events[type] )
129 // Handle the removal of namespaced events
130 if ( namespace.test(events[type][handler].type) )
131 delete events[type][handler];
133 // remove generic event handler if no more handlers exist
134 for ( ret in events[type] ) break;
136 if ( !jQuery.event.special[type] || jQuery.event.special[type].teardown.call(elem) === false ) {
137 if (elem.removeEventListener)
138 elem.removeEventListener(type, jQuery.data(elem, "handle"), false);
139 else if (elem.detachEvent)
140 elem.detachEvent("on" + type, jQuery.data(elem, "handle"));
149 // Remove the expando if it's no longer used
150 for ( ret in events ) break;
152 var handle = jQuery.data( elem, "handle" );
153 if ( handle ) handle.elem = null;
154 jQuery.removeData( elem, "events" );
155 jQuery.removeData( elem, "handle" );
160 trigger: function(type, data, elem, donative, extra) {
161 // Clone the incoming data, if any
162 data = jQuery.makeArray(data);
164 if ( type.indexOf("!") >= 0 ) {
165 type = type.slice(0, -1);
166 var exclusive = true;
169 // Handle a global trigger
171 // Only trigger if we've ever bound an event for it
172 if ( this.global[type] )
173 jQuery.each( jQuery.cache, function(){
174 if ( this.events && this.events[type] )
175 jQuery.event.trigger( type, data, this.handle.elem );
178 // Handle triggering a single element
180 // don't do events on text and comment nodes
181 if ( elem.nodeType == 3 || elem.nodeType == 8 )
184 var val, ret, fn = jQuery.isFunction( elem[ type ] || null ),
185 // Check to see if we need to provide a fake event, or not
186 event = !data[0] || !data[0].preventDefault;
188 // Pass along a fake event
193 preventDefault: function(){},
194 stopPropagation: function(){},
195 stopImmediatePropagation:stopImmediatePropagation,
198 data[0][expando] = true; // no need to fix fake event
201 // Enforce the right trigger type
204 data[0].exclusive = true;
206 // Trigger the event, it is assumed that "handle" is a function
207 var handle = jQuery.data(elem, "handle");
209 val = handle.apply( elem, data );
211 // Handle triggering native .onfoo handlers (and on links since we don't call .click() for links)
212 if ( (!fn || (jQuery.nodeName(elem, 'a') && type == "click")) && elem["on"+type] && elem["on"+type].apply( elem, data ) === false )
215 // Extra functions don't get the custom event object
219 // Handle triggering of extra function
220 if ( extra && jQuery.isFunction( extra ) ) {
221 // call the extra function and tack the current return value on the end for possible inspection
222 ret = extra.apply( elem, val == null ? data : data.concat( val ) );
223 // if anything is returned, give it precedence and have it overwrite the previous value
224 if ( ret !== undefined )
228 // Trigger the native events (except for clicks on links)
229 if ( fn && donative !== false && val !== false && !(jQuery.nodeName(elem, 'a') && type == "click") ) {
230 this.triggered = true;
233 // prevent IE from throwing an error for some hidden elements
237 this.triggered = false;
243 handle: function(event) {
244 // returned undefined or false
245 var val, ret, namespace, all, handlers;
247 event = arguments[0] = jQuery.event.fix( event || window.event );
249 // Namespaced event handlers
250 namespace = event.type.split(".");
251 event.type = namespace.shift();
252 namespace = RegExp(namespace.sort().join(".*\\.") + "(\\.|$)");
253 // Cache this now, all = true means, any handler
254 all = !namespace && !event.exclusive;
256 handlers = ( jQuery.data(this, "events") || {} )[event.type];
258 for ( var j in handlers ) {
259 var handler = handlers[j];
261 // Filter the functions by class
262 if ( all || namespace.test(handler.type) ) {
263 // Pass in a reference to the handler function itself
264 // So that we can later remove it
265 event.handler = handler;
266 event.data = handler.data;
268 ret = handler.apply( this, arguments );
273 if ( ret === false ) {
274 event.preventDefault();
275 event.stopPropagation();
287 props: "altKey attrChange attrName bubbles button cancelable charCode clientX clientY ctrlKey currentTarget data detail eventPhase fromElement handler keyCode metaKey newValue originalTarget pageX pageY prevValue relatedNode relatedTarget screenX screenY shiftKey srcElement target timeStamp toElement type view wheelDelta which".split(" "),
289 fix: function(event) {
290 if ( event[expando] )
293 // store a copy of the original event object
294 // and "clone" to set read-only properties
295 var originalEvent = event;
296 event = { originalEvent: originalEvent };
298 for ( var i = this.props.length, prop; i; ){
299 prop = this.props[ --i ];
300 event[ prop ] = originalEvent[ prop ];
304 event[expando] = true;
306 // add preventDefault and stopPropagation since
307 // they will not work on the clone
308 event.preventDefault = function() {
309 // if preventDefault exists run it on the original event
310 if (originalEvent.preventDefault)
311 originalEvent.preventDefault();
312 // otherwise set the returnValue property of the original event to false (IE)
313 originalEvent.returnValue = false;
315 event.stopPropagation = function() {
316 // if stopPropagation exists run it on the original event
317 if (originalEvent.stopPropagation)
318 originalEvent.stopPropagation();
319 // otherwise set the cancelBubble property of the original event to true (IE)
320 originalEvent.cancelBubble = true;
323 event.stopImmediatePropagation = stopImmediatePropagation;
326 event.timeStamp = event.timeStamp || now();
328 // Fix target property, if necessary
330 event.target = event.srcElement || document; // Fixes #1925 where srcElement might not be defined either
332 // check if target is a textnode (safari)
333 if ( event.target.nodeType == 3 )
334 event.target = event.target.parentNode;
336 // Add relatedTarget, if necessary
337 if ( !event.relatedTarget && event.fromElement )
338 event.relatedTarget = event.fromElement == event.target ? event.toElement : event.fromElement;
340 // Calculate pageX/Y if missing and clientX/Y available
341 if ( event.pageX == null && event.clientX != null ) {
342 var doc = document.documentElement, body = document.body;
343 event.pageX = event.clientX + (doc && doc.scrollLeft || body && body.scrollLeft || 0) - (doc.clientLeft || 0);
344 event.pageY = event.clientY + (doc && doc.scrollTop || body && body.scrollTop || 0) - (doc.clientTop || 0);
347 // Add which for key events
348 if ( !event.which && ((event.charCode || event.charCode === 0) ? event.charCode : event.keyCode) )
349 event.which = event.charCode || event.keyCode;
351 // Add metaKey to non-Mac browsers (use ctrl for PC's and Meta for Macs)
352 if ( !event.metaKey && event.ctrlKey )
353 event.metaKey = event.ctrlKey;
355 // Add which for click: 1 == left; 2 == middle; 3 == right
356 // Note: button is not normalized, so don't use it
357 if ( !event.which && event.button )
358 event.which = (event.button & 1 ? 1 : ( event.button & 2 ? 3 : ( event.button & 4 ? 2 : 0 ) ));
363 proxy: function( fn, proxy ){
364 // Set the guid of unique handler to the same of original handler, so it can be removed
365 proxy.guid = fn.guid = fn.guid || proxy.guid || this.guid++;
366 // So proxy can be declared as an argument
372 // Make sure the ready event is setup
374 teardown: function() {}
379 function stopImmediatePropagation(){
381 this.stopPropagation();
384 if ( !jQuery.browser.msie ){
385 // Checks if an event happened on an element within another element
386 // Used in jQuery.event.special.mouseenter and mouseleave handlers
387 var withinElement = function(event) {
388 // Check if mouse(over|out) are still within the same parent element
389 var parent = event.relatedTarget;
390 // Traverse up the tree
391 while ( parent && parent != this )
392 try { parent = parent.parentNode; }
393 catch(e) { parent = this; }
395 if( parent != this ){
396 // set the correct event type
397 event.type = event.data;
398 // handle event if we actually just moused on to a non sub-element
399 jQuery.event.handle.apply( this, arguments );
404 mouseover: 'mouseenter',
405 mouseout: 'mouseleave'
406 }, function( orig, fix ){
407 jQuery.event.special[ fix ] = {
409 jQuery.event.add( this, orig, withinElement, fix );
411 teardown: function(){
412 jQuery.event.remove( this, orig, withinElement );
419 bind: function( type, data, fn ) {
420 return type == "unload" ? this.one(type, data, fn) : this.each(function(){
421 jQuery.event.add( this, type, fn || data, fn && data );
425 one: function( type, data, fn ) {
426 var one = jQuery.event.proxy( fn || data, function(event) {
427 jQuery(this).unbind(event, one);
428 return (fn || data).apply( this, arguments );
430 return this.each(function(){
431 jQuery.event.add( this, type, one, fn && data);
435 unbind: function( type, fn ) {
436 return this.each(function(){
437 jQuery.event.remove( this, type, fn );
441 trigger: function( type, data, fn ) {
442 return this.each(function(){
443 jQuery.event.trigger( type, data, this, true, fn );
447 triggerHandler: function( type, data, fn ) {
448 return this[0] && jQuery.event.trigger( type, data, this[0], false, fn );
451 toggle: function( fn ) {
452 // Save reference to arguments for access in closure
453 var args = arguments, i = 1;
455 // link all the functions, so any of them can unbind this click handler
456 while( i < args.length )
457 jQuery.event.proxy( fn, args[i++] );
459 return this.click( jQuery.event.proxy( fn, function(event) {
460 // Figure out which function to execute
461 this.lastToggle = ( this.lastToggle || 0 ) % i;
463 // Make sure that clicks stop
464 event.preventDefault();
466 // and execute the function
467 return args[ this.lastToggle++ ].apply( this, arguments ) || false;
471 hover: function(fnOver, fnOut) {
472 return this.mouseenter(fnOver).mouseleave(fnOut);
475 ready: function(fn) {
476 // Attach the listeners
479 // If the DOM is already ready
480 if ( jQuery.isReady )
481 // Execute the function immediately
482 fn.call( document, jQuery );
484 // Otherwise, remember the function for later
486 // Add the function to the wait list
487 jQuery.readyList.push( function() { return fn.call(this, jQuery); } );
496 // Handle when the DOM is ready
498 // Make sure that the DOM is not already loaded
499 if ( !jQuery.isReady ) {
500 // Remember that the DOM is ready
501 jQuery.isReady = true;
503 // If there are functions bound, to execute
504 if ( jQuery.readyList ) {
505 // Execute all of them
506 jQuery.each( jQuery.readyList, function(){
507 this.call( document );
510 // Reset the list of functions
511 jQuery.readyList = null;
514 // Trigger any bound ready events
515 jQuery(document).triggerHandler("ready");
520 var readyBound = false;
522 function bindReady(){
523 if ( readyBound ) return;
526 // Mozilla, Opera and webkit nightlies currently support this event
527 if ( document.addEventListener ) {
528 // Use the handy event callback
529 document.addEventListener( "DOMContentLoaded", function(){
530 document.removeEventListener( "DOMContentLoaded", arguments.callee, false );
534 // If IE event model is used
535 } else if ( document.attachEvent ) {
536 // ensure firing before onload,
537 // maybe late but safe also for iframes
538 document.attachEvent("onreadystatechange", function(){
539 if ( document.readyState === "complete" ) {
540 document.detachEvent( "onreadystatechange", arguments.callee );
545 // If IE and not an iframe
546 // continually check to see if the document is ready
547 if ( document.documentElement.doScroll && !window.frameElement ) (function(){
548 if ( jQuery.isReady ) return;
551 // If IE is used, use the trick by Diego Perini
552 // http://javascript.nwbox.com/IEContentLoaded/
553 document.documentElement.doScroll("left");
555 setTimeout( arguments.callee, 0 );
559 // and execute any waiting functions
564 // A fallback to window.onload, that will always work
565 jQuery.event.add( window, "load", jQuery.ready );
568 jQuery.each( ("blur,focus,load,resize,scroll,unload,click,dblclick," +
569 "mousedown,mouseup,mousemove,mouseover,mouseout,mouseenter,mouseleave," +
570 "change,select,submit,keydown,keypress,keyup,error").split(","), function(i, name){
572 // Handle event binding
573 jQuery.fn[name] = function(fn){
574 return fn ? this.bind(name, fn) : this.trigger(name);
578 // Prevent memory leaks in IE
579 // And prevent errors on refresh with events like mouseover in other browsers
580 // Window isn't included so as not to unbind existing unload events
581 jQuery( window ).bind( 'unload', function(){
582 for ( var id in jQuery.cache )
584 if ( id != 1 && jQuery.cache[ id ].handle )
585 jQuery.event.remove( jQuery.cache[ id ].handle.elem );