add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / env / Ready.js

/**\r
 * This class manages ready detection and handling. Direct use of this class is not\r
 * recommended. Instead use `Ext.onReady`:\r
 * \r
 *      Ext.onReady(function () {\r
 *          // DOM and Framework are ready...\r
 *      });\r
 *\r
 * ## DOM Ready\r
 *\r
 * The lowest-level of readiness is DOM readiness. This level implies only that the document\r
 * body exists. Many things require the DOM to be ready for manipulation. If that is all\r
 * that is required, the `Ext.onDocumentReady` method can be called to register a callback\r
 * to be called as soon as the DOM is ready:\r
 *\r
 *      Ext.onDocumentReady(function () {\r
 *          // the document body is ready\r
 *      });\r
 *\r
 * ## Framework Ready\r
 *\r
 * In production builds of applications it is common to have all of the code loaded before\r
 * DOM ready, so the need to wait for "onReady" is often confused with only that concern.\r
 * This is easy to understand, at least in part because historically `Ext.onReady` only\r
 * waited for DOM ready.\r
 *\r
 * With the introduction of `Ext.Loader`, however, it became common for DOM ready to occur\r
 * in the middle of dynamically loading code. If application code were executed at that\r
 * time, any use of the yet-to-be-loaded classes would throw errors. As a consequence of\r
 * this, the `Ext.onReady` mechanism was extended to wait for both DOM ready *and* all of\r
 * the required classes to be loaded.\r
 *\r
 * When the framework enters or leaves a state where it is not ready (for example, the\r
 * first dynamic load is requested or last load completes), `Ext.env.Ready` is informed.\r
 * For example:\r
 *\r
 *      Ext.env.Ready.block();\r
 *\r
 *      //...\r
 *\r
 *      Ext.env.Ready.unblock();\r
 *\r
 * When there are no blocks and the DOM is ready, the Framework is ready and the "onReady"\r
 * callbacks are called.\r
 *\r
 * Priority can be used to control the ordering of onReady listeners, for example:\r
 *\r
 *     Ext.onReady(function() {\r
 *\r
 *     }, null, {\r
 *         priority: 100\r
 *     });\r
 *\r
 * Ready listeners with higher priorities will run sooner than those with lower priorities,\r
 * the default priority being `0`.  Internally the framework reserves priorities of 1000\r
 * or greater, and -1000 or lesser for onReady handlers that must run before or after\r
 * any application code.  Applications should stick to using priorities in the -999 - 999\r
 * range. The following priorities are currently in use by the framework:\r
 *\r
 * - Element_scroll rtl override: `1001`\r
 * - Event system initialization: `2000`\r
 * - Ext.dom.Element: `1500`\r
 *\r
 * @class Ext.env.Ready\r
 * @singleton\r
 * @private\r
 * @since 5.0.0\r
 */\r
