add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / class / Config.js

/**\r
 * @class Ext.Config\r
 * This class manages a config property. Instances of this type are created and cached as\r
 * classes declare their config properties. One instance of this class is created per\r
 * config property name.\r
 *\r
 *      Ext.define('MyClass', {\r
 *          config: {\r
 *              foo: 42\r
 *          }\r
 *      });\r
 *\r
 * This uses the cached `Ext.Config` instance for the "foo" property.\r
 *\r
 * When config properties apply options to config properties a prototype chained object is\r
 * created from the cached instance. For example:\r
 *\r
 *      Ext.define('MyClass', {\r
 *          config: {\r
 *              foo: {\r
 *                  $value: 42,\r
 *                  lazy: true\r
 *              }\r
 *          }\r
 *      });\r
 *\r
 * This creates a prototype chain to the cached "foo" instance of `Ext.Config` and applies\r
 * the `lazy` option to that new instance. This chained instance is then kept by the\r
 * `Ext.Configurator` for that class.\r
 * @private\r
 */\r
Ext.Config = function (name) {\r
// @define Ext.class.Config\r
// @define Ext.Config\r
\r
    var me = this,\r
        capitalizedName = name.charAt(0).toUpperCase() + name.substr(1);\r
\r
    /**\r
     * @property {String} name\r
     * The name of this config property.\r
     * @readonly\r
     * @private\r
     * @since 5.0.0\r
     */\r
    me.name = name;\r
\r
    /**\r
     * @property {Object} names\r
     * This object holds the cached names used to lookup properties or methods for this\r
     * config property. The properties of this object are explained in the context of an\r
     * example property named "foo".\r
     *\r
     * @property {String} names.internal The default backing property ("_foo").\r
     *\r
     * @property {String} names.initializing The property that is `true` when the config\r
     * is being initialized ("isFooInitializing").\r
     *\r
     * @property {String} names.apply The name of the applier method ("applyFoo").\r
     *\r
     * @property {String} names.update  The name of the updater method ("updateFoo").\r
     *\r
     * @property {String} names.get The name of the getter method ("getFoo").\r
     *\r
     * @property {String} names.set The name of the setter method ("setFoo").\r
     *\r
     * @property {String} names.initGet The name of the initializing getter ("initGetFoo").\r
     *\r
     * @property {String} names.changeEvent The name of the change event ("foochange").\r
     *\r
     * @readonly\r
     * @private\r
     * @since 5.0.0\r
     */\r
    me.names = {\r
        internal: '_' + name,\r
        initializing: 'is' + capitalizedName + 'Initializing',\r
        apply: 'apply' + capitalizedName,\r
        update: 'update' + capitalizedName,\r
        get: 'get' + capitalizedName,\r
        set: 'set' + capitalizedName,\r
        initGet: 'initGet' + capitalizedName,\r
        changeEvent: name.toLowerCase() + 'change'\r
    };\r
\r
    // This allows folks to prototype chain on top of these objects and yet still cache\r
    // generated methods at the bottom of the chain.\r
    me.root = me;\r
};\r
\r
Ext.Config.map = {};\r
\r
Ext.Config.get = function (name) {\r
    var map = Ext.Config.map,\r
        ret = map[name] || (map[name] = new Ext.Config(name));\r
\r
    return ret;\r
};\r
\r
Ext.Config.prototype = {\r
    self: Ext.Config,\r
\r
    isConfig: true,\r
\r
    /**\r
     * @cfg {Boolean} [cached=false]\r
     * When set as `true` the config property will be stored on the class prototype once\r
     * the first instance has had a chance to process the default value.\r
     * @private\r
     * @since 5.0.0\r
     */\r
\r
    /**\r
     * @cfg {Boolean} [lazy=false]\r
     * When set as `true` the config property will not be immediately initialized during\r
     * the `initConfig` call.\r
     * @private\r
     * @since 5.0.0\r
     */\r
\r
    /**\r
     * @cfg {Boolean} [evented=false]\r
     * When set as `true` the config property will be treated as a {@link Ext.Evented Evented Config}.\r
     * @private\r
     * @since 5.5.0\r
     */\r
\r
    /**\r
     * @cfg {Function} [merge]\r
     * This function if supplied will be called as classes or instances provide values\r
     * that need to be combined with inherited values. The function should return the\r
     * value that will be the config value. Further calls may receive such returned\r
     * values as `oldValue`.\r
     *\r
     * @cfg {Mixed} merge.newValue The new value to merge with the old.\r
     *\r
     * @cfg {Mixed} merge.oldValue The current value prior to `newValue` being merged.\r
     *\r
     * @cfg {Mixed} merge.target The class or instance to which the merged config value\r
     * will be applied.\r
     *\r
     * @cfg {Ext.Class} merge.mixinClass The mixin providing the `newValue` or `null` if\r
     * the `newValue` is not being provided by a mixin.\r
     */\r
\r
    getGetter: function () {\r
        return this.getter || (this.root.getter = this.makeGetter());\r
    },\r
    \r
    getInitGetter: function () {\r
        return this.initGetter || (this.root.initGetter = this.makeInitGetter());\r
    },\r
\r
    getSetter: function () {\r
        return this.setter || (this.root.setter = this.makeSetter());\r
    },\r
\r
    getEventedSetter: function () {\r
        return this.eventedSetter || (this.root.eventedSetter = this.makeEventedSetter());\r
    },\r
\r
    /**\r
     * Returns the name of the property that stores this config on the given instance or\r
     * class prototype.\r
     * @param {Object} target\r
     * @return {String}\r
     */\r
    getInternalName: function (target) {\r
        return target.$configPrefixed ? this.names.internal : this.name;\r
    },\r
\r
    mergeNew: function (newValue, oldValue, target, mixinClass) {\r
        var ret, key;\r
\r
        if (!oldValue) {\r
            ret = newValue;\r
        } else if (!newValue) {\r
            ret = oldValue;\r
        } else {\r
            ret = Ext.Object.chain(oldValue);\r
\r
            for (key in newValue) {\r
                if (!mixinClass || !(key in ret)) {\r
                    ret[key] = newValue[key];\r
                }\r
            }\r
        }\r
        return ret;\r
    },\r
\r
    /**\r
     * Merges the `newValue` and the `oldValue` assuming that these are basically objects\r
     * the represent sets. For example something like:\r
     *\r
     *      {\r
     *          foo: true,\r
     *          bar: true\r
     *      }\r
     *\r
     * The merge process converts arrays like the following into the above:\r
     *\r
     *      [ 'foo', 'bar' ]\r
     *\r
     * @param {String/String[]/Object} newValue\r
     * @param {Object} oldValue\r
     * @param {Boolean} [preserveExisting=false]\r
     * @return {Object}\r
     * @private\r
     * @since 5.0.0\r
     */\r
    mergeSets: function (newValue, oldValue, preserveExisting) {\r
        var ret = oldValue ? Ext.Object.chain(oldValue) : {},\r
            i, val;\r
\r
        if (newValue instanceof Array) {\r
            for (i = newValue.length; i--; ) {\r
                val = newValue[i];\r
                if (!preserveExisting || !(val in ret)) {\r
                    ret[val] = true;\r
                }\r
            }\r
        } else if (newValue) {\r
            if (newValue.constructor === Object) {\r
                for (i in newValue) {\r
                    val = newValue[i];\r
                    if (!preserveExisting || !(i in ret)) {\r
                        ret[i] = val;\r
                    }\r
                }\r
            } else if (!preserveExisting || !(newValue in ret)) {\r
                ret[newValue] = true;\r
            }\r
        }\r
\r
        return ret;\r
    },\r
\r
    //--------------------------------------------------\r
    // Factories\r
\r
    makeGetter: function () {\r
        var name = this.name,\r
            prefixedName = this.names.internal;\r
\r
        return function () {\r
            var internalName = this.$configPrefixed ? prefixedName : name;\r
            return this[internalName];\r
        };\r
    },\r
\r
    makeInitGetter: function () {\r
        var name = this.name,\r
            names = this.names,\r
            setName = names.set,\r
            getName = names.get,\r
            initializingName = names.initializing;\r
\r
        return function () {\r
            var me = this;\r
\r
            me[initializingName] = true;\r
            // Remove the initGetter from the instance now that the value has been set.\r
            delete me[getName];\r
\r
            me[setName](me.config[name]);\r
            delete me[initializingName];\r
\r
            return me[getName].apply(me, arguments);\r
        };\r
    },\r
\r
    makeSetter: function () {\r
        var name = this.name,\r
            names = this.names,\r
            prefixedName = names.internal,\r
            getName = names.get,\r
            applyName = names.apply,\r
            updateName = names.update,\r
            setter;\r
\r
        // http://jsperf.com/method-call-apply-or-direct\r
        // http://jsperf.com/method-detect-invoke\r
        setter = function (value) {\r
            var me = this,\r
                internalName = me.$configPrefixed ? prefixedName : name,\r
                oldValue = me[internalName];\r
\r
            // Remove the initGetter from the instance now that the value has been set.\r
            delete me[getName];\r
\r
            if (!me[applyName] || (value = me[applyName](value, oldValue)) !== undefined) {\r
                // The old value might have been changed at this point\r
                // (after the apply call chain) so it should be read again\r
                if (value !== (oldValue = me[internalName])) {\r
                    me[internalName] = value;\r
\r
                    if (me[updateName]) {\r
                        me[updateName](value, oldValue);\r
                    }\r
                }\r
            }\r
\r
            return me;\r
        };\r
\r
        setter.$isDefault = true;\r
\r
        return setter;\r
    },\r
\r
    makeEventedSetter: function () {\r
        var name = this.name,\r
            names = this.names,\r
            prefixedName = names.internal,\r
            getName = names.get,\r
            applyName = names.apply,\r
            updateName = names.update,\r
            changeEventName = names.changeEvent,\r
            updateFn = function (me, value, oldValue, internalName) {\r
                me[internalName] = value;\r
                if (me[updateName]) {\r
                    me[updateName](value, oldValue);\r
                }\r
            },\r
            setter;\r
\r
        // http://jsperf.com/method-call-apply-or-direct\r
        // http://jsperf.com/method-detect-invoke\r
        setter = function (value) {\r
            var me = this,\r
                internalName = me.$configPrefixed ? prefixedName : name,\r
                oldValue = me[internalName];\r
\r
            // Remove the initGetter from the instance now that the value has been set.\r
            delete me[getName];\r
\r
            if (!me[applyName] || (value = me[applyName](value, oldValue)) !== undefined) {\r
                // The old value might have been changed at this point\r
                // (after the apply call chain) so it should be read again\r
                if (value !== (oldValue = me[internalName])) {\r
\r
                    if (me.isConfiguring) {\r
                        me[internalName] = value;\r
\r
                        if (me[updateName]) {\r
                            me[updateName](value, oldValue);\r
                        }\r
                    } else {\r
                        me.fireEventedAction(changeEventName, [me, value, oldValue],\r
                                updateFn, me, [me, value, oldValue, internalName]);\r
                    }\r
                }\r
            }\r
\r
            return me;\r
        };\r
\r
        setter.$isDefault = true;\r
\r
        return setter;\r
    }\r
};\r