add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / mixin / Responsive.js

/**\r
 * This mixin provides its user with a `responsiveConfig` config that allows the class\r
 * to conditionally control config properties.\r
 *\r
 * For example:\r
 *\r
 *      Ext.define('ResponsiveClass', {\r
 *          mixin: [\r
 *              'Ext.mixin.Responsive'\r
 *          ],\r
 *\r
 *          responsiveConfig: {\r
 *              portrait: {\r
 *              },\r
 *\r
 *              landscape: {\r
 *              }\r
 *          }\r
 *      });\r
 *\r
 * For a config to participate as a responsiveConfig it must have a "setter" method. In\r
 * the below example, a "setRegion" method must exist.\r
 *\r
 *      Ext.create({\r
 *          xtype: 'viewport',\r
 *          layout: 'border',\r
 *\r
 *          items: [{\r
 *              title: 'Some Title',\r
 *              plugins: 'responsive',\r
 *\r
 *              responsiveConfig: {\r
 *                  'width < 800': {\r
 *                      region: 'north'\r
 *                  },\r
 *                  'width >= 800': {\r
 *                      region: 'west'\r
 *                  }\r
 *              }\r
 *          }]\r
 *      });\r
 *\r
 * To use responsiveConfig the class must be defined using the Ext.mixin.Responsive mixin.\r
 *\r
 *      Ext.define('App.view.Foo', {\r
 *          extend: 'Ext.panel.Panel',\r
 *          xtype: 'foo',\r
 *          mixins: [\r
 *               'Ext.mixin.Responsive'\r
 *          ],\r
 *          ...\r
 *      });\r
 *\r
 * Otherwise, you will need to use the responsive plugin if the class is not one you authored.\r
 *\r
 *      Ext.create('Ext.panel.Panel', {\r
 *          renderTo: document.body,\r
 *          plugins: 'responsive',\r
 *          ...\r
 *      });\r
 * \r
 *  _Note:_ There is the exception of `Ext.container.Viewport` or other classes using `Ext.plugin.Viewport`.\r
 *  In those cases, the viewport plugin inherits from `Ext.plugin.Responsive`.\r
 *\r
 * For details see `{@link #responsiveConfig}`.\r
 * @since 5.0.0\r
 */\r
