add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / state / Stateful.js

/**\r
 * @class Ext.state.Stateful\r
 * A mixin for being able to save the state of an object to an underlying\r
 * {@link Ext.state.Provider}.\r
 */\r
Ext.define('Ext.state.Stateful', {\r
    mixinId: 'state',\r
\r
    requires: [\r
        'Ext.state.Manager',\r
        'Ext.util.TaskRunner'\r
    ],\r
\r
    /**\r
     * @cfg {Boolean} stateful\r
     * A flag which causes the object to attempt to restore the state of\r
     * internal properties from a saved state on startup. The object must have\r
     * a {@link #stateId} for state to be managed.\r
     *\r
     * Auto-generated ids are not guaranteed to be stable across page loads and\r
     * cannot be relied upon to save and restore the same state for a object.\r
     *\r
     * For state saving to work, the state manager's provider must have been\r
     * set to an implementation of {@link Ext.state.Provider} which overrides the\r
     * {@link Ext.state.Provider#set set} and {@link Ext.state.Provider#get get}\r
     * methods to save and recall name/value pairs. A built-in implementation,\r
     * {@link Ext.state.CookieProvider} is available.\r
     *\r
     * To set the state provider for the current page:\r
     *\r
     *    Ext.state.Manager.setProvider(new Ext.state.CookieProvider({\r
     *        expires: new Date(new Date().getTime()+(1000*60*60*24*7)), //7 days from now\r
     *    }));\r
     *\r
     * A stateful object attempts to save state when one of the events\r
     * listed in the {@link #stateEvents} configuration fires.\r
     *\r
     * To save state, a stateful object first serializes its state by\r
     * calling *{@link #getState}*.\r
     *\r
     * The Component base class implements {@link #getState} to save its width and height within the state\r
     * only if they were initially configured, and have changed from the configured value.\r
     *\r
     * The Panel class saves its collapsed state in addition to that.\r
     *\r
     * The Grid class saves its column state and store state (sorters and filters and grouper) in addition to its superclass state.\r
     *\r
     * If there is more application state to be save, the developer must provide an implementation which\r
     * first calls the superclass method to inherit the above behaviour, and then injects new properties\r
     * into the returned object.\r
     *\r
     * The value yielded by getState is passed to {@link Ext.state.Manager#set}\r
     * which uses the configured {@link Ext.state.Provider} to save the object\r
     * keyed by the {@link #stateId}.\r
     *\r
     * During construction, a stateful object attempts to *restore* its state by calling\r
     * {@link Ext.state.Manager#get} passing the {@link #stateId}\r
     *\r
     * The resulting object is passed to {@link #applyState}*. The default implementation of\r
     * {@link #applyState} simply copies properties into the object, but a developer may\r
     * override this to support restoration of more complex application state.\r
     *\r
     * You can perform extra processing on state save and restore by attaching\r
     * handlers to the {@link #beforestaterestore}, {@link #staterestore},\r
     * {@link #beforestatesave} and {@link #statesave} events.\r
     */\r
    stateful: false,\r
\r
    /**\r
     * @cfg {String} stateId\r
     * The unique id for this object to use for state management purposes.\r
     *\r
     * See {@link #stateful} for an explanation of saving and restoring state.\r
     */\r
\r
    /**\r
     * @cfg {String[]} stateEvents\r
     * An array of events that, when fired, should trigger this object to\r
     * save its state. Defaults to none. `stateEvents` may be any type\r
     * of event supported by this object, including browser or custom events\r
     * (e.g., `['click', 'customerchange']`).\r
     *\r
     * See `{@link #stateful}` for an explanation of saving and\r
     * restoring object state.\r
     */\r
\r
    /**\r
     * @cfg {Number} saveDelay\r
     * A buffer to be applied if many state events are fired within a short period.\r
     */\r
    saveDelay: 100,\r
\r
    /**\r
     * @event beforestaterestore\r
     * Fires before the state of the object is restored. Return false from an event handler to stop the restore.\r
     * @param {Ext.state.Stateful} this\r
     * @param {Object} state The hash of state values returned from the StateProvider. If this\r
     * event is not vetoed, then the state object is passed to *`applyState`*. By default,\r
     * that simply copies property values into this object. The method maybe overriden to\r
     * provide custom state restoration.\r
     */\r
\r
    /**\r
     * @event staterestore\r
     * Fires after the state of the object is restored.\r
     * @param {Ext.state.Stateful} this\r
     * @param {Object} state The hash of state values returned from the StateProvider. This is passed\r
     * to *`applyState`*. By default, that simply copies property values into this\r
     * object. The method maybe overridden to provide custom state restoration.\r
     */\r
\r
    /**\r
     * @event beforestatesave\r
     * Fires before the state of the object is saved to the configured state provider. Return false to stop the save.\r
     * @param {Ext.state.Stateful} this\r
     * @param {Object} state The hash of state values. This is determined by calling\r
     * *`getState()`* on the object. This method must be provided by the\r
     * developer to return whatever representation of state is required, by default, Ext.state.Stateful\r
     * has a null implementation.\r
     */\r
\r
    /**\r
     * @event statesave\r
     * Fires after the state of the object is saved to the configured state provider.\r
     * @param {Ext.state.Stateful} this\r
     * @param {Object} state The hash of state values. This is determined by calling\r
     * *`getState()`* on the object. This method must be provided by the\r
     * developer to return whatever representation of state is required, by default, Ext.state.Stateful\r
     * has a null implementation.\r
     */\r
\r
    constructor: function() {\r
        var me = this;\r
\r
        if (!me.stateEvents) {\r
            me.stateEvents = [];\r
        }\r
\r
        if (me.stateful !== false) {\r
            me.addStateEvents(me.stateEvents);\r
            me.initState();\r
        }\r
    },\r
\r
    /**\r
     * Add events that will trigger the state to be saved. If the first argument is an\r
     * array, each element of that array is the name of a state event. Otherwise, each\r
     * argument passed to this method is the name of a state event.\r
     *\r
     * @param {String/String[]} events The event name or an array of event names.\r
     */\r
    addStateEvents: function (events) {\r
        var me = this,\r
            i, event, stateEventsByName,\r
            eventArray;\r
\r
        if (me.stateful && me.getStateId()) {\r
            eventArray =  (typeof events === 'string') ? arguments : events;\r
\r
            stateEventsByName = me.stateEventsByName || (me.stateEventsByName = {});\r
\r
            for (i = eventArray.length; i--; ) {\r
                event = eventArray[i];\r
\r
                if (event && !stateEventsByName[event]) {\r
                    stateEventsByName[event] = 1;\r
                    me.on(event, me.onStateChange, me);\r
                }\r
            }\r
        }\r
    },\r
\r
    /**\r
     * This method is called when any of the {@link #stateEvents} are fired.\r
     * @private\r
     */\r
    onStateChange: function(){\r
        var me = this,\r
            delay = me.saveDelay,\r
            statics, runner;\r
\r
        if (!me.stateful) {\r
            return;\r
        }\r
\r
        if (delay) {\r
            if (!me.stateTask) {\r
                statics = Ext.state.Stateful;\r
                runner = statics.runner || (statics.runner = new Ext.util.TaskRunner());\r
\r
                me.stateTask = runner.newTask({\r
                    run: me.saveState,\r
                    scope: me,\r
                    interval: delay,\r
                    repeat: 1,\r
                    fireIdleEvent: false\r
                });\r
            }\r
\r
            me.stateTask.start();\r
        } else {\r
            me.saveState();\r
        }\r
    },\r
\r
    /**\r
     * Saves the state of the object to the persistence store.\r
     */\r
    saveState: function() {\r
        var me = this,\r
            id = me.stateful && me.getStateId(),\r
            hasListeners = me.hasListeners,\r
            plugins,\r
            plugin,\r
            i, len,\r
            state,\r
            pluginState;\r
\r
        if (id) {\r
            state = me.getState() || {};    //pass along for custom interactions\r
\r
            /*\r
             * Gather state from those plugins that implement a getState method\r
             */\r
            plugins = me.getPlugins() || [];\r
            for (i = 0, len = plugins.length; i < len; i++) {\r
                plugin = plugins[i];\r
                if (plugin && plugin.getState) {\r
                    pluginState = plugin.getState(state);\r
                    if (pluginState && !state[plugin.ptype]) {  //first duplicate plugin wins\r
                        state[plugin.ptype] = pluginState;\r
                    }\r
                }\r
            }\r
\r
            if (!hasListeners.beforestatesave || me.fireEvent('beforestatesave', me, state) !== false) {\r
                Ext.state.Manager.set(id, state);\r
                if (hasListeners.statesave) {\r
                    me.fireEvent('statesave', me, state);\r
                }\r
            }\r
        }\r
    },\r
\r
    /**\r
     * Gets the current state of the object. By default this function returns null,\r
     * it should be overridden in subclasses to implement methods for getting the state.\r
     * @return {Object} The current state\r
     */\r
    getState: function(){\r
        return null;\r
    },\r
\r
    /**\r
     * Applies the state to the object. This should be overridden in subclasses to do\r
     * more complex state operations. By default it applies the state properties onto\r
     * the current object.\r
     * @param {Object} state The state\r
     */\r
    applyState: function(state) {\r
        if (state) {\r
            Ext.apply(this, state);\r
        }\r
    },\r
\r
    /**\r
     * Gets the state id for this object.\r
     * @return {String} The 'stateId' or the implicit 'id' specified by component configuration.\r
     * @private\r
     */\r
    getStateId: function() {\r
        var me = this;\r
        return me.stateId || (me.autoGenId ? null : me.id);\r
    },\r
\r
    /**\r
     * Initializes the state of the object upon construction.\r
     * @private\r
     */\r
    initState: function(){\r
        var me = this,\r
            id = me.stateful && me.getStateId(),\r
            hasListeners = me.hasListeners,\r
            state,\r
            combinedState,\r
            i, len,\r
            plugins,\r
            plugin,\r
            pluginType;\r
\r
        if (id) {\r
            combinedState = Ext.state.Manager.get(id);\r
            if (combinedState) {\r
                state = Ext.apply({}, combinedState);\r
                if (!hasListeners.beforestaterestore || me.fireEvent('beforestaterestore', me, combinedState) !== false) {\r
\r
                    //Notify all plugins FIRST (if interested) in new state\r
                    plugins = me.getPlugins() || [];\r
                    for (i = 0, len = plugins.length; i < len; i++) {\r
                        plugin = plugins[i];\r
                        if (plugin) {\r
                            pluginType = plugin.ptype;\r
                            if (plugin.applyState) {\r
                                plugin.applyState(state[pluginType], combinedState);\r
                            }\r
                            delete state[pluginType];  //clean to prevent unwanted props on the component in final phase\r
                        }\r
                    }\r
\r
                    me.applyState(state);\r
                    if (hasListeners.staterestore) {\r
                        me.fireEvent('staterestore', me, combinedState);\r
                    }\r
                }\r
            }\r
        }\r
    },\r
\r
    /**\r
     * Conditionally saves a single property from this object to the given state object.\r
     * The idea is to only save state which has changed from the initial state so that\r
     * current software settings do not override future software settings. Only those\r
     * values that are user-changed state should be saved.\r
     *\r
     * @param {String} propName The name of the property to save.\r
     * @param {Object} state The state object in to which to save the property.\r
     * @param {String} stateName (optional) The name to use for the property in state.\r
     * @return {Boolean} True if the property was saved, false if not.\r
     */\r
    savePropToState: function (propName, state, stateName) {\r
        var me = this,\r
            value = me[propName],\r
            config = me.initialConfig;\r
\r
        if (me.hasOwnProperty(propName)) {\r
            if (!config || config[propName] !== value) {\r
                if (state) {\r
                    state[stateName || propName] = value;\r
                }\r
                return true;\r
            }\r
        }\r
        return false;\r
    },\r
\r
    /**\r
     * Gathers additional named properties of the instance and adds their current values\r
     * to the passed state object.\r
     * @param {String/String[]} propNames The name (or array of names) of the property to save.\r
     * @param {Object} state The state object in to which to save the property values.\r
     * @return {Object} state\r
     */\r
    savePropsToState: function (propNames, state) {\r
        var me = this,\r
            i, n;\r
\r
        if (typeof propNames === 'string') {\r
            me.savePropToState(propNames, state);\r
        } else {\r
            for (i = 0, n = propNames.length; i < n; ++i) {\r
                me.savePropToState(propNames[i], state);\r
            }\r
        }\r
\r
        return state;\r
    },\r
\r
    /**\r
     * Destroys this stateful object.\r
     */\r
    destroy: function(){\r
        var me = this,\r
            task = me.stateTask;\r
\r
        if (task) {\r
            task.destroy();\r
            me.stateTask = null;\r
        }\r
\r
        me.clearListeners();\r
    }\r
});\r