Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / Card.html
index 824bd0b..ea66aa8 100644 (file)
   <pre class="prettyprint lang-js"><span id='Ext-layout-container-Card'>/**
 </span> * @class Ext.layout.container.Card
  * @extends Ext.layout.container.AbstractCard
-  * &lt;p&gt;This layout manages multiple child Components, each fitted to the Container, where only a single child Component can be
-  * visible at any given time.  This layout style is most commonly used for wizards, tab implementations, etc.
-  * This class is intended to be extended or created via the layout:'card' {@link Ext.container.Container#layout} config,
-  * and should generally not need to be created directly via the new keyword.&lt;/p&gt;
-  * &lt;p&gt;The CardLayout's focal method is {@link #setActiveItem}.  Since only one panel is displayed at a time,
-  * the only way to move from one Component to the next is by calling setActiveItem, passing the id or index of
-  * the next panel to display.  The layout itself does not provide a user interface for handling this navigation,
-  * so that functionality must be provided by the developer.&lt;/p&gt;
-  * &lt;p&gt;In the following example, a simplistic wizard setup is demonstrated.  A button bar is added
-  * to the footer of the containing panel to provide navigation buttons.  The buttons will be handled by a
-  * common navigation routine -- for this example, the implementation of that routine has been ommitted since
-  * it can be any type of custom logic.  Note that other uses of a CardLayout (like a tab control) would require a
-  * completely different implementation.  For serious implementations, a better approach would be to extend
-  * CardLayout to provide the custom functionality needed.  
-  * {@img Ext.layout.container.Card/Ext.layout.container.Card.png Ext.layout.container.Card container layout}
-  * Example usage:&lt;/p&gt;
-  * &lt;pre&gt;&lt;code&gt;
-    var navHandler = function(direction){
-         // This routine could contain business logic required to manage the navigation steps.
-         // It would call setActiveItem as needed, manage navigation button state, handle any
-         // branching logic that might be required, handle alternate actions like cancellation
-         // or finalization, etc.  A complete wizard implementation could get pretty
-         // sophisticated depending on the complexity required, and should probably be
-         // done as a subclass of CardLayout in a real-world implementation.
-     };
-
-    Ext.create('Ext.panel.Panel', {
-        title: 'Example Wizard',
-        width: 300,
-        height: 200,
-        layout: 'card',
-        activeItem: 0, // make sure the active item is set on the container config!
-        bodyStyle: 'padding:15px',
-        defaults: {
-            // applied to each contained panel
-            border:false
-        },
-        // just an example of one possible navigation scheme, using buttons
-        bbar: [
-        {
-            id: 'move-prev',
-            text: 'Back',
-            handler: navHandler(this, [-1]),
-            disabled: true
-        },
-        '-&gt;', // greedy spacer so that the buttons are aligned to each side
-        {
-            id: 'move-next',
-            text: 'Next',
-            handler: navHandler(this, [1])
-        }],
-        // the panels (or &quot;cards&quot;) within the layout
-        items: [{
-            id: 'card-0',
-            html: '&amp;lt;h1&amp;gt;Welcome to the Wizard!&amp;lt;/h1&amp;gt;&amp;lt;p&amp;gt;Step 1 of 3&amp;lt;/p&amp;gt;'
-        },{
-            id: 'card-1',
-            html: '&amp;lt;p&amp;gt;Step 2 of 3&amp;lt;/p&amp;gt;'
-        },{
-            id: 'card-2',
-            html: '&amp;lt;h1&amp;gt;Congratulations!&amp;lt;/h1&amp;gt;&amp;lt;p&amp;gt;Step 3 of 3 - Complete&amp;lt;/p&amp;gt;'
-        }],
-        renderTo: Ext.getBody()
-    });  
- &lt;/code&gt;&lt;/pre&gt;
-  */
+ *
+ * This layout manages multiple child Components, each fitted to the Container, where only a single child Component can be
+ * visible at any given time.  This layout style is most commonly used for wizards, tab implementations, etc.
+ * This class is intended to be extended or created via the layout:'card' {@link Ext.container.Container#layout} config,
+ * and should generally not need to be created directly via the new keyword.
+ *
+ * The CardLayout's focal method is {@link #setActiveItem}.  Since only one panel is displayed at a time,
+ * the only way to move from one Component to the next is by calling setActiveItem, passing the id or index of
+ * the next panel to display.  The layout itself does not provide a user interface for handling this navigation,
+ * so that functionality must be provided by the developer.
+ *
+ * In the following example, a simplistic wizard setup is demonstrated.  A button bar is added
+ * to the footer of the containing panel to provide navigation buttons.  The buttons will be handled by a
+ * common navigation routine.  Note that other uses of a CardLayout (like a tab control) would require a
+ * completely different implementation.  For serious implementations, a better approach would be to extend
+ * CardLayout to provide the custom functionality needed.
+ *
+ * {@img Ext.layout.container.Card/Ext.layout.container.Card.png Ext.layout.container.Card container layout}
+ *
+ * Example usage:
+ * 
+ *     var navigate = function(panel, direction){
+ *         // This routine could contain business logic required to manage the navigation steps.
+ *         // It would call setActiveItem as needed, manage navigation button state, handle any
+ *         // branching logic that might be required, handle alternate actions like cancellation
+ *         // or finalization, etc.  A complete wizard implementation could get pretty
+ *         // sophisticated depending on the complexity required, and should probably be
+ *         // done as a subclass of CardLayout in a real-world implementation.
+ *         var layout = panel.getLayout();
+ *         layout[direction]();
+ *         Ext.getCmp('move-prev').setDisabled(!layout.getPrev());
+ *         Ext.getCmp('move-next').setDisabled(!layout.getNext());
+ *     };
+ *  
+ *     Ext.create('Ext.panel.Panel', {
+ *         title: 'Example Wizard',
+ *         width: 300,
+ *         height: 200,
+ *         layout: 'card',
+ *         activeItem: 0, // make sure the active item is set on the container config!
+ *         bodyStyle: 'padding:15px',
+ *         defaults: {
+ *             // applied to each contained panel
+ *             border: false
+ *         },
+ *         // just an example of one possible navigation scheme, using buttons
+ *         bbar: [
+ *             {
+ *                 id: 'move-prev',
+ *                 text: 'Back',
+ *                 handler: function(btn) {
+ *                     navigate(btn.up(&quot;panel&quot;), &quot;prev&quot;);
+ *                 },
+ *                 disabled: true
+ *             },
+ *             '-&gt;', // greedy spacer so that the buttons are aligned to each side
+ *             {
+ *                 id: 'move-next',
+ *                 text: 'Next',
+ *                 handler: function(btn) {
+ *                     navigate(btn.up(&quot;panel&quot;), &quot;next&quot;);
+ *                 }
+ *             }
+ *         ],
+ *         // the panels (or &quot;cards&quot;) within the layout
+ *         items: [{
+ *             id: 'card-0',
+ *             html: '&lt;h1&gt;Welcome to the Wizard!&lt;/h1&gt;&lt;p&gt;Step 1 of 3&lt;/p&gt;'
+ *         },{
+ *             id: 'card-1',
+ *             html: '&lt;p&gt;Step 2 of 3&lt;/p&gt;'
+ *         },{
+ *             id: 'card-2',
+ *             html: '&lt;h1&gt;Congratulations!&lt;/h1&gt;&lt;p&gt;Step 3 of 3 - Complete&lt;/p&gt;'
+ *         }],
+ *         renderTo: Ext.getBody()
+ *     });  
+ */
 Ext.define('Ext.layout.container.Card', {
 
     /* Begin Definitions */
@@ -95,15 +107,32 @@ Ext.define('Ext.layout.container.Card', {
 
     /* End Definitions */
 
+<span id='Ext-layout-container-Card-method-setActiveItem'>    /**
+</span>     * Makes the given card active.
+     * 
+     *     var card1 = Ext.create('Ext.panel.Panel', {itemId: 'card-1'});
+     *     var card2 = Ext.create('Ext.panel.Panel', {itemId: 'card-2'});
+     *     var panel = Ext.create('Ext.panel.Panel', {
+     *         layout: 'card',
+     *         activeItem: 0,
+     *         items: [card1, card2]
+     *     });
+     *     // These are all equivalent
+     *     panel.getLayout().setActiveItem(card2);
+     *     panel.getLayout().setActiveItem('card-2');
+     *     panel.getLayout().setActiveItem(1);
+     * 
+     * @param {Ext.Component/Number/String} newCard  The component, component {@link Ext.Component#id id},
+     * {@link Ext.Component#itemId itemId}, or index of component.
+     * @return {Ext.Component} the activated component or false when nothing activated.
+     * False is returned also when trying to activate an already active card.
+     */
     setActiveItem: function(newCard) {
         var me = this,
             owner = me.owner,
             oldCard = me.activeItem,
             newIndex;
 
-        // Block upward layouts until we are done.
-        me.layoutBusy = true;
-
         newCard = me.parseActiveItem(newCard);
         newIndex = owner.items.indexOf(newCard);
 
@@ -125,22 +154,22 @@ Ext.define('Ext.layout.container.Card', {
 
             // Fire the beforeactivate and beforedeactivate events on the cards
             if (newCard.fireEvent('beforeactivate', newCard, oldCard) === false) {
-                me.layoutBusy = false;
                 return false;
             }
             if (oldCard &amp;&amp; oldCard.fireEvent('beforedeactivate', oldCard, newCard) === false) {
-                me.layoutBusy = false;
                 return false;
             }
 
             // If the card hasnt been sized yet, do it now
-            if (!me.sizeAllCards) {
-                me.setItemBox(newCard, me.getTargetBox());
-            }
-            else {
+            if (me.sizeAllCards) {
                 // onLayout calls setItemBox
                 me.onLayout();
             }
+            else {
+                me.setItemBox(newCard, me.getTargetBox());
+            }
+
+            me.owner.suspendLayout = true;
 
             if (oldCard) {
                 if (me.hideInactive) {
@@ -150,25 +179,28 @@ Ext.define('Ext.layout.container.Card', {
             }
 
             // Make sure the new card is shown
+            me.owner.suspendLayout = false;
             if (newCard.hidden) {
                 newCard.show();
+            } else {
+                me.onLayout();
             }
 
             newCard.fireEvent('activate', newCard, oldCard);
 
-            me.layoutBusy = false;
-
-            if (!me.sizeAllCards) {
-                if (!owner.componentLayout.layoutBusy) {
-                    me.onLayout();
-                }
-            }
             return newCard;
         }
-
-        me.layoutBusy = false;
         return false;
-    }
-});</pre>
+    },
+
+    configureItem: function(item) {
+
+        // Card layout only controls dimensions which IT has controlled.
+        // That calculation has to be determined at run time by examining the ownerCt's isFixedWidth()/isFixedHeight() methods
+        item.layoutManagedHeight = 0;
+        item.layoutManagedWidth = 0;
+
+        this.callParent(arguments);
+    }});</pre>
 </body>
 </html>