add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / EventManager.js

/**\r
 * @class Ext.EventManager\r
 * Registers event handlers on DOM elements.\r
 * \r
 * This class is deprecated.  Please use the Ext.dom.Element api to attach listeners to\r
 * DOM Elements.  For example:\r
 * \r
 *     var element = Ext.get('myId');\r
 *     \r
 *     element.on('click', function(e) {\r
 *         // event handling logic here\r
 *     });\r
 *\r
 * @singleton\r
 * @deprecated 5.0.0\r
 */\r
Ext.define('Ext.EventManager', {\r
    singleton: true,\r
\r
    mouseLeaveRe: /(mouseout|mouseleave)/,\r
    mouseEnterRe: /(mouseover|mouseenter)/,\r
\r
    /**\r
     * Appends an event handler to an element.  The shorthand version {@link #on} is equivalent.\r
     * Typically you will use {@link Ext.dom.Element#addListener} directly on an Element in favor of\r
     * calling this version.\r
     *\r
     * {@link Ext.EventManager#on} is an alias for {@link Ext.EventManager#addListener}.\r
     *\r
     * @param {String/Ext.dom.Element/HTMLElement/Window} el The html element or id to assign the event handler to.\r
     *\r
     * @param {String} eventName The name of the event to listen for.\r
     * May also be an object who's property names are event names.\r
     *\r
     * @param {Function/String} [handler] The handler function the event invokes. A String parameter\r
     * is assumed to be method name in `scope` object, or Element object if no scope is provided.\r
     * @param {Ext.event.Event} handler.event The {@link Ext.event.Event EventObject} describing the event.\r
     * @param {Ext.dom.Element} handler.target The Element which was the target of the event.\r
     * Note that this may be filtered by using the `delegate` option.\r
     * @param {Object} handler.options The options object from the addListener call.\r
     *\r
     * @param {Object} [scope] The scope (`this` reference) in which the handler function is executed.\r
     * Defaults to the Element.\r
     *\r
     * @param {Object} [options] An object containing handler configuration properties.\r
     * This may contain any of the following properties (See {@link Ext.dom.Element#addListener}\r
     * for examples of how to use these options.):\r
     * @param {Object} options.scope The scope (`this` reference) in which the handler function is executed. Defaults to the Element.\r
     * @param {String} options.delegate A simple selector to filter the target or look for a descendant of the target. See {@link Ext.dom.Query} for\r
     * information about simple selectors.\r
     * @param {Boolean} options.stopEvent True to stop the event. That is stop propagation, and prevent the default action.\r
     * @param {Boolean} options.preventDefault True to prevent the default action\r
     * @param {Boolean} options.stopPropagation True to prevent event propagation\r
     * @param {Boolean} options.normalized False to pass a browser event to the handler function instead of an Ext.event.Event\r
     * @param {Number} options.delay The number of milliseconds to delay the invocation of the handler after te event fires.\r
     * @param {Boolean} options.single True to add a handler to handle just the next firing of the event, and then remove itself.\r
     * @param {Number} options.buffer Causes the handler to be scheduled to run in an {@link Ext.util.DelayedTask} delayed\r
     * by the specified number of milliseconds. If the event fires again within that time, the original\r
     * handler is *not* invoked, but the new handler is scheduled in its place.\r
     * @param {Ext.dom.Element} options.target Only call the handler if the event was fired on the target Element,\r
     * *not* if the event was bubbled up from a child node.\r
     * @param {Boolean} options.capture `true` to initiate capture which will fire the listeners on the target Element *before* any descendant Elements.\r
     * Normal events start with the target element and propagate upward to ancestor elements, whereas captured events propagate from the top of the DOM\r
     * downward to descendant elements. This option is the same as the useCapture parameter in the javascript addEventListener method.\r
     */\r
    addListener: function(element, eventName, fn, scope, options) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager is deprecated. " +\r
            "Use Ext.dom.Element#addListener to attach an event listener.");\r
        //</debug>\r
        Ext.get(element).addListener(eventName, fn, scope, options);\r
    },\r
