src/event.js

   1 /*
   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.
   5  */
   6 jQuery.event = {
   7
   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 )
  12                         return;
  13
  14                 // For whatever reason, IE has trouble passing the window object
  15                 // around, causing it to be cloned in the process
  16                 if ( elem.setInterval && elem != window )
  17                         elem = window;
  18
  19                 // Make sure that the function being executed has a unique ID
  20                 if ( !handler.guid )
  21                         handler.guid = this.guid++;
  22
  23                 // if data is passed, bind to handler
  24                 if ( data !== undefined ) {
  25                         // Create temporary function pointer to original handler
  26                         var fn = handler;
  27
  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);
  32                         });
  33
  34                         // Store data in unique handler
  35                         handler.data = data;
  36                 }
  37
  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) :
  45                                         undefined;
  46                         });
  47                 // Add elem as a property of the handle function
  48                 // This is to prevent a memory leak with non-native
  49                 // event in IE.
  50                 handle.elem = elem;
  51
  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(".");
  57                         type = parts.shift();
  58                         handler.type = parts.sort().join(".");
  59
  60                         // Get the current list of functions bound to this event
  61                         var handlers = events[type];
  62
  63                         // Init the event handler queue
  64                         if (!handlers) {
  65                                 handlers = events[type] = {};
  66
  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);
  76                                 }
  77                         }
  78
  79                         // Add the function to the element's handler list
  80                         handlers[handler.guid] = handler;
  81
  82                         // Keep track of which events have been used, for global triggering
  83                         jQuery.event.global[type] = true;
  84                 });
  85
  86                 // Nullify elem to prevent memory leaks in IE
  87                 elem = null;
  88         },
  89
  90         guid: 1,
  91         global: {},
  92
  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 )
  97                         return;
  98
  99                 var events = jQuery.data(elem, "events"), ret, index;
 100
 101                 if ( events ) {
 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 || "") );
 106                         else {
 107                                 // types is actually an event object here
 108                                 if ( types.type ) {
 109                                         handler = types.handler;
 110                                         types = types.type;
 111                                 }
 112
 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(".*\\.") + "(\\.|$)");
 120
 121                                         if ( events[type] ) {
 122                                                 // remove the given handler for the given type
 123                                                 if ( handler )
 124                                                         delete events[type][handler.guid];
 125
 126                                                 // remove all handlers for the given type
 127                                                 else
 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];
 132
 133                                                 // remove generic event handler if no more handlers exist
 134                                                 for ( ret in events[type] ) break;
 135                                                 if ( !ret ) {
 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"));
 141                                                         }
 142                                                         ret = null;
 143                                                         delete events[type];
 144                                                 }
 145                                         }
 146                                 });
 147                         }
 148
 149                         // Remove the expando if it's no longer used
 150                         for ( ret in events ) break;
 151                         if ( !ret ) {
 152                                 var handle = jQuery.data( elem, "handle" );
 153                                 if ( handle ) handle.elem = null;
 154                                 jQuery.removeData( elem, "events" );
 155                                 jQuery.removeData( elem, "handle" );
 156                         }
 157                 }
 158         },
 159
 160         trigger: function(type, data, elem, donative, extra) {
 161                 // Clone the incoming data, if any
 162                 data = jQuery.makeArray(data);
 163
 164                 if ( type.indexOf("!") >= 0 ) {
 165                         type = type.slice(0, -1);
 166                         var exclusive = true;
 167                 }
 168
 169                 // Handle a global trigger
 170                 if ( !elem ) {
 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 );
 176                                 });
 177
 178                 // Handle triggering a single element
 179                 } else {
 180                         // don't do events on text and comment nodes
 181                         if ( elem.nodeType == 3 || elem.nodeType == 8 )
 182                                 return undefined;
 183
 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;
 187
 188                         // Pass along a fake event
 189                         if ( event ) {
 190                                 data.unshift({
 191                                         type: type,
 192                                         target: elem,
 193                                         preventDefault: function(){},
 194                                         stopPropagation: function(){},
 195                                         stopImmediatePropagation:stopImmediatePropagation,
 196                                         timeStamp: now()
 197                                 });
 198                                 data[0][expando] = true; // no need to fix fake event
 199                         }
 200
 201                         // Enforce the right trigger type
 202                         data[0].type = type;
 203                         if ( exclusive )
 204                                 data[0].exclusive = true;
 205
 206                         // Trigger the event, it is assumed that "handle" is a function
 207                         var handle = jQuery.data(elem, "handle");
 208                         if ( handle )
 209                                 val = handle.apply( elem, data );
 210
 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 )
 213                                 val = false;
 214
 215                         // Extra functions don't get the custom event object
 216                         if ( event )
 217                                 data.shift();
 218
 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 )
 225                                         val = ret;
 226                         }
 227
 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;
 231                                 try {
 232                                         elem[ type ]();
 233                                 // prevent IE from throwing an error for some hidden elements
 234                                 } catch (e) {}
 235                         }
 236
 237                         this.triggered = false;
 238                 }
 239
 240                 return val;
 241         },
 242
 243         handle: function(event) {
 244                 // returned undefined or false
 245                 var val, ret, namespace, all, handlers;
 246
 247                 event = arguments[0] = jQuery.event.fix( event || window.event );
 248
 249                 // Namespaced event handlers
 250                 namespace = event.type.split(".");
 251                 event.type = namespace.shift();
 252
 253                 // Cache this now, all = true means, any handler
 254                 all = !namespace.length && !event.exclusive;
 255
 256                 namespace = RegExp("(^|\\.)" + namespace.sort().join(".*\\.") + "(\\.|$)");
 257
 258                 handlers = ( jQuery.data(this, "events") || {} )[event.type];
 259
 260                 for ( var j in handlers ) {
 261                         var handler = handlers[j];
 262
 263                         // Filter the functions by class
 264                         if ( all || namespace.test(handler.type) ) {
 265                                 // Pass in a reference to the handler function itself
 266                                 // So that we can later remove it
 267                                 event.handler = handler;
 268                                 event.data = handler.data;
 269
 270                                 ret = handler.apply( this, arguments );
 271
 272                                 if ( val !== false )
 273                                         val = ret;
 274
 275                                 if ( ret === false ) {
 276                                         event.preventDefault();
 277                                         event.stopPropagation();
 278                                 }
 279
 280                                 if( event._sip )
 281                                         break;
 282
 283                         }
 284                 }
 285
 286                 return val;
 287         },
 288
 289         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(" "),
 290
 291         fix: function(event) {
 292                 if ( event[expando] )
 293                         return event;
 294
 295                 // store a copy of the original event object
 296                 // and "clone" to set read-only properties
 297                 var originalEvent = event;
 298                 event = { originalEvent: originalEvent };
 299
 300                 for ( var i = this.props.length, prop; i; ){
 301                         prop = this.props[ --i ];
 302                         event[ prop ] = originalEvent[ prop ];
 303                 }
 304
 305                 // Mark it as fixed
 306                 event[expando] = true;
 307
 308                 // add preventDefault and stopPropagation since
 309                 // they will not work on the clone
 310                 event.preventDefault = function() {
 311                         // if preventDefault exists run it on the original event
 312                         if (originalEvent.preventDefault)
 313                                 originalEvent.preventDefault();
 314                         // otherwise set the returnValue property of the original event to false (IE)
 315                         originalEvent.returnValue = false;
 316                 };
 317                 event.stopPropagation = function() {
 318                         // if stopPropagation exists run it on the original event
 319                         if (originalEvent.stopPropagation)
 320                                 originalEvent.stopPropagation();
 321                         // otherwise set the cancelBubble property of the original event to true (IE)
 322                         originalEvent.cancelBubble = true;
 323                 };
 324
 325                 event.stopImmediatePropagation = stopImmediatePropagation;
 326
 327                 // Fix timeStamp
 328                 event.timeStamp = event.timeStamp || now();
 329
 330                 // Fix target property, if necessary
 331                 if ( !event.target )
 332                         event.target = event.srcElement || document; // Fixes #1925 where srcElement might not be defined either
 333
 334                 // check if target is a textnode (safari)
 335                 if ( event.target.nodeType == 3 )
 336                         event.target = event.target.parentNode;
 337
 338                 // Add relatedTarget, if necessary
 339                 if ( !event.relatedTarget && event.fromElement )
 340                         event.relatedTarget = event.fromElement == event.target ? event.toElement : event.fromElement;
 341
 342                 // Calculate pageX/Y if missing and clientX/Y available
 343                 if ( event.pageX == null && event.clientX != null ) {
 344                         var doc = document.documentElement, body = document.body;
 345                         event.pageX = event.clientX + (doc && doc.scrollLeft || body && body.scrollLeft || 0) - (doc.clientLeft || 0);
 346                         event.pageY = event.clientY + (doc && doc.scrollTop || body && body.scrollTop || 0) - (doc.clientTop || 0);
 347                 }
 348
 349                 // Add which for key events
 350                 if ( !event.which && ((event.charCode || event.charCode === 0) ? event.charCode : event.keyCode) )
 351                         event.which = event.charCode || event.keyCode;
 352
 353                 // Add metaKey to non-Mac browsers (use ctrl for PC's and Meta for Macs)
 354                 if ( !event.metaKey && event.ctrlKey )
 355                         event.metaKey = event.ctrlKey;
 356
 357                 // Add which for click: 1 == left; 2 == middle; 3 == right
 358                 // Note: button is not normalized, so don't use it
 359                 if ( !event.which && event.button )
 360                         event.which = (event.button & 1 ? 1 : ( event.button & 2 ? 3 : ( event.button & 4 ? 2 : 0 ) ));
 361
 362                 return event;
 363         },
 364
 365         proxy: function( fn, proxy ){
 366                 // Set the guid of unique handler to the same of original handler, so it can be removed
 367                 proxy.guid = fn.guid = fn.guid || proxy.guid || this.guid++;
 368                 // So proxy can be declared as an argument
 369                 return proxy;
 370         },
 371
 372         special: {
 373                 ready: {
 374                         // Make sure the ready event is setup
 375                         setup: bindReady,
 376                         teardown: function() {}
 377                 }
 378         }
 379 };
 380
 381 function stopImmediatePropagation(){
 382         this._sip = 1;
 383         this.stopPropagation();
 384 }
 385
 386 // Checks if an event happened on an element within another element
 387 // Used in jQuery.event.special.mouseenter and mouseleave handlers
 388 var withinElement = function(event) {
 389         // Check if mouse(over|out) are still within the same parent element
 390         var parent = event.relatedTarget;
 391         // Traverse up the tree
 392         while ( parent && parent != this )
 393                 try { parent = parent.parentNode; }
 394                 catch(e) { parent = this; }
 395
 396         if( parent != this ){
 397                 // set the correct event type
 398                 event.type = event.data;
 399                 // handle event if we actually just moused on to a non sub-element
 400                 jQuery.event.handle.apply( this, arguments );
 401         }
 402 };
 403
 404 jQuery.each({
 405         mouseover: 'mouseenter',
 406         mouseout: 'mouseleave'
 407 }, function( orig, fix ){
 408         jQuery.event.special[ fix ] = {
 409                 setup: function(){
 410                         jQuery.event.add( this, orig, withinElement, fix );
 411                 },
 412                 teardown: function(){
 413                         jQuery.event.remove( this, orig, withinElement );
 414                 }
 415         };
 416 });
 417
 418 jQuery.fn.extend({
 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 );
 422                 });
 423         },
 424
 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 );
 429                 });
 430                 return this.each(function(){
 431                         jQuery.event.add( this, type, one, fn && data);
 432                 });
 433         },
 434
 435         unbind: function( type, fn ) {
 436                 return this.each(function(){
 437                         jQuery.event.remove( this, type, fn );
 438                 });
 439         },
 440
 441         trigger: function( type, data, fn ) {
 442                 return this.each(function(){
 443                         jQuery.event.trigger( type, data, this, true, fn );
 444                 });
 445         },
 446
 447         triggerHandler: function( type, data, fn ) {
 448                 return this[0] && jQuery.event.trigger( type, data, this[0], false, fn );
 449         },
 450
 451         toggle: function( fn ) {
 452                 // Save reference to arguments for access in closure
 453                 var args = arguments, i = 1;
 454
 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++] );
 458
 459                 return this.click( jQuery.event.proxy( fn, function(event) {
 460                         // Figure out which function to execute
 461                         this.lastToggle = ( this.lastToggle || 0 ) % i;
 462
 463                         // Make sure that clicks stop
 464                         event.preventDefault();
 465
 466                         // and execute the function
 467                         return args[ this.lastToggle++ ].apply( this, arguments ) || false;
 468                 }));
 469         },
 470
 471         hover: function(fnOver, fnOut) {
 472                 return this.mouseenter(fnOver).mouseleave(fnOut);
 473         },
 474
 475         ready: function(fn) {
 476                 // Attach the listeners
 477                 bindReady();
 478
 479                 // If the DOM is already ready
 480                 if ( jQuery.isReady )
 481                         // Execute the function immediately
 482                         fn.call( document, jQuery );
 483
 484                 // Otherwise, remember the function for later
 485                 else
 486                         // Add the function to the wait list
 487                         jQuery.readyList.push( function() { return fn.call(this, jQuery); } );
 488
 489                 return this;
 490         }
 491 });
 492
 493 jQuery.extend({
 494         isReady: false,
 495         readyList: [],
 496         // Handle when the DOM is ready
 497         ready: function() {
 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;
 502
 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 );
 508                                 });
 509
 510                                 // Reset the list of functions
 511                                 jQuery.readyList = null;
 512                         }
 513
 514                         // Trigger any bound ready events
 515                         jQuery(document).triggerHandler("ready");
 516                 }
 517         }
 518 });
 519
 520 var readyBound = false;
 521
 522 function bindReady(){
 523         if ( readyBound ) return;
 524         readyBound = true;
 525
 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 );
 531                         jQuery.ready();
 532                 }, false );
 533
 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 );
 541                                 jQuery.ready();
 542                         }
 543                 });
 544
 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;
 549
 550                         try {
 551                                 // If IE is used, use the trick by Diego Perini
 552                                 // http://javascript.nwbox.com/IEContentLoaded/
 553                                 document.documentElement.doScroll("left");
 554                         } catch( error ) {
 555                                 setTimeout( arguments.callee, 0 );
 556                                 return;
 557                         }
 558
 559                         // and execute any waiting functions
 560                         jQuery.ready();
 561                 })();
 562         }
 563
 564         // A fallback to window.onload, that will always work
 565         jQuery.event.add( window, "load", jQuery.ready );
 566 }
 567
 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){
 571
 572         // Handle event binding
 573         jQuery.fn[name] = function(fn){
 574                 return fn ? this.bind(name, fn) : this.trigger(name);
 575         };
 576 });
 577
 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 )
 583                 // Skip the window
 584                 if ( id != 1 && jQuery.cache[ id ].handle )
 585                         jQuery.event.remove( jQuery.cache[ id ].handle.elem );
 586 });