sproutcore 0.9.23 → 1.0.1003

data/frameworks/sproutcore/frameworks/foundation/system/event.js

@@ -0,0 +1,849 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('system/core_query') ;
+
+/**
+  The event class provides a simple cross-platform library for capturing and
+  delivering events on DOM elements and other objects.  While this library
+  is based on code from both jQuery and Prototype.js, it includes a number of
+  additional features including support for handler objects and event 
+  delegation.
+
+  Since native events are implemented very unevenly across browsers,
+  SproutCore will convert all native events into a standardized instance of
+  this special event class.  
+  
+  SproutCore events implement the standard W3C event API as well as some 
+  additional helper methods.
+
+  @constructor
+  @param {Event} originalEvent
+  @returns {SC.Event} event instance
+  
+  @since SproutCore 1.0
+*/
+SC.Event = function(originalEvent) { 
+
+  // copy properties from original event, if passed in.
+  if (originalEvent) {
+    this.originalEvent = originalEvent ;
+    var props = SC.Event._props, len = props.length, idx = len ;
+    while(--idx >= 0) {
+      var key = props[idx] ;
+      this[key] = originalEvent[key] ;
+    }
+  }
+
+  // Fix timeStamp
+  this.timeStamp = this.timeStamp || Date.now();
+
+  // Fix target property, if necessary
+  // Fixes #1925 where srcElement might not be defined either
+  if (!this.target) this.target = this.srcElement || document; 
+
+  // check if target is a textnode (safari)
+  if (this.target.nodeType === 3 ) this.target = this.target.parentNode;
+
+  // Add relatedTarget, if necessary
+  if (!this.relatedTarget && this.fromElement) {
+    this.relatedTarget = (this.fromElement === this.target) ? this.toElement : this.fromElement;
+  }
+
+  // Calculate pageX/Y if missing and clientX/Y available
+  if (SC.none(this.pageX) && !SC.none(this.clientX)) {
+    var doc = document.documentElement, body = document.body;
+    this.pageX = this.clientX + (doc && doc.scrollLeft || body && body.scrollLeft || 0) - (doc.clientLeft || 0);
+    this.pageY = this.clientY + (doc && doc.scrollTop || body && body.scrollTop || 0) - (doc.clientTop || 0);
+  }
+
+  // Add which for key events
+  if (!this.which && ((this.charCode || originalEvent.charCode === 0) ? this.charCode : this.keyCode)) {
+    this.which = this.charCode || this.keyCode;
+  }
+
+  // Add metaKey to non-Mac browsers (use ctrl for PC's and Meta for Macs)
+  if (!this.metaKey && this.ctrlKey) this.metaKey = this.ctrlKey;
+
+  // Add which for click: 1 == left; 2 == middle; 3 == right
+  // Note: button is not normalized, so don't use it
+  if (!this.which && this.button) {
+    this.which = ((this.button & 1) ? 1 : ((this.button & 2) ? 3 : ( (this.button & 4) ? 2 : 0 ) ));
+  }
+  
+  // normalize wheelDelta, wheelDeltaX, & wheelDeltaY for Safari
+  if (SC.browser.safari && originalEvent.wheelDelta!==undefined) {
+    this.wheelDelta = this.wheelDeltaY = 0-(originalEvent.wheelDeltaY || originalEvent.wheelDelta);
+    this.wheelDeltaX = 0-(originalEvent.wheelDeltaX||0) ;
+    
+  // normalize wheelDelta for Firefox
+  // note that we multiple the delta on FF to make it's acceleration more 
+  // natural.
+  } else if (!SC.none(originalEvent.detail)) {
+    var detail = Math.floor(originalEvent.detail * 2);
+    if (originalEvent.axis && (originalEvent.axis === originalEvent.HORIZONTAL_AXIS)) {
+      this.wheelDeltaX = detail;
+      this.wheelDeltaY = this.wheelDelta = 0;
+    } else {
+      this.wheelDeltaY = this.wheelDelta = detail ;
+      this.wheelDeltaX = 0 ;
+    }
+    
+  // handle all other legacy browser
+  } else {
+    this.wheelDelta = this.wheelDeltaY = SC.browser.msie ? 0-originalEvent.wheelDelta : originalEvent.wheelDelta ;
+    this.wheelDeltaX = 0 ;
+  }
+  
+  return this; 
+} ;
+
+SC.mixin(SC.Event, /** @scope SC.Event */ {
+
+  /** 
+    Standard method to create a new event.  Pass the native browser event you
+    wish to wrap if needed.
+  */
+  create: function(e) { return new SC.Event(e); },
+
+  // the code below was borrowed from jQuery, Dean Edwards, and Prototype.js
+  
+  /**
+    Bind an event to an element.
+
+    This method will cause the passed handler to be executed whenever a
+    relevant event occurs on the named element.  This method supports a
+    variety of handler types, depending on the kind of support you need.
+    
+    h2. Simple Function Handlers
+    
+      SC.Event.add(anElement, "click", myClickHandler) ;
+      
+    The most basic type of handler you can pass is a function.  This function
+    will be executed everytime an event of the type you specify occurs on the
+    named element.  You can optionally pass an additional context object which
+    will be included on the event in the event.data property.
+    
+    When your handler function is called the, the function's "this" property
+    will point to the element the event occurred on.
+    
+    The click handler for this method must have a method signature like:
+    
+      function(event) { return YES|NO; }
+      
+    h2. Method Invocations
+    
+      SC.Event.add(anElement, "click", myObject, myObject.aMethod) ;
+      
+    Optionally you can specify a target object and a method on the object to 
+    be invoked when the event occurs.  This will invoke the method function
+    with the target object you pass as "this".  The method should have a 
+    signature like:
+    
+      function(event, targetElement) { return YES|NO; }
+      
+    Like function handlers, you can pass an additional context data paramater
+    that will be included on the event in the event.data property.
+      
+    h2. Handler Return Values
+    
+    Both handler functions should return YES if you want the event to 
+    continue to propagate and NO if you want it to stop.  Returning NO will
+    both stop bubbling of the event and will prevent any default action 
+    taken by the browser.  You can also control these two behaviors separately
+    by calling the stopPropagation() or preventDefault() methods on the event
+    itself, returning YES from your method.
+    
+    h2. Limitations
+    
+    Although SproutCore's event implementation is based on jQuery, it is 
+    much simpler in design.  Notably, it does not support namespaced events
+    and you can only pass a single type at a time.
+    
+    If you need more advanced event handling, consider the SC.ClassicResponder 
+    functionality provided by SproutCore or use your favorite DOM library.
+
+    @param {Element} elem a DOM element, window, or document object
+    @param {String} eventType the event type you want to respond to
+    @param {Object} target The target object for a method call or a function.
+    @param {Object} method optional method or method name if target passed
+    @param {Object} context optional context to pass to the handler as event.data
+    @returns {Object} receiver
+  */
+  add: function(elem, eventType, target, method, context) {
+
+    // if a CQ object is passed in, either call add on each item in the 
+    // matched set, or simply get the first element and use that.
+    if (elem && elem.isCoreQuery) {
+      if (elem.length > 0) {
+        elem.forEach(function(e) { 
+          this.add(e, eventType, target, method, context);
+        }, this);
+        return this;
+      } else elem = elem.get(0);
+    }
+    if (!elem) return this; // nothing to do
+    
+    // cannot register events on text nodes, etc.
+    if ( elem.nodeType == 3 || elem.nodeType == 8 ) return SC.Event;
+
+    // For whatever reason, IE has trouble passing the window object
+    // around, causing it to be cloned in the process
+    if (SC.browser.msie && elem.setInterval) elem = window;
+
+    // if target is a function, treat it as the method, with optional context
+    if (SC.typeOf(target) === SC.T_FUNCTION) {
+      context = method; method = target; target = null;
+      
+    // handle case where passed method is a key on the target.
+    } else if (target && SC.typeOf(method) === SC.T_STRING) {
+      method = target[method] ;
+    }
+
+    // Get the handlers queue for this element/eventType.  If the queue does
+    // not exist yet, create it and also setup the shared listener for this
+    // eventType.
+    var events = SC.data(elem, "events") || SC.data(elem, "events", {}) ;
+    var handlers = events[eventType]; 
+    if (!handlers) {
+      handlers = events[eventType] = {} ;
+      this._addEventListener(elem, eventType) ;
+    }
+    
+    // Build the handler array and add to queue
+    handlers[SC.guidFor(method)] = [target, method, context];
+    SC.Event._global[eventType] = YES ; // optimization for global triggers
+
+    // Nullify elem to prevent memory leaks in IE
+    elem = events = handlers = null ;
+    return this ;
+  },
+
+  /**
+    Removes a specific handler or all handlers for an event or event+type.
+
+    To remove a specific handler, you must pass in the same function or the
+    same target and method as you passed into SC.Event.add().  See that method
+    for full documentation on the parameters you can pass in.
+    
+    If you omit a specific handler but provide both an element and eventType,
+    then all handlers for that element will be removed.  If you provide only
+    and element, then all handlers for all events on that element will be
+    removed.
+    
+    h2. Limitations
+    
+    Although SproutCore's event implementation is based on jQuery, it is 
+    much simpler in design.  Notably, it does not support namespaced events
+    and you can only pass a single type at a time.
+    
+    If you need more advanced event handling, consider the SC.ClassicResponder 
+    functionality provided by SproutCore or use your favorite DOM library.
+    
+    @param {Element} elem a DOM element, window, or document object
+    @param {String} eventType the event type to remove
+    @param {Object} target The target object for a method call.  Or a function.
+    @param {Object} method optional name of method
+    @returns {Object} receiver
+  */
+  remove: function(elem, eventType, target, method) {
+
+    // if a CQ object is passed in, either call add on each item in the 
+    // matched set, or simply get the first element and use that.
+    if (elem && elem.isCoreQuery) {
+      if (elem.length > 0) {
+        elem.forEach(function(e) { 
+          this.remove(e, eventType, target, method);
+        }, this);
+        return this;
+      } else elem = elem.get(0);
+    }
+    if (!elem) return this; // nothing to do
+    
+    // don't do events on text and comment nodes
+    if ( elem.nodeType == 3 || elem.nodeType == 8 ) return SC.Event;
+
+    // For whatever reason, IE has trouble passing the window object
+    // around, causing it to be cloned in the process
+    if (SC.browser.msie && elem.setInterval) elem = window;
+
+    var handlers, key, events = SC.data(elem, "events") ;
+    if (!events) return this ; // nothing to do if no events are registered
+
+    // if no type is provided, remove all types for this element.
+    if (eventType === undefined) {
+      for(eventType in events) this.remove(elem, eventType) ;
+
+    // otherwise, remove the handler for this specific eventType if found
+    } else if (handlers = events[eventType]) {
+
+      var cleanupHandlers = NO ;
+      
+      // if a target/method is provided, remove only that one
+      if (target || method) {
+        
+        // normalize the target/method
+        if (SC.typeOf(target) === SC.T_FUNCTION) {
+          method = target; target = null ;
+        } else if (SC.typeOf(method) === SC.T_STRING) {
+          method = target[method] ;
+        }
+        
+        delete events[SC.guidFor(method)] ;
+        
+        // check to see if there are handlers left on this event/eventType.
+        // if not, then cleanup the handlers.
+        key = null ;
+        for(key in handlers) break ;
+        if (key===null) cleanupHandlers = YES ;
+
+      // otherwise, just cleanup all handlers
+      } else cleanupHandlers = YES ;
+      
+      // If there are no more handlers left on this event type, remove 
+      // eventType hash from queue.
+      if (cleanupHandlers) {
+        delete events[eventType] ;
+        this._removeEventListener(elem, eventType) ;
+      }
+      
+      // verify that there are still events registered on this element.  If 
+      // there aren't, cleanup the element completely to avoid memory leaks.
+      key = null ;
+      for(key in events) break;
+      if(!key) {
+        SC.removeData(elem, "events") ;
+        delete this._elements[SC.guidFor(elem)]; // important to avoid leaks
+      }
+      
+    }
+    
+    elem = events = handlers = null ; // avoid memory leaks
+    return this ;
+  },
+
+  NO_BUBBLE: ['blur', 'focus', 'change'],
+  
+  /**
+    Generates a simulated event object.  This is mostly useful for unit 
+    testing.  You can pass the return value of this property into the 
+    trigger() method to actually send the event.
+    
+    @param {Element} elem the element the event targets
+    @param {String} eventType event type.  mousedown, mouseup, etc
+    @param {Hash} attrs optional additonal attributes to apply to event.
+    @returns {Hash} simulated event object
+  */
+  simulateEvent: function(elem, eventType, attrs) {
+    var ret = SC.Event.create({
+      type: eventType,
+      target: elem,
+      preventDefault: function(){ this.cancelled = YES; },
+      stopPropagation: function(){ this.bubbles = NO; },
+      allowDefault: function() { this.hasCustomEventHandling = YES; },
+      timeStamp: Date.now(),
+      bubbles: (this.NO_BUBBLE.indexOf(eventType)<0),
+      cancelled: NO,
+      normalized: YES
+    });
+    if (attrs) SC.mixin(ret, attrs) ;
+    return ret ;
+  },
+  
+  /**
+    Trigger an event execution immediately.  You can use this method to 
+    simulate arbitrary events on arbitary elements.
+
+    h2. Limitations
+    
+    Note that although this is based on the jQuery implementation, it is 
+    much simpler.  Notably namespaced events are not supported and you cannot
+    trigger events globally.
+    
+    If you need more advanced event handling, consider the SC.Responder 
+    functionality provided by SproutCore or use your favorite DOM library.
+
+    h2. Example
+    
+    {{{
+      SC.Event.trigger(view.get('layer'), 'mousedown');
+    }}}
+    
+    @param elem {Element} the target element
+    @param eventType {String} the event type
+    @param args {Array} optional argument or arguments to pass to handler.
+    @param donative ??
+    @returns {Boolean} Return value of trigger or undefined if not fired
+  */
+  trigger: function(elem, eventType, args, donative) {
+
+    // if a CQ object is passed in, either call add on each item in the 
+    // matched set, or simply get the first element and use that.
+    if (elem && elem.isCoreQuery) {
+      if (elem.length > 0) {
+        elem.forEach(function(e) { 
+          this.trigger(e, eventType, args, donative);
+        }, this);
+        return this;
+      } else elem = elem.get(0);
+    }
+    if (!elem) return this; // nothing to do
+
+    // don't do events on text and comment nodes
+    if ( elem.nodeType == 3 || elem.nodeType == 8 ) return undefined;
+    
+    // Normalize to an array
+    args = SC.A(args) ;
+
+    var ret, fn = SC.typeOf(elem[eventType] || null) === SC.T_FUNCTION ;
+
+    // Get the event to pass, creating a fake one if necessary
+    var event = args[0];
+    if (!event || !event.preventDefault) {
+      event = this.simulateEvent(elem, eventType) ;
+      args.unshift(event) ;
+    }
+    
+    event.type = eventType ;
+    
+    // Trigger the event - bubble if enabled
+    var current = elem;
+    do {
+      ret = SC.Event.handle.apply(current, args);
+      current = (current===document) ? null : (current.parentNode || document);
+    } while(!ret && event.bubbles && current);    
+    current = null ;
+
+    // Handle triggering native .onfoo handlers
+    var onfoo = elem["on" + eventType] ;
+    var isClick = SC.CoreQuery.nodeName(elem, 'a') && eventType === 'click';
+    if ((!fn || isClick) && onfoo && onfoo.apply(elem, args) === NO) ret = NO;
+
+    // Trigger the native events (except for clicks on links)
+    if (fn && donative !== NO && ret !== NO && !isClick) {
+      this.triggered = YES;
+      try {
+        elem[ eventType ]();
+      // prevent IE from throwing an error for some hidden elements
+      } catch (e) {}
+    }
+    
+    this.triggered = NO;
+
+    return ret;
+  },
+
+  /**
+    This method will handle the passed event, finding any registered listeners
+    and executing them.  If you have an event you want handled, you can 
+    manually invoke this method.  This function expects it's "this" value to
+    be the element the event occurred on, so you should always call this 
+    method like:
+    
+      SC.Event.handle.call(element, event) ;
+      
+    Note that like other parts of this library, the handle function does not
+    support namespaces.
+    
+    @param event {Event} the event to handle
+    @returns {Boolean}
+  */
+  handle: function(event) {
+
+    // ignore events triggered after window is unloaded or if double-called
+    // from within a trigger.
+    if ((typeof SC === "undefined") || SC.Event.triggered) return YES ;
+    
+    // returned undefined or NO
+    var val, ret, namespace, all, handlers, args;
+
+    // normalize event across browsers.  The new event will actually wrap the
+    // real event with a normalized API.
+    args = SC.A(arguments);
+    args[0] = event = SC.Event.normalizeEvent(event || window.event);
+
+    // get the handlers for this event type
+    handlers = (SC.data(this, "events") || {})[event.type];
+    if (!handlers) return NO ; // nothing to do
+    
+    // invoke all handlers
+    for (var key in handlers ) {
+      var handler = handlers[key];
+      var method = handler[1] ;
+
+      // Pass in a reference to the handler function itself
+      // So that we can later remove it
+      event.handler = method;
+      event.data = event.context = handler[2];
+
+      var target = handler[0] || this ;
+      ret = method.apply( target, args );
+      
+      if (val !== NO) val = ret;
+
+      // if method returned NO, do not continue.  Stop propogation and
+      // return default.  Note that we test explicitly for NO since 
+      // if the handler returns no specific value, we do not want to stop.
+      if ( ret === NO ) {
+        event.preventDefault();
+        event.stopPropagation();
+      }
+    }
+
+    return val;
+  },
+
+  /**
+    This method is called just before the window unloads to unhook all 
+    registered events.
+  */
+  unload: function() {
+    var key, elements = this._elements ;
+    for(key in elements) this.remove(elements[key]) ;
+    
+    // just in case some book-keeping was screwed up.  avoid memory leaks
+    for(key in elements) delete elements[key] ;
+    delete this._elements ; 
+  },
+  
+  /**
+    This hash contains handlers for special or custom events.  You can add
+    your own handlers for custom events here by simply naming the event and
+    including a hash with the following properties:
+    
+     - setup: this function should setup the handler or return NO
+     - teardown: this function should remove the event listener
+     
+  */
+  special: {
+    
+    ready: {
+      setup: function() {
+        // Make sure the ready event is setup
+        SC._bindReady() ;
+        return;
+      },
+
+      teardown: function() { return; }
+
+    },
+
+    /** @private
+        Implement support for mouseenter on browsers other than IE */
+    mouseenter: {
+      setup: function() {
+        if ( SC.browser.msie ) return NO;
+        SC.Event.add(this, 'mouseover', SC.Event.special.mouseover.handler);
+        return YES;
+      },
+
+      teardown: function() {
+        if ( SC.browser.msie ) return NO;
+        SC.Event.remove(this, 'mouseover', SC.Event.special.mouseover.handler);
+        return YES;
+      },
+
+      handler: function(event) {
+        // If we actually just moused on to a sub-element, ignore it
+        if ( SC.Event._withinElement(event, this) ) return YES;
+        // Execute the right handlers by setting the event type to mouseenter
+        event.type = "mouseenter";
+        return SC.Event.handle.apply(this, arguments);
+      }
+    },
+
+    /** @private
+        Implement support for mouseleave on browsers other than IE */
+    mouseleave: {
+      setup: function() {
+        if ( SC.browser.msie ) return NO;
+        SC.Event.add(this, "mouseout", SC.Event.special.mouseleave.handler);
+        return YES;
+      },
+
+      teardown: function() {
+        if ( SC.browser.msie ) return NO;
+        SC.Event.remove(this, "mouseout", SC.Event.special.mouseleave.handler);
+        return YES;
+      },
+
+      handler: function(event) {
+        // If we actually just moused on to a sub-element, ignore it
+        if ( SC.Event._withinElement(event, this) ) return YES;
+        // Execute the right handlers by setting the event type to mouseleave
+        event.type = "mouseleave";
+        return SC.Event.handle.apply(this, arguments);
+      }
+    }
+  },
+
+  KEY_BACKSPACE: 8,
+  KEY_TAB:       9,
+  KEY_RETURN:   13,
+  KEY_ESC:      27,
+  KEY_LEFT:     37,
+  KEY_UP:       38,
+  KEY_RIGHT:    39,
+  KEY_DOWN:     40,
+  KEY_DELETE:   46,
+  KEY_HOME:     36,
+  KEY_END:      35,
+  KEY_PAGEUP:   33,
+  KEY_PAGEDOWN: 34,
+  KEY_INSERT:   45,
+    
+  _withinElement: function(event, elem) {
+    // Check if mouse(over|out) are still within the same parent element
+    var parent = event.relatedTarget;
+    
+    // Traverse up the tree
+    while ( parent && parent != elem ) {
+      try { parent = parent.parentNode; } catch(error) { parent = elem; }
+    }
+
+    // Return YES if we actually just moused on to a sub-element
+    return parent === elem;
+  },
+  
+  /** @private
+    Adds the primary event listener for the named type on the element.
+    
+    If the event type has a special handler defined in SC.Event.special, 
+    then that handler will be used.  Otherwise the normal browser method will
+    be used.
+    
+    @param elem {Element} the target element
+    @param eventType {String} the event type
+  */
+  _addEventListener: function(elem, eventType) {
+    var listener, special = this.special[eventType] ;
+
+    // Check for a special event handler
+    // Only use addEventListener/attachEvent if the special
+    // events handler returns NO
+    if ( !special || special.setup.call(elem)===NO) {
+      
+      // Save element in cache.  This must be removed later to avoid 
+      // memory leaks.
+      var guid = SC.guidFor(elem) ;
+      this._elements[guid] = elem;
+      
+      listener = SC.data(elem, "listener") || SC.data(elem, "listener", 
+       function() {
+         return SC.Event.handle.apply(SC.Event._elements[guid], arguments); 
+      }) ;
+      
+      // Bind the global event handler to the element
+      if (elem.addEventListener) {
+        elem.addEventListener(eventType, listener, NO);
+      } else if (elem.attachEvent) {
+        // attachEvent is not working for IE8 and xhr objects
+        // there is currently a hack in request , but it needs to fixed here.
+        elem.attachEvent("on" + eventType, listener);
+      }
+      //  
+      // else {
+      //         elem.onreadystatechange = listener;
+      //       }
+    }
+    
+    elem = special = listener = null ; // avoid memory leak
+  },
+
+  /** @private
+    Removes the primary event listener for the named type on the element.
+    
+    If the event type has a special handler defined in SC.Event.special, 
+    then that handler will be used.  Otherwise the normal browser method will
+    be used.
+    
+    Note that this will not clear the _elements hash from the element.  You
+    must call SC.Event.unload() on unload to make sure that is cleared.
+    
+    @param elem {Element} the target element
+    @param eventType {String} the event type
+  */
+  _removeEventListener: function(elem, eventType) {
+    var listener, special = SC.Event.special[eventType] ;
+    if (!special || (special.teardown.call(elem)===NO)) {
+      listener = SC.data(elem, "listener") ;
+      if (listener) {
+        if (elem.removeEventListener) {
+          elem.removeEventListener(eventType, listener, NO);
+        } else if (elem.detachEvent) {
+          elem.detachEvent("on" + eventType, listener);
+        }
+      }
+    }
+    
+    elem = special = listener = null ;
+  },
+
+  _elements: {},
+  
+  // implement preventDefault() in a cross platform way
+  
+  /** @private Take an incoming event and convert it to a normalized event. */
+  normalizeEvent: function(event) {
+    if (event == window.event) {
+      // IE can't do event.normalized on an Event object
+      return SC.Event.create(event) ; 
+    } else {
+      return event.normalized ? event : SC.Event.create(event) ;
+    }
+  },
+  
+  _global: {},
+
+  /** @private properties to copy from native event onto the event */
+  _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 which touches targetTouches changedTouches".split(" ")
+  
+}) ;
+
+SC.Event.prototype = {
+
+  /**
+    Set to YES if you have called either preventDefault() or stopPropagation().  This allows a generic event handler to notice if you want to provide detailed control over how the browser handles the real event.
+  */
+  hasCustomEventHandling: NO,
+  
+  /**
+    Indicates that you want to allow the normal default behavior.  Sets
+    the hasCustomEventHandling property to YES but does not cancel the event.
+    
+    @returns {SC.Event} receiver
+  */
+  allowDefault: function() {
+    this.hasCustomEventHandling = YES ;
+    return this ;  
+  },
+  
+  /** 
+    Implements W3C standard.  Will prevent the browser from performing its
+    default action on this event.
+    
+    @returns {SC.Event} receiver
+  */
+  preventDefault: function() {
+    var evt = this.originalEvent ;
+    if (evt) {
+      if (evt.preventDefault) evt.preventDefault() ;
+      evt.returnValue = NO ; // IE
+    }
+    this.hasCustomEventHandling = YES ;
+    return this ;
+  },
+
+  /**
+    Implements W3C standard.  Prevents further bubbling of the event.
+    
+    @returns {SC.Event} receiver
+  */
+  stopPropagation: function() {
+    var evt = this.originalEvent ;
+    if (evt) {
+      if (evt.stopPropagation) evt.stopPropagation() ;
+      evt.cancelBubble = YES ; // IE
+    }
+    this.hasCustomEventHandling = YES ; 
+    return this ;
+  },
+
+  /** 
+    Stops both the default action and further propogation.  This is more 
+    convenient than calling both.
+    
+    @returns {SC.Event} receiver
+  */
+  stop: function() {
+    return this.preventDefault().stopPropagation();
+  },
+  
+  /** Always YES to indicate the event was normalized. */
+  normalized: YES,
+
+  /** Returns the pressed character (found in this.which) as a string. */
+  getCharString: function() { 
+    return (this.charCode>0) ? String.fromCharCode(this.which) : null;
+  },
+  
+  /** Returns character codes for the event.  The first value is the normalized code string, with any shift or ctrl characters added to the begining.  The second value is the char string by itself.
+  
+    @returns {Array}
+  */
+  commandCodes: function() {
+    var code=this.keyCode, ret=null, key=null, modifiers='', lowercase ;
+    
+    // handle function keys.
+    if (code) {
+      ret = SC.FUNCTION_KEYS[code] ;
+      if (!ret && (this.altKey || this.ctrlKey || this.metaKey)) {
+        ret = SC.PRINTABLE_KEYS[code];
+      }
+      
+      if (ret) {
+        if (this.altKey) modifiers += 'alt_' ;
+        if (this.ctrlKey || this.metaKey) modifiers += 'ctrl_' ;
+        if (this.shiftKey) modifiers += 'shift_' ;
+      }
+    }
+
+    // otherwise just go get the right key.
+    if (!ret) {
+      code = this.which ;
+      key = ret = String.fromCharCode(code) ;
+      lowercase = ret.toLowerCase() ;
+      if (this.metaKey) {
+        modifiers = 'meta_' ;
+        ret = lowercase;
+        
+      } else ret = null ;
+    }
+
+    if (ret) ret = modifiers + ret ;
+    return [ret, key] ;
+  }
+    
+} ;
+
+// Also provide a Prototype-like API so that people can use either one.
+
+/** Alias for add() method.  This provides a Prototype-like API. */
+SC.Event.observe = SC.Event.add ;
+
+/** Alias for remove() method.  This provides a Prototype-like API */
+SC.Event.stopObserving = SC.Event.remove ;
+
+/** Alias for trigger() method.  This provides a Prototype-like API */
+SC.Event.fire = SC.Event.trigger;
+
+// Register unload handler to eliminate any registered handlers
+// This avoids leaks in IE and issues with mouseout or other handlers on 
+// other browsers.
+SC.Event.add(window, 'unload', SC.Event.prototype, SC.Event.unload) ;
+
+SC.MODIFIER_KEYS = {
+  16:'shift', 17:'ctrl', 18: 'alt'
+};
+
+SC.FUNCTION_KEYS = {
+  8: 'backspace',  9: 'tab',  13: 'return',  19: 'pause',  27: 'escape',  
+  33: 'pageup', 34: 'pagedown', 35: 'end', 36: 'home', 
+  37: 'left', 38: 'up', 39: 'right', 40: 'down', 44: 'printscreen', 
+  45: 'insert', 46: 'delete', 112: 'f1', 113: 'f2', 114: 'f3', 115: 'f4', 
+  116: 'f5', 117: 'f7', 119: 'f8', 120: 'f9', 121: 'f10', 122: 'f11', 
+  123: 'f12', 144: 'numlock', 145: 'scrolllock'
+} ;
+
+SC.PRINTABLE_KEYS = {
+  32: ' ', 48:"0", 49:"1", 50:"2", 51:"3", 52:"4", 53:"5", 54:"6", 55:"7",
+  56:"8", 57:"9", 59:";", 61:"=", 65:"a", 66:"b", 67:"c", 68:"d", 69:"e",
+  70:"f", 71:"g", 72:"h", 73:"i", 74:"j", 75:"k", 76:"l", 77:"m", 78:"n",
+  79:"o", 80:"p", 81:"q", 82:"r", 83:"s", 84:"t", 85:"u", 86:"v", 87:"w",
+  88:"x", 89:"y", 90:"z", 107:"+", 109:"-", 110:".", 188:",", 190:".",
+  191:"/", 192:"`", 219:"[", 220:"\\", 221:"]", 222:"\""
+} ;