Ext.define('Ext.mixin.Responsive', function (Responsive) { return {\r
    extend: 'Ext.Mixin',\r
    requires: [\r
        'Ext.GlobalEvents'\r
    ],\r
\r
    mixinConfig: {\r
        id: 'responsive',\r
\r
        after: {\r
            destroy: 'destroy'\r
        }\r
    },\r
\r
    config: {\r
        /**\r
         * @cfg {Object} responsiveConfig\r
         * This object consists of keys that represent the conditions on which configs\r
         * will be applied. For example:\r
         *\r
         *      responsiveConfig: {\r
         *          landscape: {\r
         *              region: 'west'\r
         *          },\r
         *          portrait: {\r
         *              region: 'north'\r
         *          }\r
         *      }\r
         *\r
         * In this case the keys ("landscape" and "portrait") are the criteria (or "rules")\r
         * and the object to their right contains the configs that will apply when that\r
         * rule is true.\r
         *\r
         * These rules can be any valid JavaScript expression but the following values\r
         * are considered in scope:\r
         *\r
         *  * `landscape` - True if the device orientation is landscape (always `true` on\r
         *   desktop devices).\r
         *  * `portrait` - True if the device orientation is portrait (always `false` on\r
         *   desktop devices).\r
         *  * `tall` - True if `width` < `height` regardless of device type.\r
         *  * `wide` - True if `width` > `height` regardless of device type.\r
         *  * `width` - The width of the viewport in pixels.\r
         *  * `height` - The height of the viewport in pixels.\r
         *  * `platform` - An object containing various booleans describing the platform\r
         *  (see `{@link Ext#platformTags Ext.platformTags}`). The properties of this\r
         *  object are also available implicitly (without "platform." prefix) but this\r
         *  sub-object may be useful to resolve ambiguity (for example, if one of the\r
         *  `{@link #responsiveFormulas}` overlaps and hides any of these properties).\r
         *  Previous to Ext JS 5.1, the `platformTags` were only available using this\r
         *  prefix.\r
         *\r
         * A more complex example:\r
         *\r
         *      responsiveConfig: {\r
         *          'desktop || width > 800': {\r
         *              region: 'west'\r
         *          },\r
         *\r
         *          '!(desktop || width > 800)': {\r
         *              region: 'north'\r
         *          }\r
         *      }\r
         *\r
         * **NOTE**: If multiple rules set a single config (like above), it is important\r
         * that the rules be mutually exclusive. That is, only one rule should set each\r
         * config. If multiple rules are actively setting a single config, the order of\r
         * these (and therefore the config's value) is unspecified.\r
         *\r
         * For a config to participate as a `responsiveConfig` it must have a "setter"\r
         * method. In the above example, a "setRegion" method must exist.\r
         *\r
         * @since 5.0.0\r
         */\r
        responsiveConfig: {\r
            $value: undefined,\r
\r
            merge:  function (newValue, oldValue, target, mixinClass) {\r
                if (!newValue) {\r
                    return oldValue;\r
                }\r
\r
                var ret = oldValue ? Ext.Object.chain(oldValue) : {},\r
                    rule;\r
\r
                for (rule in newValue) {\r
                    if (!mixinClass || !(rule in ret)) {\r
                        ret[rule] = {\r
                            fn: null, // created on first evaluation of this rule\r
                            config: newValue[rule]\r
                        };\r
                    }\r
                }\r
\r
                return ret;\r
            }\r
        },\r
\r
        /**\r
         * @cfg {Object} responsiveFormulas\r
         * It is common when using `responsiveConfig` to have recurring expressions that\r
         * make for complex configurations. Using `responsiveFormulas` allows you to cut\r
         * down on this repetition by adding new properties to the "scope" for the rules\r
         * in a `responsiveConfig`.\r
         *\r
         * For example:\r
         *\r
         *      Ext.define('MyApp.view.main.Main', {\r
         *          extend: 'Ext.container.Container',\r
         *\r
         *          mixins: [\r
         *              'Ext.mixin.Responsive'\r
         *          ],\r
         *\r
         *          responsiveFormulas: {\r
         *              small: 'width < 600',\r
         *\r
         *              medium: 'width >= 600 && width < 800',\r
         *\r
         *              large: 'width >= 800',\r
         *\r
         *              tuesday: function (context) {\r
         *                  return (new Date()).getDay() === 2;\r
         *              }\r
         *          }\r
         *      });\r
         *\r
         * With the above declaration, any `responsiveConfig` can now use these values\r
         * like so:\r
         *\r
         *      responsiveConfig: {\r
         *          small: {\r
         *              hidden: true\r
         *          },\r
         *          'medium && !tuesday': {\r
         *              hidden: false,\r
         *              region: 'north'\r
         *          },\r
         *          large: {\r
         *              hidden: false,\r
         *              region: 'west'\r
         *          }\r
         *      }\r
         *\r
         * @since 5.0.1\r
         */\r
        responsiveFormulas: {\r
            $value: 0,\r
\r
            merge: function (newValue, oldValue, target, mixinClass) {\r
                return this.mergeNew(newValue, oldValue, target, mixinClass);\r
            }\r
        }\r
    },\r
\r
    /**\r
     * This method removes this instance from the Responsive collection.\r
     */\r
    destroy: function () {\r
        Responsive.unregister(this);\r
        this.callParent();\r
    },\r
\r
    privates: {\r
        statics: {\r
            /**\r
             * @property {Boolean} active\r
             * @static\r
             * @private\r
             */\r
            active: false,\r
\r
            /**\r
             * @property {Object} all\r
             * The collection of all `Responsive` instances. These are the instances that\r
             * will be notified when dynamic conditions change.\r
             * @static\r
             * @private\r
             */\r
            all: {},\r
\r
            /**\r
             * @property {Object} context\r
             * This object holds the various context values passed to the rule evaluation\r
             * functions.\r
             * @static\r
             * @private\r
             */\r
            context: Ext.Object.chain(Ext.platformTags),\r
\r
            /**\r
             * @property {Number} count\r
             * The number of instances in the `all` collection.\r
             * @static\r
             * @private\r
             */\r
            count: 0,\r
\r
            /**\r
             * @property {Number} nextId\r
             * The seed value used to assign `Responsive` instances a unique id for keying\r
             * in the `all` collection.\r
             * @static\r
             * @private\r
             */\r
            nextId: 0,\r
\r
            /**\r
             * Activates event listeners for all `Responsive` instances. This method is\r
             * called when the first instance is registered.\r
             * @private\r
             */\r
            activate: function () {\r
                Responsive.active = true;\r
                Responsive.updateContext();\r
                Ext.on('resize', Responsive.onResize, Responsive);\r
            },\r
\r
            /**\r
             * Deactivates event listeners. This method is called when the last instance\r
             * is destroyed.\r
             * @private\r
             */\r
            deactivate: function () {\r
                Responsive.active = false;\r
                Ext.un('resize', Responsive.onResize, Responsive);\r
            },\r
\r
            /**\r
             * Updates all registered the `Responsive` instances (found in the `all`\r
             * collection).\r
             * @private\r
             */\r
            notify: function () {\r
                var all = Responsive.all,\r
                    context = Responsive.context,\r
                    globalEvents = Ext.GlobalEvents,\r
                    timer = Responsive.timer,\r
                    id;\r
\r
                if (timer) {\r
                    Responsive.timer = null;\r
                    Ext.Function.cancelAnimationFrame(timer);\r
                }\r
\r
                Responsive.updateContext();\r
\r
                Ext.suspendLayouts();\r
\r
                globalEvents.fireEvent('beforeresponsiveupdate', context);\r
\r
                for (id in all) {\r
                    all[id].setupResponsiveContext();\r
                }\r
\r
                globalEvents.fireEvent('beginresponsiveupdate', context);\r
\r
                for (id in all) {\r
                    all[id].updateResponsiveState();\r
                }\r
\r
                globalEvents.fireEvent('responsiveupdate', context);\r
\r
                Ext.resumeLayouts(true);\r
            },\r
\r
            /**\r
             * Handler of the window resize event. Schedules a timer so that we eventually\r
             * call `notify`.\r
             * @private\r
             */\r
            onResize: function () {\r
                if (!Responsive.timer) {\r
                    Responsive.timer = Ext.Function.requestAnimationFrame(Responsive.onTimer);\r
                }\r
            },\r
\r
            /**\r
             * This method is the timer handler. When called this removes the timer and\r
             * calls `notify`.\r
             * @private\r
             */\r
            onTimer: function () {\r
                Responsive.timer = null;\r
                Responsive.notify();\r
            },\r
\r
            /**\r
             * This method is called to update the internal state of a given config since\r
             * the config is needed prior to `initConfig` processing the `instanceConfig`.\r
             *\r
             * @param {Ext.Base} instance The instance to configure.\r
             * @param {Object} instanceConfig The config for the instance.\r
             * @param {String} name The name of the config to process.\r
             * @private\r
             * @since 5.0.1\r
             */\r
            processConfig: function (instance, instanceConfig, name) {\r
                var value = instanceConfig && instanceConfig[name],\r
                    config = instance.config,\r
                    cfg, configurator;\r
\r
                // Good news is that both configs we have to handle have custom merges\r
                // so we just need to get the Ext.Config instance and call it.\r
                if (value) {\r
                    configurator = instance.getConfigurator();\r
                    cfg = configurator.configs[name]; // the Ext.Config instance\r
\r
                    // Update "this.config" which is the storage for this instance.\r
                    config[name] = cfg.merge(value, config[name], instance);\r
                }\r
            },\r
\r
            register: function (responder) {\r
                var id = responder.$responsiveId;\r
\r
                if (!id) {\r
                    responder.$responsiveId = id = ++Responsive.nextId;\r
\r
                    Responsive.all[id] = responder;\r
\r
                    if (++Responsive.count === 1) {\r
                        Responsive.activate();\r
                    }\r
                }\r
            },\r
\r
            unregister: function (responder) {\r
                var id = responder.$responsiveId;\r
\r
                if (id in Responsive.all) {\r
                    responder.$responsiveId = null;\r
\r
                    delete Responsive.all[id];\r
\r
                    if (--Responsive.count === 0) {\r
                        Responsive.deactivate();\r
                    }\r
                }\r
            },\r
\r
            /**\r
             * Updates the `context` object base on the current environment.\r
             * @private\r
             */\r
            updateContext: function () {\r
                var El = Ext.Element,\r
                    width = El.getViewportWidth(),\r
                    height = El.getViewportHeight(),\r
                    context = Responsive.context;\r
\r
                context.width = width;\r
                context.height = height;\r
                context.tall = width < height;\r
                context.wide = !context.tall;\r
\r
                context.landscape = context.portrait = false;\r
                if (!context.platform) {\r
                    context.platform = Ext.platformTags;\r
                }\r
\r
                context[Ext.dom.Element.getOrientation()] = true;\r
            }\r
        }, // private static\r
\r
        //--------------------------------------------------------------------------\r
\r
        /**\r
         * This class system hook method is called at the tail end of the mixin process.\r
         * We need to see if the `targetClass` has already got a `responsiveConfig` and\r
         * if so, we must add its value to the real config.\r
         * @param {Ext.Class} targetClass\r
         * @private\r
         */\r
        afterClassMixedIn: function (targetClass) {\r
            var proto = targetClass.prototype,\r
                responsiveConfig = proto.responsiveConfig,\r
                responsiveFormulas = proto.responsiveFormulas,\r
                config;\r
\r
            if (responsiveConfig || responsiveFormulas) {\r
                config = {};\r
\r
                if (responsiveConfig) {\r
                    delete proto.responsiveConfig;\r
                    config.responsiveConfig = responsiveConfig;\r
                }\r
\r
                if (responsiveFormulas) {\r
                    delete proto.responsiveFormulas;\r
                    config.responsiveFormulas = responsiveFormulas;\r
                }\r
\r
                targetClass.getConfigurator().add(config);\r
            }\r
        },\r
\r
        // The reason this method exists is so to convince the config system to put the\r
        // "responsiveConfig" and "responsiveFormulas" in the initList. This needs to be\r
        // done so that the initGetter is setup prior to calling transformInstanceConfig\r
        // when we need to call the getters.\r
\r
        applyResponsiveConfig: function (rules) {\r
            for (var rule in rules) {\r
                rules[rule].fn = Ext.createRuleFn(rule);\r
            }\r
            return rules;\r
        },\r
\r
        applyResponsiveFormulas: function (formulas) {\r
            var ret = {},\r
                fn, name;\r
\r
            if (formulas) {\r
                for (name in formulas) {\r
                    if (Ext.isString(fn = formulas[name])) {\r
                        fn = Ext.createRuleFn(fn);\r
                    }\r
                    ret[name] = fn;\r
                }\r
            }\r
\r
            return ret;\r
        },\r
\r
        /**\r
         * Evaluates and returns the configs based on the `responsiveConfig`. This\r
         * method relies on the state being captured by the `updateContext` method.\r
         * @private\r
         */\r
        getResponsiveState: function () {\r
            var context = Responsive.context,\r
                rules = this.getResponsiveConfig(),\r
                ret = {},\r
                entry, rule;\r
\r
            if (rules) {\r
                for (rule in rules) {\r
                    entry = rules[rule];\r
                    if (entry.fn.call(this, context)) {\r
                        Ext.merge(ret, entry.config);\r
                    }\r
                }\r
            }\r
\r
            return ret;\r
        },\r
\r
        setupResponsiveContext: function () {\r
            var formulas = this.getResponsiveFormulas(),\r
                context = Responsive.context,\r
                name;\r
\r
            if (formulas) {\r
                for (name in formulas) {\r
                    context[name] = formulas[name].call(this, context);\r
                }\r
            }\r
        },\r
\r
        /**\r
         * This config system hook method is called just prior to processing the specified\r
         * "instanceConfig". This hook returns the instanceConfig that will actually be\r
         * processed by the config system.\r
         * @param {Object} instanceConfig The user-supplied instance config object.\r
         * @private\r
         */\r
        transformInstanceConfig: function (instanceConfig) {\r
            var me = this,\r
                ret;\r
\r
            Responsive.register(me);\r
\r
            // Since we are called immediately prior to the Configurator looking at the\r
            // instanceConfig, that incoming value has not yet been merged on to\r
            // "this.config". We need to call getResponsiveConfig and getResponsiveFormulas\r
            // and still get all that merged goodness, so we have to do the merge here.\r
\r
            if (instanceConfig) {\r
                Responsive.processConfig(me, instanceConfig, 'responsiveConfig');\r
                Responsive.processConfig(me, instanceConfig, 'responsiveFormulas');\r
            }\r
\r
            // For updates this is done in bulk prior to updating all of the responsive\r
            // objects, but for instantiation, we have to do this for ourselves now.\r
            me.setupResponsiveContext();\r
\r
            // Now we can merge the current responsive state with the incoming config.\r
            // The responsiveConfig takes priority.\r
            ret = me.getResponsiveState();\r
\r
            if (instanceConfig) {\r
                ret = Ext.merge({}, instanceConfig, ret);\r
\r
                // We don't want these to remain since we've already handled them.\r
                delete ret.responsiveConfig;\r
                delete ret.responsiveFormulas;\r
            }\r
\r
            return ret;\r
        },\r
\r
        /**\r
         * Evaluates and applies the `responsiveConfig` to this instance. This is called\r
         * by `notify` automatically.\r
         * @private\r
         */\r
        updateResponsiveState: function () {\r
            var config = this.getResponsiveState();\r
            this.setConfig(config);\r
        }\r
    } // private\r
}});\r