add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / layout / container / Card.js

/**\r
 * This layout manages multiple child Components, each fitted to the Container, where only a single child Component can be\r
 * visible at any given time.  This layout style is most commonly used for wizards, tab implementations, etc.\r
 * This class is intended to be extended or created via the layout:'card' {@link Ext.container.Container#layout} config,\r
 * and should generally not need to be created directly via the new keyword.\r
 *\r
 * The CardLayout's focal method is {@link #setActiveItem}.  Since only one panel is displayed at a time,\r
 * the only way to move from one Component to the next is by calling setActiveItem, passing the next panel to display\r
 * (or its id or index).  The layout itself does not provide a user interface for handling this navigation,\r
 * so that functionality must be provided by the developer.\r
 *\r
 * To change the active card of a container, call the setActiveItem method of its layout:\r
 *\r
 *     @example\r
 *     var p = Ext.create('Ext.panel.Panel', {\r
 *         layout: 'card',\r
 *         items: [\r
 *             { html: 'Card 1' },\r
 *             { html: 'Card 2' }\r
 *         ],\r
 *         renderTo: Ext.getBody()\r
 *     });\r
 *\r
 *     p.getLayout().setActiveItem(1);\r
 * \r
 * The {@link Ext.Component#beforedeactivate beforedeactivate} and {@link Ext.Component#beforeactivate beforeactivate}\r
 * events can be used to prevent a card from activating or deactivating by returning `false`.\r
 * \r
 *     @example   \r
 *     var active = 0;\r
 *     var main = Ext.create('Ext.panel.Panel', {\r
 *         renderTo: Ext.getBody(),\r
 *         width: 200,\r
 *         height: 200,\r
 *         layout: 'card',\r
 *         tbar: [{\r
 *             text: 'Next',\r
 *             handler: function(){\r
 *                 var layout = main.getLayout();\r
 *                 ++active;\r
 *                 layout.setActiveItem(active);\r
 *                 active = main.items.indexOf(layout.getActiveItem());\r
 *             }\r
 *         }],\r
 *         items: [{\r
 *             title: 'P1'\r
 *         }, {\r
 *             title: 'P2'\r
 *         }, {\r
 *             title: 'P3',\r
 *             listeners: {\r
 *                 beforeactivate: function(){\r
 *                     return false;\r
 *                 }\r
 *             }\r
 *         }]\r
 *     });\r
 *\r
 * In the following example, a simplistic wizard setup is demonstrated.  A button bar is added\r
 * to the footer of the containing panel to provide navigation buttons.  The buttons will be handled by a\r
 * common navigation routine.  Note that other uses of a CardLayout (like a tab control) would require a\r
 * completely different implementation.  For serious implementations, a better approach would be to extend\r
 * CardLayout to provide the custom functionality needed.\r
 *\r
 *     @example\r
 *     var navigate = function(panel, direction){\r
 *         // This routine could contain business logic required to manage the navigation steps.\r
 *         // It would call setActiveItem as needed, manage navigation button state, handle any\r
 *         // branching logic that might be required, handle alternate actions like cancellation\r
 *         // or finalization, etc.  A complete wizard implementation could get pretty\r
 *         // sophisticated depending on the complexity required, and should probably be\r
 *         // done as a subclass of CardLayout in a real-world implementation.\r
 *         var layout = panel.getLayout();\r
 *         layout[direction]();\r
 *         Ext.getCmp('move-prev').setDisabled(!layout.getPrev());\r
 *         Ext.getCmp('move-next').setDisabled(!layout.getNext());\r
 *     };\r
 *\r
 *     Ext.create('Ext.panel.Panel', {\r
 *         title: 'Example Wizard',\r
 *         width: 300,\r
 *         height: 200,\r
 *         layout: 'card',\r
 *         bodyStyle: 'padding:15px',\r
 *         defaults: {\r
 *             // applied to each contained panel\r
 *             border: false\r
 *         },\r
 *         // just an example of one possible navigation scheme, using buttons\r
 *         bbar: [\r
 *             {\r
 *                 id: 'move-prev',\r
 *                 text: 'Back',\r
 *                 handler: function(btn) {\r
 *                     navigate(btn.up("panel"), "prev");\r
 *                 },\r
 *                 disabled: true\r
 *             },\r
 *             '->', // greedy spacer so that the buttons are aligned to each side\r
 *             {\r
 *                 id: 'move-next',\r
 *                 text: 'Next',\r
 *                 handler: function(btn) {\r
 *                     navigate(btn.up("panel"), "next");\r
 *                 }\r
 *             }\r
 *         ],\r
 *         // the panels (or "cards") within the layout\r
 *         items: [{\r
 *             id: 'card-0',\r
 *             html: '<h1>Welcome to the Wizard!</h1><p>Step 1 of 3</p>'\r
 *         },{\r
 *             id: 'card-1',\r
 *             html: '<p>Step 2 of 3</p>'\r
 *         },{\r
 *             id: 'card-2',\r
 *             html: '<h1>Congratulations!</h1><p>Step 3 of 3 - Complete</p>'\r
 *         }],\r
 *         renderTo: Ext.getBody()\r
 *     });\r
 */\r
