docs: function simulateMouseEvent(target /*:HTMLElement*/, type /*:String*/,
                                     bubbles /*:Boolean*/,  cancelable /*:Boolean*/,
                                     view /*:Window*/,        detail /*:int*/,
                                     screenX /*:int*/,        screenY /*:int*/,
                                     clientX /*:int*/,        clientY /*:int*/,
                                     ctrlKey /*:Boolean*/,    altKey /*:Boolean*/,
                                     shiftKey /*:Boolean*/,   metaKey /*:Boolean*/,
                                     button /*:int*/,         relatedTarget /*:HTMLElement*/) /*:Void*/
      {
  
          //check target
          if (!target){
              throw new Error("simulateMouseEvent(): Invalid target.");
          }
  
          //check event type
          if (typeof type == "string"){
              type = type.toLowerCase();
  
              //make sure it's a supported mouse event
              if (!mouseEvents[type]){
                  throw new Error("simulateMouseEvent(): Event type '" + type + "' not supported.");
              }
          } else {
              throw new Error("simulateMouseEvent(): Event type must be a string.");
          }
  
          //setup default values
          if (typeof bubbles != "boolean"){
              bubbles = true; //all mouse events bubble
          }
          if (typeof cancelable != "boolean"){
              cancelable = (type != "mousemove"); //mousemove is the only one that can't be cancelled
          }
          if (typeof view != "object" || view != null){
              view = window; //view is typically window
          }
          if (typeof detail != "number"){
              detail = 1;  //number of mouse clicks must be at least one
          }
          if (typeof screenX != "number"){
              screenX = 0;
          }
          if (typeof screenY != "number"){
              screenY = 0;
          }
          if (typeof clientX != "number"){
              clientX = 0;
          }
          if (typeof clientY != "number"){
              clientY = 0;
          }
          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 button != "number"){
              button = 0;
          }
  
          if (!relatedTarget){
              relatedTarget = null;
          }
  
          //try to create a mouse event
          var customEvent /*:MouseEvent*/ = null;
  
          //check for DOM-compliant browsers first
          if (typeof document.createEvent == "function"){
  
              customEvent = document.createEvent("MouseEvents");
  
              //Safari 2.x (WebKit 418) still doesn't implement initMouseEvent()
              if (customEvent.initMouseEvent){
                  customEvent.initMouseEvent(type, bubbles, cancelable, view, detail,
                                       screenX, screenY, clientX, clientY,
                                       ctrlKey, altKey, shiftKey, metaKey,
                                       button, relatedTarget);
              } else { //Safari
  
                  //the closest thing available in Safari 2.x is UIEvents
                  customEvent = document.createEvent("UIEvents");
                  customEvent.initEvent(type, bubbles, cancelable);
                  customEvent.view = view;
                  customEvent.detail = detail;
                  customEvent.screenX = screenX;
                  customEvent.screenY = screenY;
                  customEvent.clientX = clientX;
                  customEvent.clientY = clientY;
                  customEvent.ctrlKey = ctrlKey;
                  customEvent.altKey = altKey;
                  customEvent.metaKey = metaKey;
                  customEvent.shiftKey = shiftKey;
                  customEvent.button = button;
                  customEvent.relatedTarget = relatedTarget;
              }
  
              /*
               * Check to see if relatedTarget has been assigned. Firefox
               * versions less than 2.0 don't allow it to be assigned via
               * initMouseEvent() and the property is readonly after event
               * creation, so in order to keep YAHOO.util.getRelatedTarget()
               * working, assign to the IE proprietary toElement property
               * for mouseout event and fromElement property for mouseover
               * event.
               */
              if (relatedTarget && !customEvent.relatedTarget){
                  if (type == "mouseout"){
                      customEvent.toElement = relatedTarget;
                  } else if (type == "mouseover"){
                      customEvent.fromElement = relatedTarget;
                  }
              }
  
              //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.detail = detail;
              customEvent.screenX = screenX;
              customEvent.screenY = screenY;
              customEvent.clientX = clientX;
              customEvent.clientY = clientY;
              customEvent.ctrlKey = ctrlKey;
              customEvent.altKey = altKey;
              customEvent.metaKey = metaKey;
              customEvent.shiftKey = shiftKey;
  
              //fix button property for IE's wacky implementation
              switch(button){
                  case 0:
                      customEvent.button = 1;
                      break;
                  case 1:
                      customEvent.button = 4;
                      break;
                  case 2:
                      //leave as is
                      break;
                  default:
                      customEvent.button = 0;
              }
  
              /*
               * Have to use relatedTarget because IE won't allow assignment
               * to toElement or fromElement on generic events. This keeps
               * YAHOO.util.customEvent.getRelatedTarget() functional.
               */
              customEvent.relatedTarget = relatedTarget;
  
              //fire the event
              target.fireEvent("on" + type, customEvent);
  
          } else {
              throw new Error("simulateMouseEvent(): No event simulation framework present.");
          }
      }