\r
    /**\r
     * Adds a listener to be notified when the browser window is resized and provides resize event buffering (100 milliseconds),\r
     * passes new viewport width and height to handlers.\r
     * @param {Function} fn      The handler function the window resize event invokes.\r
     * @param {Object}   scope   The scope (<code>this</code> reference) in which the handler function executes. Defaults to the browser window.\r
     * @param {Boolean}  [options] Options object as passed to {@link Ext.dom.Element#addListener}\r
     * @deprecated 5.0.0 Use {@link Ext#method-on Ext.on}('resize', fn) to attach a window resize listener.\r
     */\r
    onWindowResize: function(fn, scope, options) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager is deprecated. " +\r
            "Use Ext.on('resize', fn) to attach a window resize listener.");\r
        //</debug>\r
        Ext.GlobalEvents.on('resize', fn, scope, options);\r
    },\r
\r
    /**\r
     * Adds a listener to be notified when the browser window is unloaded.\r
     * @param {Function} fn      The handler function the window unload event invokes.\r
     * @param {Object}   scope   The scope (<code>this</code> reference) in which the handler function executes. Defaults to the browser window.\r
     * @param {Boolean}  options Options object as passed to {@link Ext.dom.Element#addListener}\r
     * @deprecated 5.0.0\r
     */\r
    onWindowUnload: function(fn, scope, options) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager is deprecated. " +\r
            "Use Ext.getWin().on('unload', fn) to attach a window unload listener.");\r
        //</debug>\r
        Ext.getWin().on('unload', fn, scope, options);\r
    },\r
\r
    /**\r
     * Recursively removes all previous added listeners from an element and its children.\r
     * Typically you will use {@link Ext.dom.Element#clearListeners} directly on an Element\r
     * in favor of calling this method.\r
     * @param {String/Ext.dom.Element/HTMLElement/Window} el The id or html element from which\r
     * to remove all event handlers.\r
     * @param {String} eventName (optional) The name of the event.\r
     * @deprecated 5.0.0\r
     */\r
    purgeElement: function(element, eventName) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager is deprecated. " +\r
            "Call clearListeners() on a Ext.dom.Element to remove all listeners.");\r
        //</debug>\r
        Ext.get(element).clearListeners();\r
    },\r
\r
    /**\r
     * Removes all event handers from an element.  Typically you will use {@link\r
     * Ext.dom.Element#clearListeners} directly on an Element in favor of calling this method.\r
     * @param {String/Ext.dom.Element/HTMLElement/Window} el The id or html element from which\r
     * to remove all event handlers.\r
     * @deprecated 5.0.0\r
     */\r
    removeAll: function(element) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager is deprecated. " +\r
            "Call clearListeners() on a Ext.dom.Element to remove all listeners.");\r
        //</debug>\r
        Ext.get(element).clearListeners();\r
    },\r
\r
    /**\r
     * Removes an event handler from an element.  The shorthand version {@link #un} is equivalent.  Typically\r
     * you will use {@link Ext.dom.Element#removeListener} directly on an Element in favor of calling this version.\r
     *\r
     * {@link Ext.EventManager#on} is an alias for {@link Ext.EventManager#addListener}.\r
     *\r
     * @param {String/Ext.dom.Element/HTMLElement/Window} el The id or html element from which to remove the listener.\r
     * @param {String} eventName The name of the event.\r
     * @param {Function} fn The handler function to remove. **This must be a reference to the function passed\r
     * into the {@link #addListener} call.**\r
     * @param {Object} scope If a scope (`this` reference) was specified when the listener was added,\r
     * then this must refer to the same object.\r
     */\r
    removeListener: function(element, eventName, fn, scope, options) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager is deprecated. " +\r
            "Use Ext.dom.Element#removeListener to remove an event listener.");\r
        //</debug>\r
        Ext.get(element).removeListener(eventName, fn, scope, options);\r
    },\r