Ext.define('Ext.layout.container.Card', {\r
\r
    /* Begin Definitions */\r
\r
    extend: 'Ext.layout.container.Fit',\r
\r
    alternateClassName: 'Ext.layout.CardLayout',\r
\r
    alias: 'layout.card',\r
\r
    /* End Definitions */\r
\r
    type: 'card',\r
\r
    hideInactive: true,\r
\r
    /**\r
     * @cfg {Boolean} deferredRender\r
     * True to render each contained item at the time it becomes active, false to render all contained items\r
     * as soon as the layout is rendered (defaults to false).  If there is a significant amount of content or\r
     * a lot of heavy controls being rendered into panels that are not displayed by default, setting this to\r
     * true might improve performance.\r
     */\r
    deferredRender : false,\r
\r
    getRenderTree: function () {\r
        var me = this,\r
            activeItem = me.getActiveItem();\r
\r
        if (activeItem) {\r
\r
            // If they veto the activate, we have no active item\r
            if (activeItem.hasListeners.beforeactivate && activeItem.fireEvent('beforeactivate', activeItem) === false) {\r
 \r
                // We must null our activeItem reference, AND the one in our owning Container.\r
                // Because upon layout invalidation, renderChildren will use this.getActiveItem which\r
                // uses this.activeItem || this.owner.activeItem\r
                activeItem = me.activeItem = me.owner.activeItem = null;\r
            }\r
            \r
            // Item is to be the active one. Fire event after it is first layed out\r
            else if (activeItem.hasListeners.activate) {\r
                activeItem.on({\r
                    boxready: function() {\r
                        activeItem.fireEvent('activate', activeItem);\r
                    },\r
                    single: true\r
                });\r
            }\r
\r
            if (me.deferredRender) {\r
                if (activeItem) {\r
                    return me.getItemsRenderTree([activeItem]);\r
                }\r
            } else {\r
                return me.callParent(arguments);\r
            }\r
        }\r
    },\r
\r
    renderChildren: function () {\r
        var me = this,\r
            active = me.getActiveItem();\r
\r
        if (!me.deferredRender) {\r
            me.callParent();\r
        } else if (active) {\r
            // ensure the active item is configured for the layout\r
            me.renderItems([active], me.getRenderTarget());\r
        }\r
    },\r
\r
    isValidParent : function(item, target, position) {\r
        // Note: Card layout does not care about order within the target because only one is ever visible.\r
        // We only care whether the item is a direct child of the target.\r
        var itemEl = item.el ? item.el.dom : Ext.getDom(item);\r
        return (itemEl && itemEl.parentNode === (target.dom || target)) || false;\r
    },\r
\r
    /**\r
     * Return the active (visible) component in the layout.\r
     * @return {Ext.Component}\r
     */\r
    getActiveItem: function() {\r
        var me = this,\r
            // It's necessary to check that me.activeItem is not undefined as it could be 0 (falsey). We're more interested in\r
            // checking the layout's activeItem property, since that is the source of truth for an activeItem.  If it's\r
            // determined to be empty, check the owner. Note that a default item is returned if activeItem is `undefined` but\r
            // not `null`. Also, note that `null` is legitimate value and completely different from `undefined`.\r
            item = me.activeItem === undefined ? (me.owner && me.owner.activeItem) : me.activeItem,\r
            result = me.parseActiveItem(item);\r
\r
        // Sanitize the result in case the active item is no longer there.\r
        if (result && me.owner.items.indexOf(result) !== -1) {\r
            me.activeItem = result;\r
        }\r
\r
        // Note that in every use case me.activeItem will have a truthy value except for when a container or tabpanel is explicity\r
        // configured with activeItem/Tab === null or when an out-of-range index is given for an active tab (as it will be undefined).\r
        // In those cases, it is meaningful to return the null value, so do so.\r
        return result == null ? null : (me.activeItem || me.owner.activeItem);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    parseActiveItem: function (item) {\r
        var activeItem;\r
\r
        if (item && item.isComponent) {\r
            activeItem = item;\r
        } else if (typeof item === 'number' || item === undefined) {\r
            activeItem = this.getLayoutItems()[item || 0];\r
        } else if (item === null) {\r
            activeItem = null;\r
        } else {\r
            activeItem = this.owner.getComponent(item);\r
        }\r
\r
        return activeItem;\r
    },\r
\r
    /**\r
     * @private\r
     * Called before both dynamic render, and bulk render.\r
     * Ensure that the active item starts visible, and inactive ones start invisible.\r
     */\r
    configureItem: function(item) {\r
        item.setHiddenState(item !== this.getActiveItem());\r
        this.callParent(arguments);\r
    },\r
\r
    onAdd: function (item, pos) {\r
        this.callParent([item, pos]);\r
        this.setItemHideMode(item);\r
    },\r
\r
    onRemove: function(component) {\r
        var me = this;\r
\r
        me.callParent([component]);\r
        me.resetItemHideMode(component);\r
\r
        if (component === me.activeItem) {\r
            // Note setting to `undefined` is intentional. Don't null it out since null now has a specific meaning in\r
            // tab management (it specifies not setting an active item).\r
            me.activeItem = undefined;\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    getAnimation: function(newCard, owner) {\r
        var newAnim = (newCard || {}).cardSwitchAnimation;\r
        if (newAnim === false) {\r
            return false;\r
        }\r
        return newAnim || owner.cardSwitchAnimation;\r
    },\r
\r
    /**\r
     * Return the active (visible) component in the layout to the next card\r
     * @return {Ext.Component} The next component or false.\r
     */\r
    getNext: function() {\r
        var wrap = arguments[0],\r
            items = this.getLayoutItems(),\r
            index = Ext.Array.indexOf(items, this.activeItem);\r
            \r
        return items[index + 1] || (wrap ? items[0] : false);\r
    },\r
\r
    /**\r
     * Sets the active (visible) component in the layout to the next card\r
     * @return {Ext.Component} the activated component or false when nothing activated.\r
     */\r
    next: function() {\r
        var anim = arguments[0], \r
            wrap = arguments[1];\r
        return this.setActiveItem(this.getNext(wrap), anim);\r
    },\r
\r
    /**\r
     * Return the active (visible) component in the layout to the previous card\r
     * @return {Ext.Component} The previous component or false.\r
     */\r
    getPrev: function() {\r
        var wrap = arguments[0],\r
            items = this.getLayoutItems(),\r
            index = Ext.Array.indexOf(items, this.activeItem);\r
            \r
        return items[index - 1] || (wrap ? items[items.length - 1] : false);\r
    },\r
\r
    /**\r
     * Sets the active (visible) component in the layout to the previous card\r
     * @return {Ext.Component} the activated component or false when nothing activated.\r
     */\r
    prev: function() {\r
        var anim = arguments[0], \r
            wrap = arguments[1];\r
        return this.setActiveItem(this.getPrev(wrap), anim);\r
    },\r
\r
    /**\r
     * Makes the given card active.\r
     *\r
     *     var card1 = Ext.create('Ext.panel.Panel', {itemId: 'card-1'});\r
     *     var card2 = Ext.create('Ext.panel.Panel', {itemId: 'card-2'});\r
     *     var panel = Ext.create('Ext.panel.Panel', {\r
     *         layout: 'card',\r
     *         activeItem: 0,\r
     *         items: [card1, card2]\r
     *     });\r
     *     // These are all equivalent\r
     *     panel.getLayout().setActiveItem(card2);\r
     *     panel.getLayout().setActiveItem('card-2');\r
     *     panel.getLayout().setActiveItem(1);\r
     *\r
     * @param {Ext.Component/Number/String} newCard  The component, component {@link Ext.Component#id id},\r
     * {@link Ext.Component#itemId itemId}, or index of component.\r
     * @return {Ext.Component} the activated component or false when nothing activated.\r
     * False is returned also when trying to activate an already active card.\r
     */\r
    setActiveItem: function(newCard) {\r
        var me = this,\r
            owner = me.owner,\r
            oldCard = me.activeItem,\r
            rendered = owner.rendered,\r
            newIndex, focusNewCard;\r
\r
        newCard = me.parseActiveItem(newCard);\r
        newIndex = owner.items.indexOf(newCard);\r
\r
        // If the card is not a child of the owner, then add it.\r
        // Without doing a layout!\r
        if (newIndex === -1) {\r
            newIndex = owner.items.items.length;\r
            Ext.suspendLayouts();\r
            newCard = owner.add(newCard);\r
            Ext.resumeLayouts();\r
        }\r
\r
        // Is this a valid, different card?\r
        if (newCard && oldCard !== newCard) {\r
            // Fire the beforeactivate and beforedeactivate events on the cards\r
            if (newCard.fireEvent('beforeactivate', newCard, oldCard) === false) {\r
                return false;\r
            }\r
            if (oldCard && oldCard.fireEvent('beforedeactivate', oldCard, newCard) === false) {\r
                return false;\r
            }\r
\r
            if (rendered) {\r
                Ext.suspendLayouts();\r
\r
                // If the card has not been rendered yet, now is the time to do so.\r
                if (!newCard.rendered) {\r
                    me.renderItem(newCard, me.getRenderTarget(), owner.items.length);\r
                }\r
\r
                if (oldCard) {\r
                    if (me.hideInactive) {\r
                        focusNewCard = oldCard.el.contains(Ext.Element.getActiveElement());\r
\r
                        oldCard.hide();\r
\r
                        if (oldCard.hidden) {\r
                            oldCard.hiddenByLayout = true;\r
                            oldCard.fireEvent('deactivate', oldCard, newCard);\r
                        }\r
                        // Hide was vetoed, we cannot change cards.\r
                        else {\r
                            return false;\r
                        }\r
                    }\r
                }\r
\r
                // Make sure the new card is shown\r
                if (newCard.hidden) {\r
                    newCard.show();\r
                }\r
\r
                // Layout needs activeItem to be correct, so clear it if the show has been vetoed,\r
                // set it if the show has *not* been vetoed.\r
                if (newCard.hidden) {\r
                    me.activeItem = newCard = null;\r
                } else {\r
                    me.activeItem = newCard;\r
\r
                    // If the card being hidden contained focus, attempt to focus the new card\r
                    // So as not to leave focus undefined.\r
                    // The focus() call will focus the defaultFocus if it is a container\r
                    // so ensure there is a defaultFocus.\r
                    if (focusNewCard) {\r
                        if (!newCard.defaultFocus) {\r
                            newCard.defaultFocus = ':focusable';\r
                        }\r
                        newCard.focus();\r
                    }\r
                }\r
\r
                Ext.resumeLayouts(true);\r
            } else {\r
                me.activeItem = newCard;\r
            }\r
\r
            newCard.fireEvent('activate', newCard, oldCard);\r
\r
            return me.activeItem;\r
        }\r
        return false;\r
    },\r
\r
    /**\r
     * @private\r
     * Reset back to initial config when item is removed from the panel.\r
     */\r
    resetItemHideMode: function (item) {\r
        item.hideMode = item.originalHideMode;\r
        delete item.originalHideMode;\r
    },\r
\r
    /**\r
     * @private\r
     * A card layout items must have its visibility mode set to OFFSETS so its scroll\r
     * positions isn't reset when hidden.\r
     *\r
     * Do this automatically when an item is added to the panel.\r
     */\r
    setItemHideMode: function (item) {\r
        item.originalHideMode = item.hideMode;\r
        item.hideMode = 'offsets';\r
    }\r
});\r