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 ( jQuery.browser.msie && elem.setInterval )
  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 if ( !jQuery.browser.msie ){
 387         // Checks if an event happened on an element within another element
 388         // Used in jQuery.event.special.mouseenter and mouseleave handlers
 389         var withinElement = function(event) {
 390                 // Check if mouse(over|out) are still within the same parent element
 391                 var parent = event.relatedTarget;
 392                 // Traverse up the tree
 393                 while ( parent && parent != this )
 394                         try { parent = parent.parentNode; }
 395                         catch(e) { parent = this; }
 396
 397                 if( parent != this ){
 398                         // set the correct event type
 399                         event.type = event.data;
 400                         // handle event if we actually just moused on to a non sub-element
 401                         jQuery.event.handle.apply( this, arguments );
 402                 }
 403         };
 404
 405         jQuery.each({
 406                 mouseover: 'mouseenter',
 407                 mouseout: 'mouseleave'
 408         }, function( orig, fix ){
 409                 jQuery.event.special[ fix ] = {
 410                         setup: function(){
 411                                 jQuery.event.add( this, orig, withinElement, fix );
 412                         },
 413                         teardown: function(){
 414                                 jQuery.event.remove( this, orig, withinElement );
 415                         }
 416                 };
 417         });
 418 }
 419
 420 jQuery.fn.extend({
 421         bind: function( type, data, fn ) {
 422                 return type == "unload" ? this.one(type, data, fn) : this.each(function(){
 423                         jQuery.event.add( this, type, fn || data, fn && data );
 424                 });
 425         },
 426
 427         one: function( type, data, fn ) {
 428                 var one = jQuery.event.proxy( fn || data, function(event) {
 429                         jQuery(this).unbind(event, one);
 430                         return (fn || data).apply( this, arguments );
 431                 });
 432                 return this.each(function(){
 433                         jQuery.event.add( this, type, one, fn && data);
 434                 });
 435         },
 436
 437         unbind: function( type, fn ) {
 438                 return this.each(function(){
 439                         jQuery.event.remove( this, type, fn );
 440                 });
 441         },
 442
 443         trigger: function( type, data, fn ) {
 444                 return this.each(function(){
 445                         jQuery.event.trigger( type, data, this, true, fn );
 446                 });
 447         },
 448
 449         triggerHandler: function( type, data, fn ) {
 450                 return this[0] && jQuery.event.trigger( type, data, this[0], false, fn );
 451         },
 452
 453         toggle: function( fn ) {
 454                 // Save reference to arguments for access in closure
 455                 var args = arguments, i = 1;
 456
 457                 // link all the functions, so any of them can unbind this click handler
 458                 while( i < args.length )
 459                         jQuery.event.proxy( fn, args[i++] );
 460
 461                 return this.click( jQuery.event.proxy( fn, function(event) {
 462                         // Figure out which function to execute
 463                         this.lastToggle = ( this.lastToggle || 0 ) % i;
 464
 465                         // Make sure that clicks stop
 466                         event.preventDefault();
 467
 468                         // and execute the function
 469                         return args[ this.lastToggle++ ].apply( this, arguments ) || false;
 470                 }));
 471         },
 472
 473         hover: function(fnOver, fnOut) {
 474                 return this.mouseenter(fnOver).mouseleave(fnOut);
 475         },
 476
 477         ready: function(fn) {
 478                 // Attach the listeners
 479                 bindReady();
 480
 481                 // If the DOM is already ready
 482                 if ( jQuery.isReady )
 483                         // Execute the function immediately
 484                         fn.call( document, jQuery );
 485
 486                 // Otherwise, remember the function for later
 487                 else
 488                         // Add the function to the wait list
 489                         jQuery.readyList.push( function() { return fn.call(this, jQuery); } );
 490
 491                 return this;
 492         }
 493 });
 494
 495 jQuery.extend({
 496         isReady: false,
 497         readyList: [],
 498         // Handle when the DOM is ready
 499         ready: function() {
 500                 // Make sure that the DOM is not already loaded
 501                 if ( !jQuery.isReady ) {
 502                         // Remember that the DOM is ready
 503                         jQuery.isReady = true;
 504
 505                         // If there are functions bound, to execute
 506                         if ( jQuery.readyList ) {
 507                                 // Execute all of them
 508                                 jQuery.each( jQuery.readyList, function(){
 509                                         this.call( document );
 510                                 });
 511
 512                                 // Reset the list of functions
 513                                 jQuery.readyList = null;
 514                         }
 515
 516                         // Trigger any bound ready events
 517                         jQuery(document).triggerHandler("ready");
 518                 }
 519         }
 520 });
 521
 522 var readyBound = false;
 523
 524 function bindReady(){
 525         if ( readyBound ) return;
 526         readyBound = true;
 527
 528         // Mozilla, Opera and webkit nightlies currently support this event
 529         if ( document.addEventListener ) {
 530                 // Use the handy event callback
 531                 document.addEventListener( "DOMContentLoaded", function(){
 532                         document.removeEventListener( "DOMContentLoaded", arguments.callee, false );
 533                         jQuery.ready();
 534                 }, false );
 535
 536         // If IE event model is used
 537         } else if ( document.attachEvent ) {
 538                 // ensure firing before onload,
 539                 // maybe late but safe also for iframes
 540                 document.attachEvent("onreadystatechange", function(){
 541                         if ( document.readyState === "complete" ) {
 542                                 document.detachEvent( "onreadystatechange", arguments.callee );
 543                                 jQuery.ready();
 544                         }
 545                 });
 546
 547                 // If IE and not an iframe
 548                 // continually check to see if the document is ready
 549                 if ( document.documentElement.doScroll && !window.frameElement ) (function(){
 550                         if ( jQuery.isReady ) return;
 551
 552                         try {
 553                                 // If IE is used, use the trick by Diego Perini
 554                                 // http://javascript.nwbox.com/IEContentLoaded/
 555                                 document.documentElement.doScroll("left");
 556                         } catch( error ) {
 557                                 setTimeout( arguments.callee, 0 );
 558                                 return;
 559                         }
 560
 561                         // and execute any waiting functions
 562                         jQuery.ready();
 563                 })();
 564         }
 565
 566         // A fallback to window.onload, that will always work
 567         jQuery.event.add( window, "load", jQuery.ready );
 568 }
 569
 570 jQuery.each( ("blur,focus,load,resize,scroll,unload,click,dblclick," +
 571         "mousedown,mouseup,mousemove,mouseover,mouseout,mouseenter,mouseleave," +
 572         "change,select,submit,keydown,keypress,keyup,error").split(","), function(i, name){
 573
 574         // Handle event binding
 575         jQuery.fn[name] = function(fn){
 576                 return fn ? this.bind(name, fn) : this.trigger(name);
 577         };
 578 });
 579
 580 // Prevent memory leaks in IE
 581 // And prevent errors on refresh with events like mouseover in other browsers
 582 // Window isn't included so as not to unbind existing unload events
 583 jQuery( window ).bind( 'unload', function(){
 584         for ( var id in jQuery.cache )
 585                 // Skip the window
 586                 if ( id != 1 && jQuery.cache[ id ].handle )
 587                         jQuery.event.remove( jQuery.cache[ id ].handle.elem );
 588 });