add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / util / Event.js

// @tag core\r
/**\r
 * Represents single event type that an Observable object listens to.\r
 * All actual listeners are tracked inside here.  When the event fires,\r
 * it calls all the registered listener functions.\r
 *\r
 * @private\r
 */\r
Ext.define('Ext.util.Event', function() {\r
  var arraySlice = Array.prototype.slice,\r
      arrayInsert = Ext.Array.insert,\r
      toArray = Ext.Array.toArray,\r
      fireArgs = {};\r
\r
  return {\r
    requires: 'Ext.util.DelayedTask',\r
\r
    /**\r
     * @property {Boolean} isEvent\r
     * `true` in this class to identify an object as an instantiated Event, or subclass thereof.\r
     */\r
    isEvent: true,\r
    \r
    // Private. Event suspend count\r
    suspended: 0,\r
\r
    noOptions: {},\r
\r
    constructor: function(observable, name) {\r
        this.name = name;\r
        this.observable = observable;\r
        this.listeners = [];\r
    },\r
\r
    addListener: function(fn, scope, options, caller, manager) {\r
        var me = this,\r
            added = false,\r
            observable = me.observable,\r
            eventName = me.name,\r
            listeners, listener, priority, isNegativePriority, highestNegativePriorityIndex,\r
            hasNegativePriorityIndex, length, index, i, listenerPriority;\r
\r
        //<debug>\r
        if (scope && !Ext._namedScopes[scope] && (typeof fn === 'string') && (typeof scope[fn] !== 'function')) {\r
            Ext.raise("No method named '" + fn + "' found on scope object");\r
        }\r
        //</debug>\r
\r
        if (me.findListener(fn, scope) === -1) {\r
            listener = me.createListener(fn, scope, options, caller, manager);\r
            if (me.firing) {\r
                // if we are currently firing this event, don't disturb the listener loop\r
                me.listeners = me.listeners.slice(0);\r
            }\r
            listeners = me.listeners;\r
            index = length = listeners.length;\r
            priority = options && options.priority;\r
            highestNegativePriorityIndex = me._highestNegativePriorityIndex;\r
            hasNegativePriorityIndex = highestNegativePriorityIndex !== undefined;\r
            if (priority) {\r
                // Find the index at which to insert the listener into the listeners array,\r
                // sorted by priority highest to lowest.\r
                isNegativePriority = (priority < 0);\r
                if (!isNegativePriority || hasNegativePriorityIndex) {\r
                    // If the priority is a positive number, or if it is a negative number\r
                    // and there are other existing negative priority listenrs, then we\r
                    // need to calcuate the listeners priority-order index.\r
                    // If the priority is a negative number, begin the search for priority\r
                    // order index at the index of the highest existing negative priority\r
                    // listener, otherwise begin at 0\r
                    for(i = (isNegativePriority ? highestNegativePriorityIndex : 0); i < length; i++) {\r
                        // Listeners created without options will have no "o" property\r
                        listenerPriority = listeners[i].o ? listeners[i].o.priority||0 : 0;\r
                        if (listenerPriority < priority) {\r
                            index = i;\r
                            break;\r
                        }\r
                    }\r
                } else {\r
                    // if the priority is a negative number, and there are no other negative\r
                    // priority listeners, then no calculation is needed - the negative\r
                    // priority listener gets appended to the end of the listeners array.\r
                    me._highestNegativePriorityIndex = index;\r
                }\r
            } else if (hasNegativePriorityIndex) {\r
                // listeners with a priority of 0 or undefined are appended to the end of\r
                // the listeners array unless there are negative priority listeners in the\r
                // listeners array, then they are inserted before the highest negative\r
                // priority listener.\r
                index = highestNegativePriorityIndex;\r
            }\r
\r
            if (!isNegativePriority && index <= highestNegativePriorityIndex) {\r
                me._highestNegativePriorityIndex ++;\r
            }\r
            if (index === length) {\r
                listeners[length] = listener;\r
            } else {\r
                arrayInsert(listeners, index, [listener]);\r
            }\r
\r
            if (observable.isElement) {\r
                // It is the role of Ext.util.Event (vs Ext.Element) to handle subscribe/\r
                // unsubscribe because it is the lowest level place to intercept the\r
                // listener before it is added/removed.  For addListener this could easily\r
                // be done in Ext.Element's doAddListener override, but since there are\r
                // multiple paths for listener removal (un, clearListeners), it is best\r
                // to keep all subscribe/unsubscribe logic here.\r
                observable._getPublisher(eventName).subscribe(\r
                    observable,\r
                    eventName,\r
                    options.delegated !== false,\r
                    options.capture\r
                );\r
            }\r
\r
            added = true;\r
        }\r
\r
        return added;\r
    },\r
\r
    createListener: function(fn, scope, o, caller, manager) {\r
        var me = this,\r
            namedScope = Ext._namedScopes[scope],\r
            listener = {\r
                fn: fn,\r
                scope: scope,\r
                ev: me,\r
                caller: caller,\r
                manager: manager,\r
                namedScope: namedScope,\r
                defaultScope: namedScope ? (scope || me.observable) : undefined,\r
                lateBound: typeof fn === 'string'\r
            },\r
            handler = fn,\r
            wrapped = false,\r
            type;\r
\r
        // The order is important. The 'single' wrapper must be wrapped by the 'buffer' and 'delayed' wrapper\r
        // because the event removal that the single listener does destroys the listener's DelayedTask(s)\r
        if (o) {\r
            listener.o = o;\r
            if (o.single) {\r
                handler = me.createSingle(handler, listener, o, scope);\r
                wrapped = true;\r
            }\r
            if (o.target) {\r
                handler = me.createTargeted(handler, listener, o, scope, wrapped);\r
                wrapped = true;\r
            }\r
            if (o.delay) {\r
                handler = me.createDelayed(handler, listener, o, scope, wrapped);\r
                wrapped = true;\r
            }\r
            if (o.buffer) {\r
                handler = me.createBuffered(handler, listener, o, scope, wrapped);\r
                wrapped = true;\r
            }\r
\r
            if (me.observable.isElement) {\r
                // If the event type was translated, e.g. mousedown -> touchstart, we need to save\r
                // the original type in the listener object so that the Ext.event.Event object can\r
                // reflect the correct type at firing time\r
                type = o.type;\r
                if (type) {\r
                    listener.type = type;\r
                }\r
            }\r
        }\r
\r
        listener.fireFn = handler;\r
        listener.wrapped = wrapped;\r
        return listener;\r
    },\r
\r
    findListener: function(fn, scope) {\r
        var listeners = this.listeners,\r
            i = listeners.length,\r
            listener;\r
\r
        while (i--) {\r
            listener = listeners[i];\r
            if (listener) {\r
                // use ==, not === for scope comparison, so that undefined and null are equal\r
                if (listener.fn === fn && listener.scope == scope) {\r
                    return i;\r
                }\r
            }\r
        }\r
\r
        return - 1;\r
    },\r
\r
    removeListener: function(fn, scope, index) {\r
        var me = this,\r
            removed = false,\r
            observable = me.observable,\r
            eventName = me.name,\r
            listener, highestNegativePriorityIndex, options,\r
            k, manager, managedListeners, managedListener, i;\r
\r
        index = index || me.findListener(fn, scope);\r
\r
        if (index != -1) {\r
            listener = me.listeners[index];\r
            options = listener.o;\r
            highestNegativePriorityIndex = me._highestNegativePriorityIndex;\r
\r
            if (me.firing) {\r
                me.listeners = me.listeners.slice(0);\r
            }\r
\r
            // cancel and remove a buffered handler that hasn't fired yet\r
            if (listener.task) {\r
                listener.task.cancel();\r
                delete listener.task;\r
            }\r
\r
            // cancel and remove all delayed handlers that haven't fired yet\r
            k = listener.tasks && listener.tasks.length;\r
            if (k) {\r
                while (k--) {\r
                    listener.tasks[k].cancel();\r
                }\r
                delete listener.tasks;\r
            }\r
\r
            // Remove this listener from the listeners array\r
            // We can use splice directly. The IE8 bug which Ext.Array works around only affects *insertion*\r
            // http://social.msdn.microsoft.com/Forums/en-US/iewebdevelopment/thread/6e946d03-e09f-4b22-a4dd-cd5e276bf05a/\r
            me.listeners.splice(index, 1);\r
\r
            manager = listener.manager;\r
            if (manager) {\r
                // If this is a managed listener we need to remove it from the manager's\r
                // managedListeners array.  This ensures that if we listen using mon\r
                // and then remove without using mun, the managedListeners array is updated\r
                // accordingly, for example\r
                //\r
                //     manager.on(target, 'foo', fn);\r
                //\r
                //     target.un('foo', fn);\r
                managedListeners = manager.managedListeners;\r
                if (managedListeners) {\r
                    for (i = managedListeners.length; i--;) {\r
                        managedListener = managedListeners[i];\r
                        if (managedListener.item === me.observable && managedListener.ename === eventName &&\r
                                managedListener.fn === fn && managedListener.scope === scope) {\r
                            managedListeners.splice(i, 1);\r
                        }\r
                    }\r
                }\r
            }\r
\r
            // if the listeners array contains negative priority listeners, adjust the\r
            // internal index if needed.\r
            if (highestNegativePriorityIndex) {\r
                if (index < highestNegativePriorityIndex) {\r
                    me._highestNegativePriorityIndex --;\r
                } else if (index === highestNegativePriorityIndex && index === me.listeners.length) {\r
                    delete me._highestNegativePriorityIndex;\r
                }\r
            }\r
\r
            if (observable.isElement) {\r
                observable._getPublisher(eventName).unsubscribe(\r
                    observable,\r
                    eventName,\r
                    options.delegated !== false,\r
                    options.capture\r
                );\r
            }\r
\r
            removed = true;\r
        }\r
\r
        return removed;\r
    },\r
\r
    // Iterate to stop any buffered/delayed events\r
    clearListeners: function() {\r
        var listeners = this.listeners,\r
            i = listeners.length,\r
            listener;\r
\r
        while (i--) {\r
            listener = listeners[i];\r
            this.removeListener(listener.fn, listener.scope);\r
        }\r
    },\r
\r
    suspend: function() {\r
        ++this.suspended;\r
    },\r
\r
    resume: function() {\r
        if (this.suspended) {\r
            --this.suspended;\r
        }\r
    },\r
    \r
    isSuspended: function() {\r
        return this.suspended > 0;\r
    },\r
\r
    fireDelegated: function(firingObservable, args) {\r
        this.firingObservable = firingObservable;\r
        return this.fire.apply(this, args);\r
    },\r
\r
    fire: function() {\r
        var me = this,\r
            listeners = me.listeners,\r
            count = listeners.length,\r
            observable = me.observable,\r
            isElement = observable.isElement,\r
            isComponent = observable.isComponent,\r
            firingObservable = me.firingObservable,\r
            options, delegate, fireInfo, i, args, listener, len, delegateEl, currentTarget,\r
            type, chained, firingArgs, e, fireFn, fireScope;\r
\r
        if (!me.suspended && count > 0) {\r
            me.firing = true;\r
            args = arguments.length ? arraySlice.call(arguments, 0) : [];\r
            len = args.length;\r
            if (isElement) {\r
                e = args[0];\r
            }\r
            for (i = 0; i < count; i++) {\r
                listener = listeners[i];\r
                options = listener.o;\r
\r
                if (isElement) {\r
                    if (currentTarget) {\r
                        // restore the previous currentTarget if we changed it last time\r
                        // around the loop while processing the delegate option.\r
                        e.setCurrentTarget(currentTarget);\r
                    }\r
\r
                    // For events that have been translated to provide device compatibility,\r
                    // e.g. mousedown -> touchstart, we want the event object to reflect the\r
                    // type that was originally listened for, not the type of the actual event\r
                    // that fired. The listener's "type" property reflects the original type.\r
                    type = listener.type;\r
\r
                    if (type) {\r
                        // chain a new object to the event object before changing the type.\r
                        // This is more efficient than creating a new event object, and we\r
                        // don't want to change the type of the original event because it may\r
                        // be used asynchronously by other handlers\r
                        chained = e;\r
                        e = args[0] = chained.chain({ type: type });\r
                    }\r
\r
                    // In Ext4 Ext.EventObject was a singleton event object that was reused as events\r
                    // were fired.  Set Ext.EventObject to the last fired event for compatibility.\r
                    Ext.EventObject = e;\r
                }\r
\r
                firingArgs = args;\r
\r
                if (options) {\r
                    delegate = options.delegate;\r
                    if (delegate) {\r
                        if (isElement) {\r
                            // prepending the currentTarget.id to the delegate selector\r
                            // allows us to match selectors such as "> div"\r
                            delegateEl = e.getTarget('#' + e.currentTarget.id + ' ' + delegate);\r
                            if (delegateEl) {\r
                                args[1] = delegateEl;\r
                                // save the current target before changing it to the delegateEl\r
                                // so that we can restore it next time around\r
                                currentTarget = e.currentTarget;\r
                                e.setCurrentTarget(delegateEl);\r
                            } else {\r
                                continue;\r
                            }\r
                        } else if (isComponent &&\r
                                !firingObservable.is('#' + observable.id + ' ' + options.delegate)) {\r
                            continue;\r
                        }\r
                    }\r
                    \r
                    if (isElement) {\r
                        if (options.preventDefault) {\r
                            e.preventDefault();\r
                        }\r
    \r
                        if (options.stopPropagation) {\r
                            e.stopPropagation();\r
                        }\r
    \r
                        if (options.stopEvent) {\r
                            e.stopEvent();\r
                        }\r
                    }\r
\r
                    args[len] = options;\r
\r
                    if (options.args) {\r
                        firingArgs = options.args.concat(args);\r
                    }\r
                }\r
\r
                fireInfo = me.getFireInfo(listener);\r
                fireFn = fireInfo.fn;\r
                fireScope = fireInfo.scope;\r
                \r
                // We don't want to keep closure and scope on the Event prototype!\r
                fireInfo.fn = fireInfo.scope = null;\r
                \r
                if (fireFn.apply(fireScope, firingArgs) === false) {\r
                    Ext.EventObject = null;\r
                    \r
                    return (me.firing = false);\r
                }\r
\r
                if (chained) {\r
                    // if we chained the event object for type translation we need to\r
                    // un-chain it before proceeding to process the next listener, which\r
                    // may not be a translated event.\r
                    e = args[0] = chained;\r
                    chained = null;\r
                }\r
                \r
                // We don't guarantee Ext.EventObject existence outside of the immediate\r
                // event propagation scope\r
                Ext.EventObject = null;\r
            }\r
        }\r
        \r
        me.firing = false;\r
        \r
        return true;\r
    },\r
\r
    getFireInfo: function(listener, fromWrapped) {\r
        var observable = this.observable,\r
            fireFn = listener.fireFn,\r
            scope = listener.scope,\r
            namedScope = listener.namedScope,\r
            fn;\r
\r
        // If we are called with a wrapped listener, only attempt to do scope\r
        // resolution if we are explicitly called by the last wrapped function\r
        if (!fromWrapped && listener.wrapped) {\r
            fireArgs.fn = fireFn;\r
            return fireArgs;\r
        }\r
            \r
        fn = fromWrapped ? listener.fn : fireFn;\r
        //<debug>\r
        var name = fn;\r
\r
        //</debug>\r
        if (listener.lateBound) {\r
            // handler is a function name - need to resolve it to a function reference\r
            if (!scope || namedScope) {\r
                // Only invoke resolveListenerScope if the user did not specify a scope,\r
                // or if the user specified a named scope.  Named function handlers that\r
                // use an arbitrary object as the scope just skip this part, and just\r
                // use the given scope object to resolve the method.\r
                scope = (listener.caller || observable).resolveListenerScope(listener.defaultScope);\r
            }\r
            //<debug>\r
            if (!scope) {\r
                Ext.raise('Unable to dynamically resolve scope for "' + listener.ev.name + '" listener on ' + this.observable.id);\r
            }\r
\r
            if (!Ext.isFunction(scope[fn])) {\r
                Ext.raise('No method named "' + fn + '" on ' +\r
                    (scope.$className || 'scope object.'));\r
            }\r
            //</debug>\r
\r
            fn = scope[fn];\r
        } else if (namedScope && namedScope.isController) {\r
            // If handler is a function reference and scope:'controller' was requested\r
            // we'll do our best to look up a controller.\r
            scope = (listener.caller || observable).resolveListenerScope(listener.defaultScope);\r
            //<debug>\r
            if (!scope) {\r
                Ext.raise('Unable to dynamically resolve scope for "' + listener.ev.name + '" listener on ' + this.observable.id);\r
            }\r
            //</debug>\r
        } else if (!scope || namedScope) {\r
            // If handler is a function reference we use the observable instance as\r
            // the default scope\r
            scope = observable;\r
        }\r
\r
        // We can only ever be firing one event at a time, so just keep\r
        // overwriting tghe object we've got in our closure, otherwise we'll be\r
        // creating a whole bunch of garbage objects\r
        fireArgs.fn = fn;\r
        fireArgs.scope = scope;\r
        //<debug>\r
        if (!fn) {\r
            Ext.raise('Unable to dynamically resolve method "' + name + '" on ' + this.observable.$className);\r
        }\r
        //</debug>\r
        return fireArgs;\r
    },\r
\r
    createTargeted: function (handler, listener, o, scope, wrapped) {\r
        return function(){\r
            if (o.target === arguments[0]) {\r
                var fireInfo;\r
\r
                if (!wrapped) {\r
                    fireInfo = listener.ev.getFireInfo(listener, true);\r
                    handler = fireInfo.fn;\r
                    scope = fireInfo.scope;\r
                    \r
                    // We don't want to keep closure and scope references on the Event prototype!\r
                    fireInfo.fn = fireInfo.scope = null;\r
                }\r
\r
                return handler.apply(scope, arguments);\r
            }\r
        };\r
    },\r
\r
    createBuffered: function (handler, listener, o, scope, wrapped) {\r
        listener.task = new Ext.util.DelayedTask();\r
        return function() {\r
            var fireInfo;\r
\r
            if (!wrapped) {\r
                fireInfo = listener.ev.getFireInfo(listener, true);\r
                handler = fireInfo.fn;\r
                scope = fireInfo.scope;\r
                \r
                // We don't want to keep closure and scope references on the Event prototype!\r
                fireInfo.fn = fireInfo.scope = null;\r
            }\r
\r
            listener.task.delay(o.buffer, handler, scope, toArray(arguments));\r
        };\r
    },\r
\r
    createDelayed: function (handler, listener, o, scope, wrapped) {\r
        return function() {\r
            var task = new Ext.util.DelayedTask(),\r
                fireInfo;\r
\r
            if (!wrapped) {\r
                fireInfo = listener.ev.getFireInfo(listener, true);\r
                handler = fireInfo.fn;\r
                scope = fireInfo.scope;\r
                \r
                // We don't want to keep closure and scope references on the Event prototype!\r
                fireInfo.fn = fireInfo.scope = null;\r
            }\r
                \r
            if (!listener.tasks) {\r
                listener.tasks = [];\r
            }\r
            listener.tasks.push(task);\r
            task.delay(o.delay || 10, handler, scope, toArray(arguments));\r
        };\r
    },\r
\r
    createSingle: function (handler, listener, o, scope, wrapped) {\r
        return function() {\r
            var event = listener.ev,\r
                fireInfo;\r
\r
\r
            if (event.removeListener(listener.fn, scope) && event.observable) {\r
                // Removing from a regular Observable-owned, named event (not an anonymous\r
                // event such as Ext's readyEvent): Decrement the listeners count\r
                event.observable.hasListeners[event.name]--;\r
            }\r
\r
            if (!wrapped) {\r
                fireInfo = event.getFireInfo(listener, true);\r
                handler = fireInfo.fn;\r
                scope = fireInfo.scope;\r
                \r
                // We don't want to keep closure and scope references on the Event prototype!\r
                fireInfo.fn = fireInfo.scope = null;\r
            }\r
            \r
            return handler.apply(scope, arguments);\r
        };\r
    }\r
  };\r
});\r