src/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, types, handler, data) {
  11                 if ( element.nodeType == 3 || element.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 && element.setInterval != undefined )
  17                         element = 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 = 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                         // Set the guid of unique handler to the same of original handler, so it can be removed
  38                         handler.guid = fn.guid;
  39                 }
  40
  41                 // Init the element's event structure
  42                 var events = jQuery.data(element, "events") || jQuery.data(element, "events", {}),
  43                         handle = jQuery.data(element, "handle") || jQuery.data(element, "handle", function(){
  44                                 // returned undefined or false
  45                                 var val;
  46
  47                                 // Handle the second event of a trigger and when
  48                                 // an event is called after a page has unloaded
  49                                 if ( typeof jQuery == "undefined" || jQuery.event.triggered )
  50                                         return val;
  51
  52                                 val = jQuery.event.handle.apply(element, arguments);
  53
  54                                 return val;
  55                         });
  56
  57                         // Handle multiple events seperated by a space
  58                         // jQuery(...).bind("mouseover mouseout", fn);
  59                         jQuery.each(types.split(/\s+/), function(index, type) {
  60                                 // Namespaced event handlers
  61                                 var parts = type.split(".");
  62                                 type = parts[0];
  63                                 handler.type = parts[1];
  64
  65                                 // Get the current list of functions bound to this event
  66                                 var handlers = events[type];
  67
  68                                 // Init the event handler queue
  69                                 if (!handlers) {
  70                                         handlers = events[type] = {};
  71
  72                                         // Check for a special event handler
  73                                         // Only use addEventListener/attachEvent if the special
  74                                         // events handler returns false
  75                                         if ( !jQuery.event.special[type] || jQuery.event.special[type].setup.call(element) === false ) {
  76                                                 // Bind the global event handler to the element
  77                                                 if (element.addEventListener)
  78                                                         element.addEventListener(type, handle, false);
  79                                                 else if (element.attachEvent)
  80                                                         element.attachEvent("on" + type, handle);
  81                                         }
  82                                 }
  83
  84                                 // Add the function to the element's handler list
  85                                 handlers[handler.guid] = handler;
  86
  87                                 // Keep track of which events have been used, for global triggering
  88                                 jQuery.event.global[type] = true;
  89                         });
  90         },
  91
  92         guid: 1,
  93         global: {},
  94
  95         // Detach an event or set of events from an element
  96         remove: function(element, types, handler) {
  97                 // don't do events on text and comment nodes
  98                 if ( element.nodeType == 3 || element.nodeType == 8 )
  99                         return;
 100
 101                 var events = jQuery.data(element, "events"), ret, index;
 102
 103                 if ( events ) {
 104                         // Unbind all events for the element
 105                         if ( !types )
 106                                 for ( var type in events )
 107                                         this.remove( element, type );
 108                         else {
 109                                 // types is actually an event object here
 110                                 if ( types.type ) {
 111                                         handler = types.handler;
 112                                         types = types.type;
 113                                 }
 114
 115                                 // Handle multiple events seperated by a space
 116                                 // jQuery(...).unbind("mouseover mouseout", fn);
 117                                 jQuery.each(types.split(/\s+/), function(index, type){
 118                                         // Namespaced event handlers
 119                                         var parts = type.split(".");
 120                                         type = parts[0];
 121
 122                                         if ( events[type] ) {
 123                                                 // remove the given handler for the given type
 124                                                 if ( handler )
 125                                                         delete events[type][handler.guid];
 126
 127                                                 // remove all handlers for the given type
 128                                                 else
 129                                                         for ( handler in events[type] )
 130                                                                 // Handle the removal of namespaced events
 131                                                                 if ( !parts[1] || events[type][handler].type == parts[1] )
 132                                                                         delete events[type][handler];
 133
 134                                                 // remove generic event handler if no more handlers exist
 135                                                 for ( ret in events[type] ) break;
 136                                                 if ( !ret ) {
 137                                                         if ( !jQuery.event.special[type] || jQuery.event.special[type].teardown.call(this, element) === false ) {
 138                                                                 if (element.removeEventListener)
 139                                                                         element.removeEventListener(type, jQuery.data(element, "handle"), false);
 140                                                                 else if (element.detachEvent)
 141                                                                         element.detachEvent("on" + type, jQuery.data(element, "handle"));
 142                                                         }
 143                                                         ret = null;
 144                                                         delete events[type];
 145                                                 }
 146                                         }
 147                                 });
 148                         }
 149
 150                         // Remove the expando if it's no longer used
 151                         for ( ret in events ) break;
 152                         if ( !ret ) {
 153                                 jQuery.removeData( element, "events" );
 154                                 jQuery.removeData( element, "handle" );
 155                         }
 156                 }
 157         },
 158
 159         trigger: function(type, data, element, donative, extra) {
 160                 // Clone the incoming data, if any
 161                 data = jQuery.makeArray(data || []);
 162
 163                 // Handle a global trigger
 164                 if ( !element ) {
 165                         // Only trigger if we've ever bound an event for it
 166                         if ( this.global[type] )
 167                                 jQuery("*").add([window, document]).trigger(type, data);
 168
 169                 // Handle triggering a single element
 170                 } else {
 171                         // don't do events on text and comment nodes
 172                         if ( element.nodeType == 3 || element.nodeType == 8 )
 173                                 return;
 174
 175                         var val, ret, fn = jQuery.isFunction( element[ type ] || null ),
 176                                 // Check to see if we need to provide a fake event, or not
 177                                 event = !data[0] || !data[0].preventDefault;
 178
 179                         // Pass along a fake event
 180                         if ( event )
 181                                 data.unshift( this.fix({ type: type, target: element }) );
 182
 183                         // Enforce the right trigger type
 184                         data[0].type = type;
 185
 186                         // Trigger the event
 187                         if ( jQuery.isFunction( jQuery.data(element, "handle") ) )
 188                                 val = jQuery.data(element, "handle").apply( element, data );
 189
 190                         // Handle triggering native .onfoo handlers
 191                         if ( !fn && element["on"+type] && element["on"+type].apply( element, data ) === false )
 192                                 val = false;
 193
 194                         // Extra functions don't get the custom event object
 195                         if ( event )
 196                                 data.shift();
 197
 198                         // Handle triggering of extra function
 199                         if ( extra ) {
 200                                 // call the extra function and tack the current return value on the end for possible inspection
 201                                 var ret = extra.apply( element, data.concat( val ) );
 202                                 // if anything is returned, give it precedence and have it overwrite the previous value
 203                                 if (ret !== undefined)
 204                                         val = ret;
 205                         }
 206
 207                         // Trigger the native events (except for clicks on links)
 208                         if ( fn && donative !== false && val !== false && !(jQuery.nodeName(element, 'a') && type == "click") ) {
 209                                 this.triggered = true;
 210                                 try {
 211                                         element[ type ]();
 212                                 // prevent IE from throwing an error for some hidden elements
 213                                 } catch (e) {}
 214                         }
 215
 216                         this.triggered = false;
 217                 }
 218
 219                 return val;
 220         },
 221
 222         handle: function(event) {
 223                 // returned undefined or false
 224                 var val;
 225
 226                 // Empty object is for triggered events with no data
 227                 event = jQuery.event.fix( event || window.event || {} );
 228
 229                 // Namespaced event handlers
 230                 var parts = event.type.split(".");
 231                 event.type = parts[0];
 232
 233                 var handlers = jQuery.data(this, "events") && jQuery.data(this, "events")[event.type], args = Array.prototype.slice.call( arguments, 1 );
 234                 args.unshift( event );
 235
 236                 for ( var j in handlers ) {
 237                         var handler = handlers[j];
 238                         // Pass in a reference to the handler function itself
 239                         // So that we can later remove it
 240                         args[0].handler = handler;
 241                         args[0].data = handler.data;
 242
 243                         // Filter the functions by class
 244                         if ( !parts[1] || handler.type == parts[1] ) {
 245                                 var ret = handler.apply( this, args );
 246
 247                                 if ( val !== false )
 248                                         val = ret;
 249
 250                                 if ( ret === false ) {
 251                                         event.preventDefault();
 252                                         event.stopPropagation();
 253                                 }
 254                         }
 255                 }
 256
 257                 // Clean up added properties in IE to prevent memory leak
 258                 if (jQuery.browser.msie)
 259                         event.target = event.preventDefault = event.stopPropagation =
 260                                 event.handler = event.data = null;
 261
 262                 return val;
 263         },
 264
 265         fix: function(event) {
 266                 // store a copy of the original event object
 267                 // and clone to set read-only properties
 268                 var originalEvent = event;
 269                 event = jQuery.extend({}, originalEvent);
 270
 271                 // add preventDefault and stopPropagation since
 272                 // they will not work on the clone
 273                 event.preventDefault = function() {
 274                         // if preventDefault exists run it on the original event
 275                         if (originalEvent.preventDefault)
 276                                 originalEvent.preventDefault();
 277                         // otherwise set the returnValue property of the original event to false (IE)
 278                         originalEvent.returnValue = false;
 279                 };
 280                 event.stopPropagation = function() {
 281                         // if stopPropagation exists run it on the original event
 282                         if (originalEvent.stopPropagation)
 283                                 originalEvent.stopPropagation();
 284                         // otherwise set the cancelBubble property of the original event to true (IE)
 285                         originalEvent.cancelBubble = true;
 286                 };
 287
 288                 // Fix target property, if necessary
 289                 if ( !event.target )
 290                         event.target = event.srcElement || document; // Fixes #1925 where srcElement might not be defined either
 291
 292                 // check if target is a textnode (safari)
 293                 if ( event.target.nodeType == 3 )
 294                         event.target = originalEvent.target.parentNode;
 295
 296                 // Add relatedTarget, if necessary
 297                 if ( !event.relatedTarget && event.fromElement )
 298                         event.relatedTarget = event.fromElement == event.target ? event.toElement : event.fromElement;
 299
 300                 // Calculate pageX/Y if missing and clientX/Y available
 301                 if ( event.pageX == null && event.clientX != null ) {
 302                         var doc = document.documentElement, body = document.body;
 303                         event.pageX = event.clientX + (doc && doc.scrollLeft || body && body.scrollLeft || 0) - (doc.clientLeft || 0);
 304                         event.pageY = event.clientY + (doc && doc.scrollTop || body && body.scrollTop || 0) - (doc.clientTop || 0);
 305                 }
 306
 307                 // Add which for key events
 308                 if ( !event.which && (event.charCode || event.keyCode) )
 309                         event.which = event.charCode || event.keyCode;
 310
 311                 // Add metaKey to non-Mac browsers (use ctrl for PC's and Meta for Macs)
 312                 if ( !event.metaKey && event.ctrlKey )
 313                         event.metaKey = event.ctrlKey;
 314
 315                 // Add which for click: 1 == left; 2 == middle; 3 == right
 316                 // Note: button is not normalized, so don't use it
 317                 if ( !event.which && event.button )
 318                         event.which = (event.button & 1 ? 1 : ( event.button & 2 ? 3 : ( event.button & 4 ? 2 : 0 ) ));
 319
 320                 return event;
 321         },
 322
 323         special: {
 324                 ready: {
 325                         setup: function() {
 326                                 var handler = jQuery.event.special.ready.handler;
 327
 328                                 // Mozilla, Opera and webkit nightlies currently support this event
 329                                 if ( document.addEventListener )
 330                                         // Use the handy event callback
 331                                         document.addEventListener( "DOMContentLoaded", handler, false );
 332
 333                                 // If Safari or IE is used
 334                                 // Continually check to see if the document is ready
 335                                 if  (jQuery.browser.msie || jQuery.browser.safari ) (function(){
 336                                         try {
 337                                                 // If IE is used, use the trick by Diego Perini
 338                                                 // http://javascript.nwbox.com/IEContentLoaded/
 339                                                 if ( jQuery.browser.msie || document.readyState != "loaded" && document.readyState != "complete" )
 340                                                         document.documentElement.doScroll("left");
 341                                         } catch( error ) {
 342                                                 return setTimeout( arguments.callee, 0 );
 343                                         }
 344
 345                                         // and execute any waiting functions
 346                                         handler();
 347                                 })();
 348
 349                                 // A fallback to window.onload, that will always work
 350                                 jQuery.event.add( window, "load", handler );
 351                         },
 352
 353                         teardown: function() {return;},
 354
 355                         handler: function() {
 356                                 // Make sure that the DOM is not already loaded
 357                                 if ( !jQuery.isReady ) {
 358                                         // Remember that the DOM is ready
 359                                         jQuery.isReady = true;
 360                                         jQuery(document).triggerHandler("ready");
 361                                         jQuery(document).unbind("ready");
 362                                 }
 363                         }
 364                 },
 365
 366                 mouseenter: {
 367                         setup: function() {
 368                                 if (jQuery.browser.msie) return false;
 369                                 jQuery(this).bind('mouseover', jQuery.event.special.mouseenter.handler);
 370                         },
 371
 372                         teardown: function() {
 373                                 if (jQuery.browser.msie) return false;
 374                                 jQuery(this).unbind('mouseover', jQuery.event.special.mouseenter.handler);
 375                         },
 376
 377                         handler: function(event) {
 378                                 var args = Array.prototype.slice.call( arguments, 1 );
 379                                 // If we actually just moused on to a sub-element, ignore it
 380                                 if ( withinElement(event, this) ) return;
 381                                 // Execute the right handlers by setting the event type to mouseenter
 382                                 event.type = 'mouseenter';
 383                                 // Include the event object as the first argument
 384                                 args.unshift(event);
 385                                 var val = jQuery.event.handle.apply(this, args);
 386                                 return val;
 387                         }
 388                 },
 389
 390                 mouseleave: {
 391                         setup: function() {
 392                                 if (jQuery.browser.msie) return false;
 393                                 jQuery(this).bind('mouseout', jQuery.event.special.mouseleave.handler);
 394                         },
 395
 396                         teardown: function() {
 397                                 if (jQuery.browser.msie) return false;
 398                                 jQuery(this).unbind('mouseout', jQuery.event.special.mouseleave.handler);
 399                         },
 400
 401                         handler: function(event) {
 402                                 var args = Array.prototype.slice.call( arguments, 1 );
 403                                 // If we actually just moused on to a sub-element, ignore it
 404                                 if ( withinElement(event, this) ) return false;
 405                                 // Execute the right handlers by setting the event type to mouseleave
 406                                 event.type = 'mouseleave';
 407                                 // Include the event object as the first argument
 408                                 args.unshift(event);
 409                                 var val = jQuery.event.handle.apply(this, args);
 410                                 return val;
 411                         }
 412                 }
 413         }
 414 };
 415
 416 jQuery.fn.extend({
 417         bind: function( type, data, fn ) {
 418                 return type == "unload" ? this.one(type, data, fn) : this.each(function(){
 419                         jQuery.event.add( this, type, fn || data, fn && data );
 420                 });
 421         },
 422
 423         one: function( type, data, fn ) {
 424                 return this.each(function(){
 425                         jQuery.event.add( this, type, function(event) {
 426                                 jQuery(this).unbind(event);
 427                                 return (fn || data).apply( this, arguments);
 428                         }, fn && data);
 429                 });
 430         },
 431
 432         unbind: function( type, fn ) {
 433                 return this.each(function(){
 434                         jQuery.event.remove( this, type, fn );
 435                 });
 436         },
 437
 438         trigger: function( type, data, fn ) {
 439                 return this.each(function(){
 440                         jQuery.event.trigger( type, data, this, true, fn );
 441                 });
 442         },
 443
 444         triggerHandler: function( type, data, fn ) {
 445                 if ( this[0] )
 446                         return jQuery.event.trigger( type, data, this[0], false, fn );
 447         },
 448
 449         toggle: function() {
 450                 // Save reference to arguments for access in closure
 451                 var args = arguments;
 452
 453                 return this.click(function(event) {
 454                         // Figure out which function to execute
 455                         this.lastToggle = 0 == this.lastToggle ? 1 : 0;
 456
 457                         // Make sure that clicks stop
 458                         event.preventDefault();
 459
 460                         // and execute the function
 461                         return args[this.lastToggle].apply( this, arguments ) || false;
 462                 });
 463         },
 464
 465         hover: function(fnOver, fnOut) {
 466                 return this.bind('mouseenter', fnOver).bind('mouseleave', fnOut);
 467         }
 468 });
 469
 470 jQuery.extend({
 471         isReady: false
 472 });
 473
 474 jQuery.each( ("blur,focus,load,ready,resize,scroll,unload,click,dblclick," +
 475         "mousedown,mouseup,mousemove,mouseover,mouseout,change,select," +
 476         "submit,keydown,keypress,keyup,error").split(","), function(i, name){
 477
 478         // Handle event binding
 479         jQuery.fn[name] = function(fn){
 480                 return fn ? this.bind(name, fn) : this.trigger(name);
 481         };
 482 });
 483
 484 // Checks if an event happened on an element within another element
 485 // Used in jQuery.event.special.mouseenter and mouseleave handlers
 486 var withinElement = function(event, element) {
 487         // Check if mouse(over|out) are still within the same parent element
 488         var parent = event.relatedTarget;
 489         // Traverse up the tree
 490         while ( parent && parent != element ) try { parent = parent.parentNode } catch(error) { parent = element; };
 491         // Return true if we actually just moused on to a sub-element
 492         return parent == element;
 493 };
 494
 495 // Prevent memory leaks in IE
 496 // And prevent errors on refresh with events like mouseover in other browsers
 497 // Window isn't included so as not to unbind existing unload events
 498 jQuery(window).bind("unload", function() {
 499         jQuery("*").add(document).unbind();
 500 });