\r
    /**\r
     * Removes the passed window resize listener.\r
     * @param {Function} fn        The method the event invokes\r
     * @param {Object}   scope    The scope of handler\r
     * @deprecated 5.0.0\r
     */\r
    removeResizeListener: function(fn, scope) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager is deprecated. " +\r
            "Use Ext.on('resize', fn) to detach a window resize listener.");\r
        //</debug>\r
        Ext.GlobalEvents.un('resize', fn, scope);\r
    },\r
\r
    /**\r
     * Removes the passed window unload listener.\r
     * @param {Function} fn        The method the event invokes\r
     * @param {Object}   scope    The scope of handler\r
     * @deprecated 5.0.0\r
     */\r
    removeUnloadListener: function(fn, scope) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager is deprecated. " +\r
            "Use Ext.getWin().un('unload', fn) to detach a window unload listener.");\r
        //</debug>\r
        Ext.getWin().un('unload', fn, scope);\r
    },\r
\r
    /**\r
     * Stop the event (preventDefault and stopPropagation)\r
     * @param {Event} event The event to stop\r
     * @deprecated 5.0.0\r
     */\r
    stopEvent: function(event) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager.stopEvent() is deprecated. " +\r
            "Call stopEvent() directly on the Ext.event.Event instance instead.");\r
        //</debug>\r
        this.stopPropagation(event);\r
        this.preventDefault(event);\r
    },\r
\r
    /**\r
     * Cancels bubbling of the event.\r
     * @param {Event} event The event to stop bubbling.\r
     * @deprecated 5.0.0\r
     */\r
    stopPropagation: function(event) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager.stopPropagation() is deprecated. " +\r
            "Call stopPropagation() directly on the Ext.event.Event instance instead.");\r
        //</debug>\r
        event = event.browserEvent || event;\r
        if (event.stopPropagation) {\r
            event.stopPropagation();\r
        } else {\r
            event.cancelBubble = true;\r
        }\r
    },\r
\r
    /**\r
     * Prevents the browsers default handling of the event.\r
     * @param {Event} event The event to prevent the default\r
     * @deprecated 5.0.0\r
     */\r
    preventDefault: function(event) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager.preventDefault() is deprecated. " +\r
            "Call preventDefault() directly on the Ext.event.Event instance instead.");\r
        //</debug>\r
        event = event.browserEvent || event;\r
        if (event.preventDefault) {\r
            event.preventDefault();\r
        } else {\r
            event.returnValue = false;\r
            // Some keys events require setting the keyCode to -1 to be prevented\r
            try {\r
              // all ctrl + X and F1 -> F12\r
              if (event.ctrlKey || event.keyCode > 111 && event.keyCode < 124) {\r
                  event.keyCode = -1;\r
              }\r
            } catch (e) {\r
                // see this outdated document http://support.microsoft.com/kb/934364/en-us for more info\r
            }\r
        }\r
    },\r
\r
    /**\r
     * Get the id of the element. If one has not been assigned, automatically assign it.\r
     * @param {HTMLElement/Ext.dom.Element} element The element to get the id for.\r
     * @return {String} id\r
     * @deprecated 5.0.0\r
     */\r
    getId: function(element) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager.getId() is deprecated. " +\r
            "Call Ext.get() to assign ids to elements.");\r
        //</debug>\r
        element = Ext.get(element);\r
        return element.id;\r
    },\r
\r
    /**\r
     * Gets the related target from the event.\r
     * @param {Object} event The event\r
     * @return {HTMLElement} The related target.\r
     * @deprecated 5.0.0\r
     */\r
    getRelatedTarget: function(event) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager.getRelatedTarget() is deprecated. " +\r
            "Call getRelatedTarget() directly on the Ext.event.Event instance instead.");\r
        //</debug>\r
        event = event.browserEvent || event;\r
        var target = event.relatedTarget;\r
        if (!target) {\r
            if (this.mouseLeaveRe.test(event.type)) {\r
                target = event.toElement;\r
            } else if (this.mouseEnterRe.test(event.type)) {\r
                target = event.fromElement;\r
            }\r
        }\r
        return this.resolveTextNode(target);\r
    },\r