Ext.env.Ready = {\r
// @define Ext.env.Ready\r
// @require Ext.env.Browser\r
// @require Ext.env.OS\r
// @require Ext.env.Feature\r
\r
    /**\r
     * @property {Number} blocks The number of Framework readiness blocks.\r
     * @private\r
     */\r
    blocks: (location.search || '').indexOf('ext-pauseReadyFire') > 0 ? 1 : 0,\r
\r
    /**\r
     * @property {Number} bound This property stores the state of event listeners bound\r
     * to the document or window to detect ready state.\r
     * @private\r
     */\r
    bound: 0,\r
\r
    /**\r
     * @property {Number} [delay=1]\r
     * This allows the DOM listener thread to complete (usually desirable with mobWebkit,\r
     * Gecko) before firing the entire onReady chain (high stack load on Loader). For mobile\r
     * devices when running from Home Screen, the splash screen will not disappear until\r
     * all external resource requests finish. This delay clears the splash screen.\r
     * @private\r
     */\r
    delay: 1,\r
\r
    //<debug>\r
    /**\r
     * @property {Event[]} events An array of events that have triggered ready state. This\r
     * is for diagnostic purposes only and is only available in debug builds.\r
     * An array\r
     * @private\r
     */\r
    events: [],\r
    //</debug>\r
\r
    /**\r
     * @property {Boolean} firing This property is `true` when we currently calling the\r
     * listeners.\r
     * @private\r
     */\r
    firing: false,\r
\r
    /**\r
     * @property {Number} generation A counter of the number of mutations of `listeners`.\r
     * @private\r
     */\r
    generation: 0,\r
\r
    /**\r
     * @property {Object[]} listeners The set of listeners waiting for ready.\r
     * @private\r
     */\r
    listeners: [],\r
\r
    /**\r
     * @property {Number} nextId A counter so we can assign listeners an `id` to keep\r
     * them in FIFO order.\r
     * @private\r
     */\r
    nextId: 0,\r
\r
    /**\r
     * @property {Number} sortGeneration A captured value of `generation` that indicates\r
     * when the `listeners` were last sorted.\r
     * @private\r
     */\r
    sortGeneration: 0,\r
\r
    /**\r
     * @property {Number} state\r
     * Holds the current ready state as managed by this class. The values possible are:\r
     * \r
     *   * 0 - Not ready.\r
     *   * 1 - Ready detected but listeners are not yet notified.\r
     *   * 2 - Ready detected and listeners are notified. See also `firing`.\r
     *   \r
     * @private\r
     */\r
    state: 0,\r
\r
    /**\r
     * @property {Object} timer The handle from `setTimeout` for the delayed notification\r
     * of ready.\r
     * @private\r
     */\r
    timer: null,\r
\r
    /**\r
     * Binds the appropriate browser event for checking if the DOM has loaded.\r
     * @private\r
     */\r
    bind: function () {\r
        var me = Ext.env.Ready,\r
            doc = document;\r
\r
        if (!me.bound) {\r
            // Test scenario where load is dynamic AFTER window.load\r
            if (doc.readyState === 'complete') {\r
                // Firefox4+ got support for this state, others already do.\r
                me.onReadyEvent({\r
                    type: doc.readyState || 'body'\r
                });\r
            } else {\r
                me.bound = 1;\r
                if (Ext.browser.is.PhoneGap && !Ext.os.is.Desktop) {\r
                    me.bound = 2;\r
                    doc.addEventListener('deviceready', me.onReadyEvent, false);\r
                }\r
                doc.addEventListener('DOMContentLoaded', me.onReadyEvent, false);\r
                window.addEventListener('load', me.onReadyEvent, false);\r
            }\r
        }\r
    },\r
\r
    block: function () {\r
        ++this.blocks;\r
        Ext.isReady = false;\r
    },\r
\r
    /**\r
     * This method starts the process of firing the ready event. This may be delayed based\r
     * on the `delay` property.\r
     * @private\r
     */\r
    fireReady: function () {\r
        var me = Ext.env.Ready;\r
\r
        if (!me.state) {\r
            Ext._readyTime = Ext.ticks();\r
            Ext.isDomReady = true;\r
            me.state = 1;\r
\r
            // As soon as we transition to domready, complete the feature detection:\r
            Ext.feature.detect(true);\r
\r
            if (!me.delay) {\r
                me.handleReady();\r
            } else if (navigator.standalone) {\r
                // When running from Home Screen, the splash screen will not disappear\r
                // until all external resource requests finish.\r
                // The first timeout clears the splash screen\r
                // The second timeout allows inital HTML content to be displayed\r
                me.timer = Ext.defer(function() {\r
                    me.timer = null;\r
                    me.handleReadySoon();\r
                }, 1);\r
            } else {\r
                me.handleReadySoon();\r
            }\r
        }\r
    },\r
\r
    /**\r
     * This method iterates over the `listeners` and invokes them. This advances the\r
     * `state` from 1 to 2 and ensure the proper subset of `listeners` are invoked.\r
     * @private\r
     */\r
    handleReady: function () {\r
        var me = this;\r
\r
        if (me.state === 1) {\r
            me.state = 2;\r
\r
            Ext._beforeReadyTime = Ext.ticks();\r
            me.invokeAll();\r
            Ext._afterReadyTime = Ext.ticks();\r
        }\r
    },\r
\r
    /**\r
     * This method is called to schedule a call to `handleReady` using a `setTimeout`. It\r
     * ensures that only one timer is pending.\r
     * @param {Number} [delay] If passed, this overrides the `delay` property.\r
     * @private\r
     */\r
    handleReadySoon: function (delay) {\r
        var me = this;\r
\r
        if (!me.timer) {\r
            me.timer = Ext.defer(function () {\r
                me.timer = null;\r
                me.handleReady();\r
            }, delay || me.delay);\r
        }\r
    },\r
\r
    /**\r
     * This method invokes the given `listener` instance based on its options.\r
     * @param {Object} listener\r
     */\r
    invoke: function (listener) {\r
        var delay = listener.delay;\r
\r
        if (delay) {\r
            Ext.defer(listener.fn, delay, listener.scope);\r
        } else {\r
            if (Ext.elevateFunction) {\r
                Ext.elevateFunction(listener.fn, listener.scope);\r
            } else {\r
                listener.fn.call(listener.scope);\r
            }\r
        }\r
    },\r
\r
    /**\r
     * Invokes as many listeners as are appropriate given the current state. This should\r
     * only be called when DOM ready is achieved. The remaining business of `blocks` is\r
     * handled here.\r
     */\r
    invokeAll: function() {\r
        if (Ext.elevateFunction) {\r
            Ext.elevateFunction(this.doInvokeAll, this);\r
        } else {\r
            this.doInvokeAll();\r
        }\r
    },\r
\r
    doInvokeAll: function () {\r
        var me = this,\r
            listeners = me.listeners,\r
            listener;\r
\r
        if (!me.blocks) {\r
            // Since DOM is ready and we have no blocks, we mark the framework as ready.\r
            Ext.isReady = true;\r
        }\r
        me.firing = true;\r
\r
        // NOTE: We cannot cache this length because each time through the loop a callback\r
        // may have added new callbacks.\r
        while (listeners.length) {\r
            if (me.sortGeneration !== me.generation) {\r
                me.sortGeneration = me.generation;\r
\r
                // This will happen just once on the first pass... if nothing is being\r
                // added as we call the callbacks. This sorts the listeners such that the\r
                // highest priority listener is at the *end* of the array ... so we can\r
                // use pop (as opposed to shift) to extract it.\r
                listeners.sort(me.sortFn);\r
            }\r
\r
            listener = listeners.pop();\r
            if (me.blocks && !listener.dom) {\r
                // If we are blocked (i.e., only DOM ready) and this listener is not a\r
                // DOM-ready listener we have reached the end of the line. The remaining\r
                // listeners are Framework ready listeners.\r
                listeners.push(listener);\r
                break;\r
            }\r
\r
            me.invoke(listener);\r
        }\r
\r
        me.firing = false;\r
    },\r
\r
    /**\r
     * This method wraps the given listener pieces in a proper object for the `listeners`\r
     * array and `invoke` methods.\r
     * @param {Function} fn The method to call.\r
     * @param {Object} [scope] The scope (`this` reference) in which the `fn` executes.\r
     * Defaults to the browser window.\r
     * @param {Object} [options] An object with extra options.\r
     * @param {Number} [options.delay=0] A number of milliseconds to delay.\r
     * @param {Number} [options.priority=0] Relative priority of this callback. A larger\r
     * number will result in the callback being sorted before the others.  Priorities\r
     * 1000 or greater and -1000 or lesser are reserved for internal framework use only.\r
     * @param {Boolean} [options.dom=false] Pass `true` to only wait for DOM ready, `false`\r
     * means full Framework and DOM readiness.\r
     * @return {Object} The listener instance.\r
     * @private\r
     */\r
    makeListener: function (fn, scope, options) {\r
        var ret = {\r
            fn: fn,\r
            id: ++this.nextId, // so sortFn can respect FIFO\r
            scope: scope,\r
            dom: false,\r
            priority: 0\r
        };\r
        if (options) {\r
            Ext.apply(ret, options);\r
        }\r
        ret.phase = ret.dom ? 0 : 1; // to simplify the sortFn\r
        return ret;\r
    },\r
\r
    /**\r
     * Adds a listener to be notified when the document is ready (before onload and before\r
     * images are loaded).\r
     *\r
     * @param {Function} fn The method to call.\r
     * @param {Object} [scope] The scope (`this` reference) in which the `fn` executes.\r
     * Defaults to the browser window.\r
     * @param {Object} [options] An object with extra options.\r
     * @param {Number} [options.delay=0] A number of milliseconds to delay.\r
     * @param {Number} [options.priority=0] Relative priority of this callback. A larger\r
     * number will result in the callback being sorted before the others.  Priorities\r
     * 1000 or greater and -1000 or lesser are reserved for internal framework use only.\r
     * @param {Boolean} [options.dom=false] Pass `true` to only wait for DOM ready, `false`\r
     * means full Framework and DOM readiness.\r
     * @private\r
     */\r
    on: function (fn, scope, options) {\r
        var me = Ext.env.Ready,\r
            listener = me.makeListener(fn, scope, options);\r
\r
        if (me.state === 2 && !me.firing && (listener.dom || !me.blocks)) {\r
            // If we are DOM ready (state === 2) and not currently in invokeAll (!firing)\r
            // and this listener is ready to call (either a DOM ready listener or there\r
            // are no blocks), then we need to invoke the listener now.\r
            //\r
            // Otherwise we can fall to the else block and push the listener. The eventual\r
            // (or currently executing) call to handleReady or unblock will trigger its\r
            // delivery in proper priority order.\r
            me.invoke(listener);\r
        } else {\r
            me.listeners.push(listener);\r
            ++me.generation;\r
\r
            if (!me.bound) {\r
                // If we have never bound then bind the ready event now. If we have unbound\r
                // the event then me.bound == -1 and we don't want to rebind it as the DOM\r
                // is ready.\r
                me.bind();\r
            }\r
        }\r
    },\r
\r
    /**\r
     * This is a generic event handler method attached to all of the various events that\r
     * may indicate ready state. The first call to this method indicates ready state has\r
     * been achieved.\r
     * @param {Event} [ev] The event instance.\r
     * @private\r
     */\r
    onReadyEvent: function (ev) {\r
        var me = Ext.env.Ready;\r
\r
        if (Ext.elevateFunction) {\r
            Ext.elevateFunction(me.doReadyEvent, me, arguments);\r
        } else {\r
            me.doReadyEvent(ev);\r
        }\r
    },\r
\r
    doReadyEvent: function (ev) {\r
        var me = this;\r
\r
        //<debug>\r
        if (ev && ev.type) {\r
            me.events.push(ev);\r
        }\r
        //</debug>\r
\r
        if (me.bound > 0) {\r
            me.unbind();\r
            me.bound = -1; // NOTE: *not* 0 or false - we never want to rebind!\r
        }\r
\r
        if (!me.state) {\r
            me.fireReady();\r
        }\r
    },\r
\r
    /**\r
     * Sorts the `listeners` array by `phase` and `priority` such that the first listener\r
     * to fire can be determined using `pop` on the `listeners` array.\r
     * @private\r
     */\r
    sortFn: function (a, b) {\r
        return -((a.phase - b.phase) || (b.priority - a.priority) || (a.id - b.id));\r
    },\r
\r
    unblock: function () {\r
        var me = this;\r
\r
        if (me.blocks) {\r
            if (! --me.blocks) {\r
                if (me.state === 2 && !me.firing) {\r
                    // We have already finished handleReady (the DOM ready handler) so\r
                    // this trigger just needs to dispatch all the remaining listeners.\r
                    me.invokeAll();\r
                }\r
                // if we are currently firing then invokeAll will pick up the Framework\r
                // ready listeners automatically.\r
                //\r
                // If me.state < 2 then we are waiting for DOM ready so it will eventually\r
                // call handleReady and invokeAll when everything is ready.\r
            }\r
        }\r
    },\r
\r
    /**\r
     * This method is called to remove all event listeners that may have been set up to\r
     * detect ready state.\r
     * @private\r
     */\r
    unbind: function () {\r
        var me = this,\r
            doc = document;\r
\r
        if (me.bound > 1) {\r
            doc.removeEventListener('deviceready', me.onReadyEvent, false);\r
        }\r
\r
        doc.removeEventListener('DOMContentLoaded', me.onReadyEvent, false);\r
        window.removeEventListener('load', me.onReadyEvent, false);\r
    }\r
};\r
\r
(function () {\r
    var Ready = Ext.env.Ready;\r
\r
    //<feature legacyBrowser>\r
\r
    /*\r
     *  EXTJS-13522\r
     *  Although IE 9 has the DOMContentLoaded event available, usage of that causes\r
     *  timing issues when attempting to access document.namespaces (VmlCanvas.js).\r
     *  Consequently, even in IE 9 we need to use the legacy bind override for ready\r
     *  detection.  This defers ready firing enough to allow access to the\r
     *  document.namespaces property.\r
     *\r
     *  NOTE: this issue is very timing sensitive, and typically only displays itself\r
     *  when there is a large amount of latency between the browser and the server, and\r
     *  when testing against a built page (ext-all.js) and not a dev mode page.\r
     */\r
    if (Ext.isIE9m) {\r
        /* Customized implementation for Legacy IE. The default implementation is \r
         * configured for use with all other 'standards compliant' agents.\r
         * References: http://javascript.nwbox.com/IEContentLoaded/\r
         * licensed courtesy of http://developer.yahoo.com/yui/license.html\r
         */\r
        Ext.apply(Ready, {\r
            /**\r
             * Timer for doScroll polling\r
             * @private\r
             */\r
            scrollTimer: null,\r
\r
            /**\r
             * @private\r
             */\r
            readyStatesRe  : /complete/i,\r
\r
            /**\r
             * This strategy has minimal benefits for Sencha solutions that build\r
             * themselves (ie. minimal initial page markup). However, progressively-enhanced\r
             * pages (with image content and/or embedded frames) will benefit the most\r
             * from it. Browser timer resolution is too poor to ensure a doScroll check\r
             * more than once on a page loaded with minimal assets (the readystatechange\r
             * event 'complete' usually beats the doScroll timer on a 'lightly-loaded'\r
             * initial document).\r
             * @private\r
             */\r
            pollScroll : function() {\r
                var scrollable = true;\r
\r
                try {\r
                    document.documentElement.doScroll('left');\r
                } catch(e) {\r
                    scrollable = false;\r
                }\r
\r
                // on IE8, when running within an iFrame, document.body is not immediately\r
                // available\r
                if (scrollable && document.body) {\r
                    Ready.onReadyEvent({\r
                        type: 'doScroll'\r
                    });\r
                } else {\r
                     // Minimize thrashing --\r
                     // adjusted for setTimeout's close-to-minimums (not too low),\r
                     // as this method SHOULD always be called once initially\r
                    Ready.scrollTimer = Ext.defer(Ready.pollScroll, 20);\r
                }\r
\r
                return scrollable;\r
            },\r
\r
            bind: function () {\r
                if (Ready.bound) {\r
                    return;\r
                }\r
\r
                var doc = document,\r
                    topContext;\r
\r
                // See if we are in an IFRAME? (doScroll ineffective here)\r
                try {\r
                    topContext = window.frameElement === undefined;\r
                } catch(e) {\r
                    // If we throw an exception, it means we're probably getting access\r
                    // denied, which means we're in an iframe cross domain.\r
                }\r
\r
                if (!topContext || !doc.documentElement.doScroll) {\r
                    Ready.pollScroll = Ext.emptyFn;   //then noop this test altogether\r
                }\r
                else if (Ready.pollScroll()) { // starts scroll polling if necessary\r
                    return;\r
                }\r
\r
                if (doc.readyState === 'complete')  {\r
                    // Loaded AFTER initial document write/load...\r
                    Ready.onReadyEvent({\r
                        type: 'already ' + (doc.readyState || 'body')\r
                    });\r
                } else {\r
                    doc.attachEvent('onreadystatechange', Ready.onReadyStateChange);\r
                    window.attachEvent('onload', Ready.onReadyEvent);\r
                    Ready.bound = 1;\r
                }\r
            },\r
\r
            unbind : function () {\r
                document.detachEvent('onreadystatechange', Ready.onReadyStateChange);\r
                window.detachEvent('onload', Ready.onReadyEvent);\r
\r
                if (Ext.isNumber(Ready.scrollTimer)) {\r
                    clearTimeout(Ready.scrollTimer);\r
                    Ready.scrollTimer = null;\r
                }\r
            },\r
\r
            /**\r
             * This event handler is called when the readyState changes.\r
             * @private\r
             */\r
            onReadyStateChange: function() {\r
                var state = document.readyState;\r
\r
                if (Ready.readyStatesRe.test(state)) {\r
                    Ready.onReadyEvent({\r
                        type: state\r
                    });\r
                }\r
            }\r
        });\r
    }\r
    //</feature>\r
\r
    /**\r
     * @property {Boolean} isDomReady\r
     * `true` when the document body is ready for use.\r
     * @member Ext\r
     * @readonly\r
     */\r
\r
    /**\r
     * @property {Boolean} isReady\r
     * `true` when `isDomReady` is true and the Framework is ready for use.\r
     * @member Ext\r
     * @readonly\r
     */\r
\r
    /**\r
     * @method onDocumentReady\r
     * @member Ext\r
     * Adds a listener to be notified when the document is ready (before onload and before\r
     * images are loaded).\r
     *\r
     * @param {Function} fn The method to call.\r
     * @param {Object} [scope] The scope (`this` reference) in which the handler function\r
     * executes. Defaults to the browser window.\r
     * @param {Object} [options] An object with extra options.\r
     * @param {Number} [options.delay=0] A number of milliseconds to delay.\r
     * @param {Number} [options.priority=0] Relative priority of this callback. A larger\r
     * number will result in the callback being sorted before the others.  Priorities\r
     * 1000 or greater and -1000 or lesser are reserved for internal framework use only.\r
     * @private\r
     */\r
    Ext.onDocumentReady = function (fn, scope, options) {\r
        var opt = {\r
            dom: true\r
        };\r
\r
        if (options) {\r
            Ext.apply(opt, options);\r
        }\r
\r
        Ready.on(fn, scope, opt);\r
    };\r
\r
    /**\r
     * @method onReady\r
     * @member Ext\r
     * Adds a listener to be notified when the document is ready (before onload and before\r
     * images are loaded).\r
     *\r
     * @param {Function} fn The method to call.\r
     * @param {Object} [scope] The scope (`this` reference) in which the handler function\r
     * executes. Defaults to the browser window.\r
     * @param {Object} [options] An object with extra options.\r
     * @param {Number} [options.delay=0] A number of milliseconds to delay.\r
     * @param {Number} [options.priority=0] Relative priority of this callback. A larger\r
     * number will result in the callback being sorted before the others.  Priorities\r
     * 1000 or greater and -1000 or lesser are reserved for internal framework use only.\r
     * @param {Boolean} [options.dom=false] Pass `true` to only wait for DOM ready, `false`\r
     * means full Framework and DOM readiness.\r
     * numbers are reserved.\r
     */\r
    Ext.onReady = function (fn, scope, options) {\r
        Ready.on(fn, scope, options);\r
    };\r
\r
    // A shortcut method for onReady with a high priority\r
    Ext.onInternalReady = function(fn, scope, options) {\r
        Ready.on(fn, scope, Ext.apply({\r
            priority: 1000\r
        }, options));\r
    }\r
\r
    Ready.bind();\r
}());\r