docs: function simulateKeyEvent(target /*:HTMLElement*/, type /*:String*/,
                                   bubbles /*:Boolean*/,  cancelable /*:Boolean*/,
                                   view /*:Window*/,
                                   ctrlKey /*:Boolean*/,    altKey /*:Boolean*/,
                                   shiftKey /*:Boolean*/,   metaKey /*:Boolean*/,
                                   keyCode /*:int*/,        charCode /*:int*/) /*:Void*/
      {
          //check target
          if (!target){
              throw new Error("simulateKeyEvent(): Invalid target.");
          }
  
          //check event type
          if (typeof type == "string"){
              type = type.toLowerCase();
              switch(type){
                  case "textevent": //DOM Level 3
                      type = "keypress";
                      break;
                  case "keyup":
                  case "keydown":
                  case "keypress":
                      break;
                  default:
                      throw new Error("simulateKeyEvent(): Event type '" + type + "' not supported.");
              }
          } else {
              throw new Error("simulateKeyEvent(): Event type must be a string.");
          }
  
          //setup default values
          if (typeof bubbles != "boolean"){
              bubbles = true; //all key events bubble
          }
          if (typeof cancelable != "boolean"){
              cancelable = true; //all key events can be cancelled
          }
          if (typeof view != "object" || view == null){
              view = window; //view is typically window
          }
          if (typeof ctrlKey != "boolean"){
              ctrlKey = false;
          }
          if (typeof altKey != "boolean"){
              altKey = false;
          }
          if (typeof shiftKey != "boolean"){
              shiftKey = false;
          }
          if (typeof metaKey != "boolean"){
              metaKey = false;
          }
          if (typeof keyCode != "number"){
              keyCode = 0;
          }
          if (typeof charCode != "number"){
              charCode = 0;
          }
  
          //try to create a mouse event
          var customEvent = null;
  
          //check for DOM-compliant browsers first
          if (typeof document.createEvent == "function"){
  
              try {
  
                  //try to create key event
                  customEvent = document.createEvent("KeyEvents");
  
                  /*
                   * Interesting problem: Firefox implemented a non-standard
                   * version of initKeyEvent() based on DOM Level 2 specs.
                   * Key event was removed from DOM Level 2 and re-introduced
                   * in DOM Level 3 with a different interface. Firefox is the
                   * only browser with any implementation of Key Events, so for
                   * now, assume it's Firefox if the above line doesn't error.
                   */
                  // @TODO: Decipher between Firefox's implementation and a correct one.
                  customEvent.initKeyEvent(type, bubbles, cancelable, view, ctrlKey,
                      altKey, shiftKey, metaKey, keyCode, charCode);
  
              } catch (ex){
  
                  /*
                   * If it got here, that means key events aren't officially supported.
                   * Safari/WebKit is a real problem now. WebKit 522 won't let you
                   * set keyCode, charCode, or other properties if you use a
                   * UIEvent, so we first must try to create a generic event. The
                   * fun part is that this will throw an error on Safari 2.x. The
                   * end result is that we need another try...catch statement just to
                   * deal with this mess.
                   */
                  try {
  
                      //try to create generic event - will fail in Safari 2.x
                      customEvent = document.createEvent("Events");
  
                  } catch (uierror /*:Error*/){
  
                      //the above failed, so create a UIEvent for Safari 2.x
                      customEvent = document.createEvent("UIEvents");
  
                  } finally {
  
                      customEvent.initEvent(type, bubbles, cancelable);
  
                      //initialize
                      customEvent.view = view;
                      customEvent.altKey = altKey;
                      customEvent.ctrlKey = ctrlKey;
                      customEvent.shiftKey = shiftKey;
                      customEvent.metaKey = metaKey;
                      customEvent.keyCode = keyCode;
                      customEvent.charCode = charCode;
  
                  }
  
              }
  
              //fire the event
              target.dispatchEvent(customEvent);
  
          } else if (typeof document.createEventObject != "undefined"){ //IE
  
              //create an IE event object
              customEvent = document.createEventObject();
  
              //assign available properties
              customEvent.bubbles = bubbles;
              customEvent.cancelable = cancelable;
              customEvent.view = view;
              customEvent.ctrlKey = ctrlKey;
              customEvent.altKey = altKey;
              customEvent.shiftKey = shiftKey;
              customEvent.metaKey = metaKey;
  
              /*
               * IE doesn't support charCode explicitly. CharCode should
               * take precedence over any keyCode value for accurate
               * representation.
               */
              customEvent.keyCode = (charCode > 0) ? charCode : keyCode;
  
              //fire the event
              target.fireEvent("on" + type, customEvent);
  
          } else {
              throw new Error("simulateKeyEvent(): No event simulation framework present.");
          }
      }