\r
    /**\r
     * Gets the x coordinate from the event\r
     * @param {Object} event The event\r
     * @return {Number} The x coordinate\r
     * @deprecated 5.0.0\r
     */\r
    getPageX: function(event) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager.getPageX() is deprecated. " +\r
            "Call getX() directly on the Ext.event.Event instance instead.");\r
        //</debug>\r
        return this.getPageXY(event)[0];\r
    },\r
\r
    /**\r
     * Gets the x & y coordinate from the event\r
     * @param {Object} event The event\r
     * @return {Number[]} The x/y coordinate\r
     * @deprecated 5.0.0\r
     */\r
    getPageXY: function(event) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager.getPageXY() is deprecated. " +\r
            "Call getXY() directly on the Ext.event.Event instance instead.");\r
        //</debug>\r
        event = event.browserEvent || event;\r
        var x = event.pageX,\r
            y = event.pageY,\r
            docEl = document.documentElement,\r
            body = document.body;\r
\r
        // pageX/pageY not available (undefined, not null), use clientX/clientY instead\r
        if (!x && x !== 0) {\r
            x = event.clientX + (docEl && docEl.scrollLeft || body && body.scrollLeft || 0) - (docEl && docEl.clientLeft || body && body.clientLeft || 0);\r
            y = event.clientY + (docEl && docEl.scrollTop  || body && body.scrollTop  || 0) - (docEl && docEl.clientTop  || body && body.clientTop  || 0);\r
        }\r
        return [x, y];\r
    },\r
\r
    /**\r
     * Gets the y coordinate from the event\r
     * @param {Object} event The event\r
     * @return {Number} The y coordinate\r
     * @deprecated 5.0.0\r
     */\r
    getPageY: function(event) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager.getPageY() is deprecated. " +\r
            "Call getY() directly on the Ext.event.Event instance instead.");\r
        //</debug>\r
        return this.getPageXY(event)[1];\r
    },\r
\r
    /**\r
     * Gets the target of the event.\r
     * @param {Object} event The event\r
     * @return {HTMLElement} target\r
     * @deprecated 5.0.0\r
     */\r
    getTarget: function(event) {\r
        //<debug>\r
        Ext.log.warn("Ext.EventManager.getTarget() is deprecated. " +\r
            "Call getTarget() directly on the Ext.event.Event instance instead.");\r
        //</debug>\r
        event = event.browserEvent || event;\r
        return Ext.EventManager.resolveTextNode(event.target || event.srcElement);\r
    },\r
\r
    // technically no need to browser sniff this, however it makes\r
    // no sense to check this every time, for every event, whether\r
    // the string is equal.\r
    /**\r
     * @method\r
     * Resolve any text nodes accounting for browser differences.\r
     * @private\r
     * @param {HTMLElement} node The node\r
     * @return {HTMLElement} The resolved node\r
     * @deprecated 5.0.0\r
     */\r
    resolveTextNode: Ext.isGecko ?\r
        function(node) {\r
            if (node) {\r
                // work around firefox bug, https://bugzilla.mozilla.org/show_bug.cgi?id=101197\r
                var s = HTMLElement.prototype.toString.call(node);\r
                if (s !== '[xpconnect wrapped native prototype]' && s !== '[object XULElement]') {\r
                    return node.nodeType === 3 ? node.parentNode: node;\r
                }\r
            }\r
        }\r
        :\r
        function(node) {\r
            return node && node.nodeType === 3 ? node.parentNode: node;\r
        }\r
}, function(EventManager) {\r
    /**\r
     * @member Ext.EventManager\r
     * @method on\r
     * @inheritdoc Ext.EventManager#addListener\r
     */\r
    EventManager.on = EventManager.addListener;\r
\r
    /**\r
     * @member Ext.EventManager\r
     * @method un\r
     * @inheritdoc Ext.EventManager#removeListener\r
     */\r
    EventManager.un = EventManager.removeListener;\r
});