[extjs.git] / extjs / packages / ux / src / event / Player.js

/**\r
 * @extends Ext.ux.event.Driver\r
 * This class manages the playback of an array of "event descriptors". For details on the\r
 * contents of an "event descriptor", see {@link Ext.ux.event.Recorder}. The events recorded by the\r
 * {@link Ext.ux.event.Recorder} class are designed to serve as input for this class.\r
 * \r
 * The simplest use of this class is to instantiate it with an {@link #eventQueue} and call\r
 * {@link #method-start}. Like so:\r
 *\r
 *      var player = Ext.create('Ext.ux.event.Player', {\r
 *          eventQueue: [ ... ],\r
 *          speed: 2,  // play at 2x speed\r
 *          listeners: {\r
 *              stop: function () {\r
 *                  player = null; // all done\r
 *              }\r
 *          }\r
 *      });\r
 *\r
 *      player.start();\r
 *\r
 * A more complex use would be to incorporate keyframe generation after playing certain\r
 * events.\r
 *\r
 *      var player = Ext.create('Ext.ux.event.Player', {\r
 *          eventQueue: [ ... ],\r
 *          keyFrameEvents: {\r
 *              click: true\r
 *          },\r
 *          listeners: {\r
 *              stop: function () {\r
 *                  // play has completed... probably time for another keyframe...\r
 *                  player = null;\r
 *              },\r
 *              keyframe: onKeyFrame\r
 *          }\r
 *      });\r
 *\r
 *      player.start();\r
 *\r
 * If a keyframe can be handled immediately (synchronously), the listener would be:\r
 *\r
 *      function onKeyFrame () {\r
 *          handleKeyFrame();\r
 *      }\r
 *\r
 *  If the keyframe event is always handled asynchronously, then the event listener is only\r
 *  a bit more:\r
 *\r
 *      function onKeyFrame (p, eventDescriptor) {\r
 *          eventDescriptor.defer(); // pause event playback...\r
 *\r
 *          handleKeyFrame(function () {\r
 *              eventDescriptor.finish(); // ...resume event playback\r
 *          });\r
 *      }\r
 *\r
 * Finally, if the keyframe could be either handled synchronously or asynchronously (perhaps\r
 * differently by browser), a slightly more complex listener is required.\r
 *\r
 *      function onKeyFrame (p, eventDescriptor) {\r
 *          var async;\r
 *\r
 *          handleKeyFrame(function () {\r
 *              // either this callback is being called immediately by handleKeyFrame (in\r
 *              // which case async is undefined) or it is being called later (in which case\r
 *              // async will be true).\r
 *\r
 *              if (async) {\r
 *                  eventDescriptor.finish();\r
 *              } else {\r
 *                  async = false;\r
 *              }\r
 *          });\r
 *\r
 *          // either the callback was called (and async is now false) or it was not\r
 *          // called (and async remains undefined).\r
 *\r
 *          if (async !== false) {\r
 *              eventDescriptor.defer();\r
 *              async = true; // let the callback know that we have gone async\r
 *          }\r
 *      }\r
 */\r
