Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / docs / source / CardLayout.html
index 280d1a5..abed4b4 100644 (file)
-<html>\r
-<head>\r
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js"><div id="cls-Ext.layout.CardLayout"></div>/**\r
- * @class Ext.layout.CardLayout\r
- * @extends Ext.layout.FitLayout\r
- * <p>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#layout} config,\r
- * and should generally not need to be created directly via the new keyword.</p>\r
- * <p>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 id or index of\r
- * the next panel to display.  The layout itself does not provide a user interface for handling this navigation,\r
- * so that functionality must be provided by the developer.</p>\r
- * <p>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 -- for this example, the implementation of that routine has been ommitted since\r
- * it can be any type of custom logic.  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.  Example usage:</p>\r
- * <pre><code>\r
-var navHandler = function(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
-};\r
-\r
-var card = new Ext.Panel({\r
-    title: 'Example Wizard',\r
-    layout:'card',\r
-    activeItem: 0, // make sure the active item is set on the container config!\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: navHandler.createDelegate(this, [-1]),\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: navHandler.createDelegate(this, [1])\r
-        }\r
-    ],\r
-    // the panels (or "cards") within the layout\r
-    items: [{\r
-        id: 'card-0',\r
-        html: '&lt;h1&gt;Welcome to the Wizard!&lt;/h1&gt;&lt;p&gt;Step 1 of 3&lt;/p&gt;'\r
-    },{\r
-        id: 'card-1',\r
-        html: '&lt;p&gt;Step 2 of 3&lt;/p&gt;'\r
-    },{\r
-        id: 'card-2',\r
-        html: '&lt;h1&gt;Congratulations!&lt;/h1&gt;&lt;p&gt;Step 3 of 3 - Complete&lt;/p&gt;'\r
-    }]\r
-});\r
-</code></pre>\r
- */\r
-Ext.layout.CardLayout = Ext.extend(Ext.layout.FitLayout, {\r
-    <div id="cfg-Ext.layout.CardLayout-deferredRender"></div>/**\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
-    <div id="cfg-Ext.layout.CardLayout-layoutOnCardChange"></div>/**\r
-     * @cfg {Boolean} layoutOnCardChange\r
-     * True to force a layout of the active item when the active card is changed. Defaults to false.\r
-     */\r
-    layoutOnCardChange : false,\r
-\r
-    <div id="cfg-Ext.layout.CardLayout-renderHidden"></div>/**\r
-     * @cfg {Boolean} renderHidden @hide\r
-     */\r
-    // private\r
-    renderHidden : true,\r
-\r
-    type: 'card',\r
-\r
-    constructor: function(config){\r
-        Ext.layout.CardLayout.superclass.constructor.call(this, config);\r
-    },\r
-\r
-    <div id="method-Ext.layout.CardLayout-setActiveItem"></div>/**\r
-     * Sets the active (visible) item in the layout.\r
-     * @param {String/Number} item The string component id or numeric index of the item to activate\r
-     */\r
-    setActiveItem : function(item){\r
-        var ai = this.activeItem,\r
-            ct = this.container;\r
-        item = ct.getComponent(item);\r
-\r
-        // Is this a valid, different card?\r
-        if(item && ai != item){\r
-\r
-            // Changing cards, hide the current one\r
-            if(ai){\r
-                ai.hide();\r
-                if (ai.hidden !== true) {\r
-                    return false;\r
-                }\r
-                ai.fireEvent('deactivate', ai);\r
-            }\r
-            // Change activeItem reference\r
-            this.activeItem = item;\r
-\r
-            // The container is about to get a recursive layout, remove any deferLayout reference\r
-            // because it will trigger a redundant layout.\r
-            delete item.deferLayout;\r
-\r
-            // Show the new component\r
-            item.show();\r
-\r
-            this.layout();\r
-\r
-            if(item.doLayout){\r
-                item.doLayout();\r
-            }\r
-            item.fireEvent('activate', item);\r
-        }\r
-    },\r
-\r
-    // private\r
-    renderAll : function(ct, target){\r
-        if(this.deferredRender){\r
-            this.renderItem(this.activeItem, undefined, target);\r
-        }else{\r
-            Ext.layout.CardLayout.superclass.renderAll.call(this, ct, target);\r
-        }\r
-    }\r
-});\r
-Ext.Container.LAYOUTS['card'] = Ext.layout.CardLayout;</pre>    \r
-</body>\r
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <title>The source code</title>
+    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+</head>
+<body  onload="prettyPrint();">
+    <pre class="prettyprint lang-js">/*!
+ * Ext JS Library 3.3.1
+ * Copyright(c) 2006-2010 Sencha Inc.
+ * licensing@sencha.com
+ * http://www.sencha.com/license
+ */
+<div id="cls-Ext.layout.CardLayout"></div>/**
+ * @class Ext.layout.CardLayout
+ * @extends Ext.layout.FitLayout
+ * <p>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#layout} config,
+ * and should generally not need to be created directly via the new keyword.</p>
+ * <p>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.</p>
+ * <p>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.  Example usage:</p>
+ * <pre><code>
+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.
+};
+
+var card = new Ext.Panel({
+    title: 'Example Wizard',
+    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.createDelegate(this, [-1]),
+            disabled: true
+        },
+        '->', // greedy spacer so that the buttons are aligned to each side
+        {
+            id: 'move-next',
+            text: 'Next',
+            handler: navHandler.createDelegate(this, [1])
+        }
+    ],
+    // the panels (or "cards") 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;'
+    }]
+});
+</code></pre>
+ */
+Ext.layout.CardLayout = Ext.extend(Ext.layout.FitLayout, {
+    <div id="cfg-Ext.layout.CardLayout-deferredRender"></div>/**
+     * @cfg {Boolean} deferredRender
+     * True to render each contained item at the time it becomes active, false to render all contained items
+     * as soon as the layout is rendered (defaults to false).  If there is a significant amount of content or
+     * a lot of heavy controls being rendered into panels that are not displayed by default, setting this to
+     * true might improve performance.
+     */
+    deferredRender : false,
+
+    <div id="cfg-Ext.layout.CardLayout-layoutOnCardChange"></div>/**
+     * @cfg {Boolean} layoutOnCardChange
+     * True to force a layout of the active item when the active card is changed. Defaults to false.
+     */
+    layoutOnCardChange : false,
+
+    <div id="cfg-Ext.layout.CardLayout-renderHidden"></div>/**
+     * @cfg {Boolean} renderHidden @hide
+     */
+    // private
+    renderHidden : true,
+
+    type: 'card',
+
+    <div id="method-Ext.layout.CardLayout-setActiveItem"></div>/**
+     * Sets the active (visible) item in the layout.
+     * @param {String/Number} item The string component id or numeric index of the item to activate
+     */
+    setActiveItem : function(item){
+        var ai = this.activeItem,
+            ct = this.container;
+        item = ct.getComponent(item);
+
+        // Is this a valid, different card?
+        if(item && ai != item){
+
+            // Changing cards, hide the current one
+            if(ai){
+                ai.hide();
+                if (ai.hidden !== true) {
+                    return false;
+                }
+                ai.fireEvent('deactivate', ai);
+            }
+
+            var layout = item.doLayout && (this.layoutOnCardChange || !item.rendered);
+
+            // Change activeItem reference
+            this.activeItem = item;
+
+            // The container is about to get a recursive layout, remove any deferLayout reference
+            // because it will trigger a redundant layout.
+            delete item.deferLayout;
+
+            // Show the new component
+            item.show();
+
+            this.layout();
+
+            if(layout){
+                item.doLayout();
+            }
+            item.fireEvent('activate', item);
+        }
+    },
+
+    // private
+    renderAll : function(ct, target){
+        if(this.deferredRender){
+            this.renderItem(this.activeItem, undefined, target);
+        }else{
+            Ext.layout.CardLayout.superclass.renderAll.call(this, ct, target);
+        }
+    }
+});
+Ext.Container.LAYOUTS['card'] = Ext.layout.CardLayout;
+</pre>    
+</body>
 </html>
\ No newline at end of file