Ext.define('Ext.ux.event.Player', function (Player) {\r
var defaults    = {},\r
    mouseEvents = {},\r
    keyEvents   = {},\r
    doc,\r
    \r
    //HTML events supported\r
    uiEvents  = {},\r
    \r
    //events that bubble by default\r
    bubbleEvents = {\r
        //scroll:     1,\r
        resize:     1,\r
        reset:      1,\r
        submit:     1,\r
        change:     1,\r
        select:     1,\r
        error:      1,\r
        abort:      1\r
    };\r
\r
Ext.each([ 'click', 'dblclick', 'mouseover', 'mouseout', 'mousedown', 'mouseup', 'mousemove' ],\r
    function (type) {\r
        bubbleEvents[type] = defaults[type] = mouseEvents[type] = {\r
            bubbles: true,\r
            cancelable: (type != "mousemove"), // mousemove cannot be cancelled\r
            detail: 1,\r
            screenX: 0,\r
            screenY: 0,\r
            clientX: 0,\r
            clientY: 0,\r
            ctrlKey: false,\r
            altKey: false,\r
            shiftKey: false,\r
            metaKey: false,\r
            button: 0\r
        };\r
    });\r
\r
Ext.each([ 'keydown', 'keyup', 'keypress' ],\r
    function (type) {\r
        bubbleEvents[type] = defaults[type] = keyEvents[type] = {\r
            bubbles: true,\r
            cancelable: true,\r
            ctrlKey: false,\r
            altKey: false,\r
            shiftKey: false,\r
            metaKey: false,\r
            keyCode: 0,\r
            charCode: 0\r
        };\r
    });\r
\r
Ext.each([ 'blur', 'change', 'focus', 'resize', 'scroll', 'select' ],\r
    function (type) {\r
        defaults[type] = uiEvents[type] = {\r
            bubbles: (type in bubbleEvents),\r
            cancelable: false,\r
            detail: 1\r
        };\r
    });\r
\r
var inputSpecialKeys = {\r
        8: function (target, start, end) { // backspace: 8,\r
            if (start < end) {\r
                target.value = target.value.substring(0, start) +\r
                               target.value.substring(end);\r
            } else if (start > 0) {\r
                target.value = target.value.substring(0, --start) +\r
                               target.value.substring(end);\r
            }\r
            this.setTextSelection(target, start, start);\r
        },\r
        46: function (target, start, end) { // delete: 46\r
            if (start < end) {\r
                target.value = target.value.substring(0, start) +\r
                               target.value.substring(end);\r
            } else if (start < target.value.length - 1) {\r
                target.value = target.value.substring(0, start) +\r
                               target.value.substring(start+1);\r
            }\r
            this.setTextSelection(target, start, start);\r
        }\r
    };\r
\r
return {\r
    extend: 'Ext.ux.event.Driver',\r
\r
    /**\r
     * @cfg {Array} eventQueue The event queue to playback. This must be provided before\r
     * the {@link #method-start} method is called.\r
     */\r
\r
    /**\r
     * @cfg {Object} keyFrameEvents An object that describes the events that should generate\r
     * keyframe events. For example, `{ click: true }` would generate keyframe events after\r
     * each `click` event.\r
     */\r
    keyFrameEvents: {\r
        click: true\r
    },\r
\r
    /**\r
     * @cfg {Boolean} pauseForAnimations True to pause event playback during animations, false\r
     * to ignore animations. Default is true.\r
     */\r
    pauseForAnimations: true,\r
\r
    /**\r
     * @cfg {Number} speed The playback speed multiplier. Default is 1.0 (to playback at the\r
     * recorded speed). A value of 2 would playback at 2x speed.\r
     */\r
    speed: 1.0,\r
\r
    stallTime: 0,\r
    \r
    _inputSpecialKeys: {\r
        INPUT: inputSpecialKeys,\r
\r
        TEXTAREA: Ext.apply({\r
            //13: function (target, start, end) { // enter: 8,\r
                //TODO ?\r
            //}\r
        }, inputSpecialKeys)\r
    },\r
\r
    tagPathRegEx: /(\w+)(?:\[(\d+)\])?/,\r
    \r
    /**\r
     * @event beforeplay\r
     * Fires before an event is played.\r
     * @param {Ext.ux.event.Player} this\r
     * @param {Object} eventDescriptor The event descriptor about to be played.\r
     */\r
\r
    /**\r
     * @event keyframe\r
     * Fires when this player reaches a keyframe. Typically, this is after events\r
     * like `click` are injected and any resulting animations have been completed.\r
     * @param {Ext.ux.event.Player} this\r
     * @param {Object} eventDescriptor The keyframe event descriptor.\r
     */\r
\r
    constructor: function (config) {\r
        var me = this;\r
        \r
        me.callParent(arguments);\r
\r
        me.timerFn = function () {\r
            me.onTick();\r
        };\r
        me.attachTo = me.attachTo || window;\r
\r
        doc = me.attachTo.document;\r
    },\r
\r
    /**\r
     * Returns the element given is XPath-like description.\r
     * @param {String} xpath The XPath-like description of the element.\r
     * @return {HTMLElement}\r
     */\r
    getElementFromXPath: function (xpath) {\r
        var me = this,\r
            parts = xpath.split('/'),\r
            regex = me.tagPathRegEx,\r
            i, n, m, count, tag, child,\r
            el = me.attachTo.document;\r
\r
        el = (parts[0] == '~') ? el.body\r
                    : el.getElementById(parts[0].substring(1)); // remove '#'\r
\r
        for (i = 1, n = parts.length; el && i < n; ++i) {\r
            m = regex.exec(parts[i]);\r
            count = m[2] ? parseInt(m[2], 10) : 1;\r
            tag = m[1].toUpperCase();\r
\r
            for (child = el.firstChild; child; child = child.nextSibling) {\r
                if (child.tagName == tag) {\r
                    if (count == 1) {\r
                        break;\r
                    }\r
                    --count;\r
                }\r
            }\r
\r
            el = child;\r
        }\r
\r
        return el;\r
    },\r
\r
    // Moving across a line break only counts as moving one character in a TextRange, whereas a line break in\r
    // the textarea value is two characters. This function corrects for that by converting a text offset into a\r
    // range character offset by subtracting one character for every line break in the textarea prior to the\r
    // offset\r
    offsetToRangeCharacterMove: function(el, offset) {\r
        return offset - (el.value.slice(0, offset).split("\r\n").length - 1);\r
    },\r
\r
    setTextSelection: function (el, startOffset, endOffset) {\r
        // See https://code.google.com/p/rangyinputs/source/browse/trunk/rangyinputs_jquery.js\r
        if (startOffset < 0) {\r
            startOffset += el.value.length;\r
        }\r
        if (endOffset == null) {\r
            endOffset = startOffset;\r
        }\r
        if (endOffset < 0) {\r
            endOffset += el.value.length;\r
        }\r
\r
        if (typeof el.selectionStart === "number") {\r
            el.selectionStart = startOffset;\r
            el.selectionEnd = endOffset;\r
        } else {\r
            var range = el.createTextRange();\r
            var startCharMove = this.offsetToRangeCharacterMove(el, startOffset);\r
\r
            range.collapse(true);\r
\r
            if (startOffset == endOffset) {\r
                range.move("character", startCharMove);\r
            } else {\r
                range.moveEnd("character", this.offsetToRangeCharacterMove(el, endOffset));\r
                range.moveStart("character", startCharMove);\r
            }\r
\r
            range.select();\r
        }\r
    },\r
\r
    getTimeIndex: function () {\r
        var t = this.getTimestamp() - this.stallTime;\r
        return t * this.speed;\r
    },\r
\r
    makeToken: function (eventDescriptor, signal) {\r
        var me = this,\r
            t0;\r
\r
        eventDescriptor[signal] = true;\r
\r
        eventDescriptor.defer = function () {\r
            eventDescriptor[signal] = false;\r
            t0 = me.getTime();\r
        };\r
\r
        eventDescriptor.finish = function () {\r
            eventDescriptor[signal] = true;\r
            me.stallTime += me.getTime() - t0;\r
\r
            me.schedule();\r
        };\r
    },\r
\r
    /**\r
     * This method is called after an event has been played to prepare for the next event.\r
     * @param {Object} eventDescriptor The descriptor of the event just played.\r
     */\r
    nextEvent: function (eventDescriptor) {\r
        var me = this,\r
            index = ++me.queueIndex;\r
\r
        // keyframe events are inserted after a keyFrameEvent is played.\r
        if (me.keyFrameEvents[eventDescriptor.type]) {\r
            Ext.Array.insert(me.eventQueue, index, [\r
                {keyframe: true, ts: eventDescriptor.ts}\r
            ]);\r
        }\r
    },\r
\r
    /**\r
     * This method returns the event descriptor at the front of the queue. This does not\r
     * dequeue the event. Repeated calls return the same object (until {@link #nextEvent}\r
     * is called).\r
     */\r
    peekEvent: function () {\r
        return this.eventQueue[this.queueIndex] || null;\r
    },\r
\r
    /**\r
     * Replaces an event in the queue with an array of events. This is often used to roll\r
     * up a multi-step pseudo-event and expand it just-in-time to be played. The process\r
     * for doing this in a derived class would be this:\r
     * \r
     *      Ext.define('My.Player', {\r
     *          extend: 'Ext.ux.event.Player',\r
     *\r
     *          peekEvent: function () {\r
     *              var event = this.callParent();\r
     *\r
     *              if (event.multiStepSpecial) {\r
     *                  this.replaceEvent(null, [\r
     *                      ... expand to actual events\r
     *                  ]);\r
     *\r
     *                  event = this.callParent(); // get the new next event\r
     *              }\r
     *\r
     *              return event;\r
     *          }\r
     *      });\r
     * \r
     * This method ensures that the `beforeplay` hook (if any) from the replaced event is\r
     * placed on the first new event and the `afterplay` hook (if any) is placed on the\r
     * last new event.\r
     * \r
     * @param {Number} index The queue index to replace. Pass `null` to replace the event\r
     * at the current `queueIndex`.\r
     * @param {Event[]} events The array of events with which to replace the specified\r
     * event.\r
     */\r
    replaceEvent: function (index, events) {\r
        for (var t, i = 0, n = events.length; i < n; ++i) {\r
            if (i) {\r
                t = events[i-1];\r
                delete t.afterplay;\r
                delete t.screenshot;\r
\r
                delete events[i].beforeplay;\r
            }\r
        }\r
\r
        Ext.Array.replace(this.eventQueue, (index == null) ? this.queueIndex : index,\r
                          1, events);\r
    },\r
\r
    /**\r
     * This method dequeues and injects events until it has arrived at the time index. If\r
     * no events are ready (based on the time index), this method does nothing.\r
     * @return {Boolean} True if there is more to do; false if not (at least for now).\r
     */\r
    processEvents: function () {\r
        var me = this,\r
            animations = me.pauseForAnimations && me.attachTo.Ext.fx.Manager.items,\r
            eventDescriptor;\r
\r
        while ((eventDescriptor = me.peekEvent()) !== null) {\r
            if (animations && animations.getCount()) {\r
                return true;\r
            }\r
            \r
            if (eventDescriptor.keyframe) {\r
                if (!me.processKeyFrame(eventDescriptor)) {\r
                    return false;\r
                }\r
                me.nextEvent(eventDescriptor);\r
            } else if (eventDescriptor.ts <= me.getTimeIndex() &&\r
                       me.fireEvent('beforeplay', me, eventDescriptor) !== false &&\r
                       me.playEvent(eventDescriptor)) {\r
                me.nextEvent(eventDescriptor);\r
            } else {\r
                return true;\r
            }\r
        }\r
\r
        me.stop();\r
        return false;\r
    },\r
\r
    /**\r
     * This method is called when a keyframe is reached. This will fire the keyframe event.\r
     * If the keyframe has been handled, true is returned. Otherwise, false is returned.\r
     * @param {Object} eventDescriptor The event descriptor of the keyframe.\r
     * @return {Boolean} True if the keyframe was handled, false if not.\r
     */\r
    processKeyFrame: function (eventDescriptor) {\r
        var me = this;\r
\r
        // only fire keyframe event (and setup the eventDescriptor) once...\r
        if (!eventDescriptor.defer) {\r
            me.makeToken(eventDescriptor, 'done');\r
            me.fireEvent('keyframe', me, eventDescriptor);\r
        }\r
\r
        return eventDescriptor.done;\r
    },\r
\r
    /**\r
     * Called to inject the given event on the specified target.\r
     * @param {HTMLElement} target The target of the event.\r
     * @param {Object} event The event to inject. The properties of this object should be\r
     * those of standard DOM events but vary based on the `type` property. For details on\r
     * event types and their properties, see the class documentation.\r
     */\r
    injectEvent: function (target, event) {\r
        var me = this,\r
            type = event.type,\r
            options = Ext.apply({}, event, defaults[type]),\r
            handler;\r
\r
        if (type === 'type') {\r
            handler = me._inputSpecialKeys[target.tagName];\r
            if (handler) {\r
                return me.injectTypeInputEvent(target, event, handler);\r
            }\r
            return me.injectTypeEvent(target, event);\r
        }\r
        if (type === 'focus' && target.focus) {\r
            target.focus();\r
            return true;\r
        }\r
        if (type === 'blur' && target.blur) {\r
            target.blur();\r
            return true;\r
        }\r
        if (type === 'scroll') {\r
            target.scrollLeft = event.pos[0];\r
            target.scrollTop = event.pos[1];\r
            return true;\r
        }\r
        if (type === 'mduclick') {\r
            return me.injectEvent(target, Ext.applyIf({ type: 'mousedown' }, event)) &&\r
                   me.injectEvent(target, Ext.applyIf({ type: 'mouseup' }, event)) &&\r
                   me.injectEvent(target, Ext.applyIf({ type: 'click' }, event));\r
        }\r
\r
        if (mouseEvents[type]){\r
            return Player.injectMouseEvent(target, options, me.attachTo);\r
        }\r
\r
        if (keyEvents[type]){\r
            return Player.injectKeyEvent(target, options, me.attachTo);\r
        }\r
\r
        if (uiEvents[type]){\r
            return Player.injectUIEvent(target, type,\r
                options.bubbles,\r
                options.cancelable,\r
                options.view || me.attachTo,\r
                options.detail);\r
        }\r
\r
        return false;\r
    },\r
\r
    injectTypeEvent: function (target, event) {\r
        var me = this,\r
            text = event.text,\r
            xlat = [],\r
            ch, chUp, i, n, sel, upper, isInput;\r
\r
        if (text) {\r
            delete event.text;\r
            upper = text.toUpperCase();\r
\r
            for (i = 0, n = text.length; i < n; ++i) {\r
                ch = text.charCodeAt(i);\r
                chUp = upper.charCodeAt(i);\r
\r
                xlat.push(\r
                    Ext.applyIf({type: 'keydown', charCode: chUp, keyCode: chUp}, event),\r
                    Ext.applyIf({type: 'keypress', charCode: ch, keyCode: ch},    event),\r
                    Ext.applyIf({type: 'keyup', charCode: chUp, keyCode: chUp},   event)\r
                );\r
            }\r
        } else {\r
            xlat.push(\r
                Ext.applyIf({type: 'keydown', charCode: event.keyCode}, event),\r
                Ext.applyIf({type: 'keyup',   charCode: event.keyCode}, event)\r
            );\r
        }\r
\r
        for (i = 0, n = xlat.length; i < n; ++i) {\r
            me.injectEvent(target, xlat[i]);\r
        }\r
\r
        return true;\r
    },\r
\r
    injectTypeInputEvent: function (target, event, handler) {\r
        var me = this,\r
            text = event.text,\r
            sel, n;\r
\r
        if (handler) {\r
            sel = me.getTextSelection(target);\r
\r
            if (text) {\r
                n = sel[0];\r
                target.value = target.value.substring(0, n) + text +\r
                               target.value.substring(sel[1]);\r
                n += text.length;\r
                me.setTextSelection(target, n, n);\r
            } else {\r
                if (!(handler = handler[event.keyCode])) {\r
                    // no handler for the special key for this element\r
                    if ('caret' in event) {\r
                        me.setTextSelection(target, event.caret, event.caret);\r
                    } else if (event.selection) {\r
                        me.setTextSelection(target, event.selection[0], event.selection[1]);\r
                    }\r
                    return me.injectTypeEvent(target, event);\r
                }\r
                handler.call(this, target, sel[0], sel[1]);\r
                return true;\r
            }\r
        }\r
\r
        return true;\r
    },\r
\r
    playEvent: function (eventDescriptor) {\r
        var me = this,\r
            target = me.getElementFromXPath(eventDescriptor.target),\r
            event;\r
\r
        if (!target) {\r
            // not present (yet)... wait for element present...\r
            // TODO - need a timeout here\r
            return false;\r
        }\r
\r
        if (!me.playEventHook(eventDescriptor, 'beforeplay')) {\r
            return false;\r
        }\r
\r
        if (!eventDescriptor.injected) {\r
            eventDescriptor.injected = true;\r
            event = me.translateEvent(eventDescriptor, target);\r
            me.injectEvent(target, event);\r
        }\r
\r
        return me.playEventHook(eventDescriptor, 'afterplay');\r
    },\r
\r
    playEventHook: function (eventDescriptor, hookName) {\r
        var me = this,\r
            doneName = hookName + '.done',\r
            firedName = hookName + '.fired',\r
            hook = eventDescriptor[hookName];\r
\r
        if (hook && !eventDescriptor[doneName]) {\r
            if (!eventDescriptor[firedName]) {\r
                eventDescriptor[firedName] = true;\r
                me.makeToken(eventDescriptor, doneName);\r
\r
                if (me.eventScope && Ext.isString(hook)) {\r
                    hook = me.eventScope[hook];\r
                }\r
\r
                if (hook) {\r
                    hook.call(me.eventScope || me, eventDescriptor);\r
                }\r
            }\r
            return false;\r
        }\r
\r
        return true;\r
    },\r
\r
    schedule: function () {\r
        var me = this;\r
        if (!me.timer) {\r
            me.timer = setTimeout(me.timerFn, 10);\r
        }\r
    },\r
\r
    _translateAcross: [\r
        'type',\r
        'button',\r
        'charCode',\r
        'keyCode',\r
        'caret',\r
        'pos',\r
        'text',\r
        'selection'\r
    ],\r
\r
    translateEvent: function (eventDescriptor, target) {\r
        var me = this,\r
            event = {},\r
            modKeys = eventDescriptor.modKeys || '',\r
            names = me._translateAcross,\r
            i = names.length,\r
            name, xy;\r
\r
        while (i--) {\r
            name = names[i];\r
            if (name in eventDescriptor) {\r
                event[name] = eventDescriptor[name];\r
            }\r
        }\r
\r
        event.altKey = modKeys.indexOf('A') > 0;\r
        event.ctrlKey = modKeys.indexOf('C') > 0;\r
        event.metaKey = modKeys.indexOf('M') > 0;\r
        event.shiftKey = modKeys.indexOf('S') > 0;\r
\r
        if (target && 'x' in eventDescriptor) {\r
            xy = Ext.fly(target).getXY();\r
            xy[0] += eventDescriptor.x;\r
            xy[1] += eventDescriptor.y;\r
        } else if ('x' in eventDescriptor) {\r
            xy = [ eventDescriptor.x, eventDescriptor.y ];\r
        } else if ('px' in eventDescriptor) {\r
            xy = [ eventDescriptor.px, eventDescriptor.py ];\r
        }\r
\r
        if (xy) {\r
            event.clientX = event.screenX = xy[0];\r
            event.clientY = event.screenY = xy[1];\r
        }\r
\r
        if (eventDescriptor.key) {\r
            event.keyCode = me.specialKeysByName[eventDescriptor.key];\r
        }\r
\r
        if (eventDescriptor.type === 'wheel') {\r
            if ('onwheel' in me.attachTo.document) {\r
                event.wheelX = eventDescriptor.dx;\r
                event.wheelY = eventDescriptor.dy;\r
            } else {\r
                event.type = 'mousewheel';\r
                event.wheelDeltaX = -40 * eventDescriptor.dx;\r
                event.wheelDeltaY = event.wheelDelta = -40 * eventDescriptor.dy;\r
            }\r
        }\r
    \r
        return event;\r
    },\r
\r
    //---------------------------------\r
    // Driver overrides\r
\r
    onStart: function () {\r
        var me = this;\r
\r
        me.queueIndex = 0;\r
        me.schedule();\r
    },\r
\r
    onStop: function () {\r
        var me = this;\r
\r
        if (me.timer) {\r
            clearTimeout(me.timer);\r
            me.timer = null;\r
        }\r
    },\r
\r
    //---------------------------------\r
\r
    onTick: function () {\r
        var me = this;\r
\r
        me.timer = null;\r
\r
        if (me.processEvents()) {\r
            me.schedule();\r
        }\r
    },\r
\r
    statics: {\r
        ieButtonCodeMap: {\r
            0: 1,\r
            1: 4,\r
            2: 2\r
        },\r
\r
        /**\r
         * Injects a key event using the given event information to populate the event\r
         * object.\r
         * \r
         * **Note:** `keydown` causes Safari 2.x to crash.\r
         * \r
         * @param {HTMLElement} target The target of the given event.\r
         * @param {Object} options Object object containing all of the event injection\r
         * options.\r
         * @param {String} options.type The type of event to fire. This can be any one of\r
         * the following: `keyup`, `keydown` and `keypress`.\r
         * @param {Boolean} [options.bubbles=true] `tru` if the event can be bubbled up.\r
         * DOM Level 3 specifies that all key events bubble by default.\r
         * @param {Boolean} [options.cancelable=true] `true` if the event can be canceled\r
         * using `preventDefault`. DOM Level 3 specifies that all key events can be\r
         * cancelled.\r
         * @param {Boolean} [options.ctrlKey=false] `true` if one of the CTRL keys is\r
         * pressed while the event is firing.\r
         * @param {Boolean} [options.altKey=false] `true` if one of the ALT keys is\r
         * pressed while the event is firing.\r
         * @param {Boolean} [options.shiftKey=false] `true` if one of the SHIFT keys is\r
         * pressed while the event is firing.\r
         * @param {Boolean} [options.metaKey=false] `true` if one of the META keys is\r
         * pressed while the event is firing.\r
         * @param {Number} [options.keyCode=0] The code for the key that is in use.\r
         * @param {Number} [options.charCode=0] The Unicode code for the character \r
         * associated with the key being used.\r
         * @param {Window} [view=window] The view containing the target. This is typically\r
         * the window object.\r
         * @private\r
         */\r
        injectKeyEvent: function (target, options, view) {\r
            var type = options.type,\r
                customEvent = null;\r
\r
            if (type === 'textevent') {\r
                type = 'keypress';\r
            }\r
            view = view || window;\r
\r
            //check for DOM-compliant browsers first\r
            if (doc.createEvent){\r
                try {\r
                    customEvent = doc.createEvent("KeyEvents");\r
\r
                    // Interesting problem: Firefox implemented a non-standard\r
                    // version of initKeyEvent() based on DOM Level 2 specs.\r
                    // Key event was removed from DOM Level 2 and re-introduced\r
                    // in DOM Level 3 with a different interface. Firefox is the\r
                    // only browser with any implementation of Key Events, so for\r
                    // now, assume it's Firefox if the above line doesn't error.\r
\r
                    // @TODO: Decipher between Firefox's implementation and a correct one.\r
                    customEvent.initKeyEvent(type, options.bubbles, options.cancelable,\r
                            view, options.ctrlKey, options.altKey, options.shiftKey,\r
                            options.metaKey, options.keyCode, options.charCode);\r
\r
                } catch (ex) {\r
                    // If it got here, that means key events aren't officially supported. \r
                    // Safari/WebKit is a real problem now. WebKit 522 won't let you\r
                    // set keyCode, charCode, or other properties if you use a\r
                    // UIEvent, so we first must try to create a generic event. The\r
                    // fun part is that this will throw an error on Safari 2.x. The\r
                    // end result is that we need another try...catch statement just to\r
                    // deal with this mess.\r
\r
                    try {\r
                        //try to create generic event - will fail in Safari 2.x\r
                        customEvent = doc.createEvent("Events");\r
\r
                    } catch (uierror) {\r
                        //the above failed, so create a UIEvent for Safari 2.x\r
                        customEvent = doc.createEvent("UIEvents");\r
\r
                    } finally {\r
                        customEvent.initEvent(type, options.bubbles, options.cancelable);\r
\r
                        customEvent.view = view;\r
                        customEvent.altKey = options.altKey;\r
                        customEvent.ctrlKey = options.ctrlKey;\r
                        customEvent.shiftKey = options.shiftKey;\r
                        customEvent.metaKey = options.metaKey;\r
                        customEvent.keyCode = options.keyCode;\r
                        customEvent.charCode = options.charCode;\r
                    }          \r
                }\r
\r
                target.dispatchEvent(customEvent);\r
\r
            } else if (doc.createEventObject) { //IE\r
                customEvent = doc.createEventObject();\r
\r
                customEvent.bubbles = options.bubbles;\r
                customEvent.cancelable = options.cancelable;\r
                customEvent.view = view;\r
                customEvent.ctrlKey = options.ctrlKey;\r
                customEvent.altKey = options.altKey;\r
                customEvent.shiftKey = options.shiftKey;\r
                customEvent.metaKey = options.metaKey;\r
\r
                // IE doesn't support charCode explicitly. CharCode should\r
                // take precedence over any keyCode value for accurate\r
                // representation.\r
\r
                customEvent.keyCode = (options.charCode > 0) ? options.charCode : options.keyCode;\r
\r
                target.fireEvent("on" + type, customEvent);  \r
\r
            } else {\r
                return false;\r
            }\r
\r
            return true;\r
        },\r
\r
        /**\r
         * Injects a mouse event using the given event information to populate the event\r
         * object.\r
         *\r
         * @param {HTMLElement} target The target of the given event.\r
         * @param {Object} options Object object containing all of the event injection\r
         * options.\r
         * @param {String} options.type The type of event to fire. This can be any one of\r
         * the following: `click`, `dblclick`, `mousedown`, `mouseup`, `mouseout`,\r
         * `mouseover` and `mousemove`.\r
         * @param {Boolean} [options.bubbles=true] `tru` if the event can be bubbled up.\r
         * DOM Level 2 specifies that all mouse events bubble by default.\r
         * @param {Boolean} [options.cancelable=true] `true` if the event can be canceled\r
         * using `preventDefault`. DOM Level 2 specifies that all mouse events except\r
         * `mousemove` can be cancelled. This defaults to `false` for `mousemove`.\r
         * @param {Boolean} [options.ctrlKey=false] `true` if one of the CTRL keys is\r
         * pressed while the event is firing.\r
         * @param {Boolean} [options.altKey=false] `true` if one of the ALT keys is\r
         * pressed while the event is firing.\r
         * @param {Boolean} [options.shiftKey=false] `true` if one of the SHIFT keys is\r
         * pressed while the event is firing.\r
         * @param {Boolean} [options.metaKey=false] `true` if one of the META keys is\r
         * pressed while the event is firing.\r
         * @param {Number} [options.detail=1] The number of times the mouse button has \r
         * been used.\r
         * @param {Number} [options.screenX=0] The x-coordinate on the screen at which point\r
         * the event occurred.\r
         * @param {Number} [options.screenY=0] The y-coordinate on the screen at which point\r
         * the event occurred.\r
         * @param {Number} [options.clientX=0] The x-coordinate on the client at which point\r
         * the event occurred.\r
         * @param {Number} [options.clientY=0] The y-coordinate on the client at which point\r
         * the event occurred.\r
         * @param {Number} [options.button=0] The button being pressed while the event is\r
         * executing. The value should be 0 for the primary mouse button (typically the\r
         * left button), 1 for the tertiary mouse button (typically the middle button),\r
         * and 2 for the secondary mouse button (typically the right button).\r
         * @param {HTMLElement} [options.relatedTarget=null] For `mouseout` events, this\r
         * is the element that the mouse has moved to. For `mouseover` events, this is\r
         * the element that the mouse has moved from. This argument is ignored for all\r
         * other events.\r
         * @param {Window} [view=window] The view containing the target. This is typically\r
         * the window object.\r
         * @private\r
         */\r
        injectMouseEvent: function (target, options, view) {\r
            var type = options.type,\r
                customEvent = null;\r
\r
            view = view || window;\r
\r
            //check for DOM-compliant browsers first\r
            if (doc.createEvent){\r
                customEvent = doc.createEvent("MouseEvents");\r
\r
                //Safari 2.x (WebKit 418) still doesn't implement initMouseEvent()\r
                if (customEvent.initMouseEvent){\r
                    customEvent.initMouseEvent(type, options.bubbles, options.cancelable,\r
                            view, options.detail, options.screenX, options.screenY,\r
                            options.clientX, options.clientY, options.ctrlKey,\r
                            options.altKey, options.shiftKey, options.metaKey,\r
                            options.button, options.relatedTarget);\r
                } else { //Safari\r
                    //the closest thing available in Safari 2.x is UIEvents\r
                    customEvent = doc.createEvent("UIEvents");\r
\r
                    customEvent.initEvent(type, options.bubbles, options.cancelable);\r
\r
                    customEvent.view = view;\r
                    customEvent.detail = options.detail;\r
                    customEvent.screenX = options.screenX;\r
                    customEvent.screenY = options.screenY;\r
                    customEvent.clientX = options.clientX;\r
                    customEvent.clientY = options.clientY;\r
                    customEvent.ctrlKey = options.ctrlKey;\r
                    customEvent.altKey = options.altKey;\r
                    customEvent.metaKey = options.metaKey;\r
                    customEvent.shiftKey = options.shiftKey;\r
                    customEvent.button = options.button;\r
                    customEvent.relatedTarget = options.relatedTarget;\r
                }\r
\r
                /*\r
                 * Check to see if relatedTarget has been assigned. Firefox\r
                 * versions less than 2.0 don't allow it to be assigned via\r
                 * initMouseEvent() and the property is readonly after event\r
                 * creation, so in order to keep YAHOO.util.getRelatedTarget()\r
                 * working, assign to the IE proprietary toElement property\r
                 * for mouseout event and fromElement property for mouseover\r
                 * event.\r
                 */\r
                if (options.relatedTarget && !customEvent.relatedTarget){\r
                    if (type == "mouseout"){\r
                        customEvent.toElement = options.relatedTarget;\r
                    } else if (type == "mouseover"){\r
                        customEvent.fromElement = options.relatedTarget;\r
                    }\r
                }\r
\r
                target.dispatchEvent(customEvent);\r
\r
            } else if (doc.createEventObject) { //IE\r
                customEvent = doc.createEventObject();\r
\r
                customEvent.bubbles = options.bubbles;\r
                customEvent.cancelable = options.cancelable;\r
                customEvent.view = view;\r
                customEvent.detail = options.detail;\r
                customEvent.screenX = options.screenX;\r
                customEvent.screenY = options.screenY;\r
                customEvent.clientX = options.clientX;\r
                customEvent.clientY = options.clientY;\r
                customEvent.ctrlKey = options.ctrlKey;\r
                customEvent.altKey = options.altKey;\r
                customEvent.metaKey = options.metaKey;\r
                customEvent.shiftKey = options.shiftKey;\r
                customEvent.button = Player.ieButtonCodeMap[options.button] || 0;\r
\r
                /*\r
                 * Have to use relatedTarget because IE won't allow assignment\r
                 * to toElement or fromElement on generic events. This keeps\r
                 * YAHOO.util.customEvent.getRelatedTarget() functional.\r
                 */\r
                customEvent.relatedTarget = options.relatedTarget;\r
\r
                target.fireEvent('on' + type, customEvent);\r
            } else {\r
                return false;\r
            }\r
\r
            return true;\r
        },\r
\r
        /**\r
         * Injects a UI event using the given event information to populate the event\r
         * object.\r
         * \r
         * @param {HTMLElement} target The target of the given event.\r
         * @param {Object} options\r
         * @param {String} options.type The type of event to fire. This can be any one of\r
         * the following: `click`, `dblclick`, `mousedown`, `mouseup`, `mouseout`,\r
         * `mouseover` and `mousemove`.\r
         * @param {Boolean} [options.bubbles=true] `tru` if the event can be bubbled up.\r
         * DOM Level 2 specifies that all mouse events bubble by default.\r
         * @param {Boolean} [options.cancelable=true] `true` if the event can be canceled\r
         * using `preventDefault`. DOM Level 2 specifies that all mouse events except\r
         * `mousemove` can be canceled. This defaults to `false` for `mousemove`.\r
         * @param {Number} [options.detail=1] The number of times the mouse button has been\r
         * used.\r
         * @param {Window} [view=window] The view containing the target. This is typically\r
         * the window object.\r
         * @private\r
         */\r
        injectUIEvent: function (target, options, view) {\r
            var customEvent = null;    \r
\r
            view = view || window;\r
\r
            //check for DOM-compliant browsers first\r
            if (doc.createEvent){\r
                //just a generic UI Event object is needed\r
                customEvent = doc.createEvent("UIEvents");\r
\r
                customEvent.initUIEvent(options.type, options.bubbles, options.cancelable,\r
                        view, options.detail);\r
\r
                target.dispatchEvent(customEvent);\r
\r
            } else if (doc.createEventObject){ //IE\r
                customEvent = doc.createEventObject();\r
\r
                customEvent.bubbles = options.bubbles;\r
                customEvent.cancelable = options.cancelable;\r
                customEvent.view = view;\r
                customEvent.detail = options.detail;\r
\r
                target.fireEvent("on" + options.type, customEvent);\r
\r
            } else {\r
                return false;\r
            }\r
\r
            return true;\r
        }\r
    } // statics\r
};\r
});\r