docs/source/Panel4.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-tab-Panel-method-constructor'><span id='Ext-tab-Panel'>/**
  19 </span></span> * @author Ed Spencer, Tommy Maintz, Brian Moeskau
  20  * @class Ext.tab.Panel
  21  * @extends Ext.panel.Panel
  22
  23 A basic tab container. TabPanels can be used exactly like a standard {@link Ext.panel.Panel} for layout purposes, but also
  24 have special support for containing child Components (`{@link Ext.container.Container#items items}`) that are managed
  25 using a {@link Ext.layout.container.Card CardLayout layout manager}, and displayed as separate tabs.
  26
  27 __Note:__
  28
  29 By default, a tab's close tool _destroys_ the child tab Component and all its descendants. This makes the child tab
  30 Component, and all its descendants __unusable__. To enable re-use of a tab, configure the TabPanel with `{@link #autoDestroy autoDestroy: false}`.
  31
  32 __TabPanel's layout:__
  33
  34 TabPanels use a Dock layout to position the {@link Ext.tab.Bar TabBar} at the top of the widget. Panels added to the TabPanel will have their
  35 header hidden by default because the Tab will automatically take the Panel's configured title and icon.
  36
  37 TabPanels use their {@link Ext.panel.Panel#header header} or {@link Ext.panel.Panel#footer footer} element (depending on the {@link #tabPosition}
  38 configuration) to accommodate the tab selector buttons. This means that a TabPanel will not display any configured title, and will not display any
  39 configured header {@link Ext.panel.Panel#tools tools}.
  40
  41 To display a header, embed the TabPanel in a {@link Ext.panel.Panel Panel} which uses `{@link Ext.container.Container#layout layout:'fit'}`.
  42
  43 __Examples:__
  44
  45 Here is a basic TabPanel rendered to the body. This also shows the useful configuration {@link #activeTab}, which allows you to set the active tab on render.
  46 If you do not set an {@link #activeTab}, no tabs will be active by default.
  47 {@img Ext.tab.Panel/Ext.tab.Panel1.png TabPanel component}
  48 Example usage:
  49
  50     Ext.create('Ext.tab.Panel', {
  51         width: 300,
  52         height: 200,
  53         activeTab: 0,
  54         items: [
  55             {
  56                 title: 'Tab 1',
  57                 bodyPadding: 10,
  58                 html : 'A simple tab'
  59             },
  60             {
  61                 title: 'Tab 2',
  62                 html : 'Another one'
  63             }
  64         ],
  65         renderTo : Ext.getBody()
  66     });
  67
  68 It is easy to control the visibility of items in the tab bar. Specify hidden: true to have the
  69 tab button hidden initially. Items can be subsequently hidden and show by accessing the
  70 tab property on the child item.
  71
  72 Example usage:
  73
  74     var tabs = Ext.create('Ext.tab.Panel', {
  75         width: 400,
  76         height: 400,
  77         renderTo: document.body,
  78         items: [{
  79             title: 'Home',
  80             html: 'Home',
  81             itemId: 'home'
  82         }, {
  83             title: 'Users',
  84             html: 'Users',
  85             itemId: 'users',
  86             hidden: true
  87         }, {
  88             title: 'Tickets',
  89             html: 'Tickets',
  90             itemId: 'tickets'
  91         }]
  92     });
  93
  94     setTimeout(function(){
  95         tabs.child('#home').tab.hide();
  96         var users = tabs.child('#users');
  97         users.tab.show();
  98         tabs.setActiveTab(users);
  99     }, 1000);
 100
 101 You can remove the background of the TabBar by setting the {@link #plain} property to `false`.
 102
 103 Example usage:
 104
 105     Ext.create('Ext.tab.Panel', {
 106         width: 300,
 107         height: 200,
 108         activeTab: 0,
 109         plain: true,
 110         items: [
 111             {
 112                 title: 'Tab 1',
 113                 bodyPadding: 10,
 114                 html : 'A simple tab'
 115             },
 116             {
 117                 title: 'Tab 2',
 118                 html : 'Another one'
 119             }
 120         ],
 121         renderTo : Ext.getBody()
 122     });
 123
 124 Another useful configuration of TabPanel is {@link #tabPosition}. This allows you to change the position where the tabs are displayed. The available
 125 options for this are `'top'` (default) and `'bottom'`.
 126 {@img Ext.tab.Panel/Ext.tab.Panel2.png TabPanel component}
 127 Example usage:
 128
 129     Ext.create('Ext.tab.Panel', {
 130         width: 300,
 131         height: 200,
 132         activeTab: 0,
 133         bodyPadding: 10,
 134         tabPosition: 'bottom',
 135         items: [
 136             {
 137                 title: 'Tab 1',
 138                 html : 'A simple tab'
 139             },
 140             {
 141                 title: 'Tab 2',
 142                 html : 'Another one'
 143             }
 144         ],
 145         renderTo : Ext.getBody()
 146     });
 147
 148 The {@link #setActiveTab} is a very useful method in TabPanel which will allow you to change the current active tab. You can either give it an index or
 149 an instance of a tab.
 150
 151 Example usage:
 152
 153     var tabs = Ext.create('Ext.tab.Panel', {
 154         items: [
 155             {
 156                 id   : 'my-tab',
 157                 title: 'Tab 1',
 158                 html : 'A simple tab'
 159             },
 160             {
 161                 title: 'Tab 2',
 162                 html : 'Another one'
 163             }
 164         ],
 165         renderTo : Ext.getBody()
 166     });
 167
 168     var tab = Ext.getCmp('my-tab');
 169
 170     Ext.create('Ext.button.Button', {
 171         renderTo: Ext.getBody(),
 172         text    : 'Select the first tab',
 173         scope   : this,
 174         handler : function() {
 175             tabs.setActiveTab(tab);
 176         }
 177     });
 178
 179     Ext.create('Ext.button.Button', {
 180         text    : 'Select the second tab',
 181         scope   : this,
 182         handler : function() {
 183             tabs.setActiveTab(1);
 184         },
 185         renderTo : Ext.getBody()
 186     });
 187
 188 The {@link #getActiveTab} is a another useful method in TabPanel which will return the current active tab.
 189
 190 Example usage:
 191
 192     var tabs = Ext.create('Ext.tab.Panel', {
 193         items: [
 194             {
 195                 title: 'Tab 1',
 196                 html : 'A simple tab'
 197             },
 198             {
 199                 title: 'Tab 2',
 200                 html : 'Another one'
 201             }
 202         ],
 203         renderTo : Ext.getBody()
 204     });
 205
 206     Ext.create('Ext.button.Button', {
 207         text    : 'Get active tab',
 208         scope   : this,
 209         handler : function() {
 210             var tab = tabs.getActiveTab();
 211             alert('Current tab: ' + tab.title);
 212         },
 213         renderTo : Ext.getBody()
 214     });
 215
 216 Adding a new tab is very simple with a TabPanel. You simple call the {@link #add} method with an config object for a panel.
 217
 218 Example usage:
 219
 220     var tabs = Ext.Create('Ext.tab.Panel', {
 221         items: [
 222             {
 223                 title: 'Tab 1',
 224                 html : 'A simple tab'
 225             },
 226             {
 227                 title: 'Tab 2',
 228                 html : 'Another one'
 229             }
 230         ],
 231         renderTo : Ext.getBody()
 232     });
 233
 234     Ext.create('Ext.button.Button', {
 235         text    : 'New tab',
 236         scope   : this,
 237         handler : function() {
 238             var tab = tabs.add({
 239                 title: 'Tab ' + (tabs.items.length + 1), //we use the tabs.items property to get the length of current items/tabs
 240                 html : 'Another one'
 241             });
 242
 243             tabs.setActiveTab(tab);
 244         },
 245         renderTo : Ext.getBody()
 246     });
 247
 248 Additionally, removing a tab is very also simple with a TabPanel. You simple call the {@link #remove} method with an config object for a panel.
 249
 250 Example usage:
 251
 252     var tabs = Ext.Create('Ext.tab.Panel', {
 253         items: [
 254             {
 255                 title: 'Tab 1',
 256                 html : 'A simple tab'
 257             },
 258             {
 259                 id   : 'remove-this-tab',
 260                 title: 'Tab 2',
 261                 html : 'Another one'
 262             }
 263         ],
 264         renderTo : Ext.getBody()
 265     });
 266
 267     Ext.Create('Ext.button.Button', {
 268         text    : 'Remove tab',
 269         scope   : this,
 270         handler : function() {
 271             var tab = Ext.getCmp('remove-this-tab');
 272             tabs.remove(tab);
 273         },
 274         renderTo : Ext.getBody()
 275     });
 276
 277  * @extends Ext.Panel
 278  * @constructor
 279  * @param {Object} config The configuration options
 280  * @xtype tabpanel
 281  * @markdown
 282  */
 283 Ext.define('Ext.tab.Panel', {
 284     extend: 'Ext.panel.Panel',
 285     alias: 'widget.tabpanel',
 286     alternateClassName: ['Ext.TabPanel'],
 287
 288     requires: ['Ext.layout.container.Card', 'Ext.tab.Bar'],
 289
 290 <span id='Ext-tab-Panel-cfg-tabPosition'>    /**
 291 </span>     * @cfg {String} tabPosition The position where the tab strip should be rendered (defaults to &lt;code&gt;'top'&lt;/code&gt;).
 292      * In 4.0, The only other supported value is &lt;code&gt;'bottom'&lt;/code&gt;.
 293      */
 294     tabPosition : 'top',
 295
 296 <span id='Ext-tab-Panel-cfg-tabBar'>    /**
 297 </span>     * @cfg {Object} tabBar Optional configuration object for the internal {@link Ext.tab.Bar}. If present, this is
 298      * passed straight through to the TabBar's constructor
 299      */
 300
 301 <span id='Ext-tab-Panel-cfg-layout'>    /**
 302 </span>     * @cfg {Object} layout Optional configuration object for the internal {@link Ext.layout.container.Card card layout}.
 303      * If present, this is passed straight through to the layout's constructor
 304      */
 305
 306 <span id='Ext-tab-Panel-cfg-removePanelHeader'>    /**
 307 </span>     * @cfg {Boolean} removePanelHeader True to instruct each Panel added to the TabContainer to not render its header
 308      * element. This is to ensure that the title of the panel does not appear twice. Defaults to true.
 309      */
 310     removePanelHeader: true,
 311
 312 <span id='Ext-tab-Panel-cfg-Boolean'>    /**
 313 </span>     * @cfg Boolean plain
 314      * True to not show the full background on the TabBar
 315      */
 316     plain: false,
 317
 318 <span id='Ext-tab-Panel-cfg-itemCls'>    /**
 319 </span>     * @cfg {String} itemCls The class added to each child item of this TabPanel. Defaults to 'x-tabpanel-child'.
 320      */
 321     itemCls: 'x-tabpanel-child',
 322
 323 <span id='Ext-tab-Panel-cfg-minTabWidth'>    /**
 324 </span>     * @cfg {Number} minTabWidth The minimum width for a tab in the {@link #tabBar}. Defaults to &lt;code&gt;30&lt;/code&gt;.
 325      */
 326
 327 <span id='Ext-tab-Panel-cfg-deferredRender'>    /**
 328 </span>     * @cfg {Boolean} deferredRender
 329      * &lt;p&gt;&lt;tt&gt;true&lt;/tt&gt; by default to defer the rendering of child &lt;tt&gt;{@link Ext.container.Container#items items}&lt;/tt&gt;
 330      * to the browsers DOM until a tab is activated. &lt;tt&gt;false&lt;/tt&gt; will render all contained
 331      * &lt;tt&gt;{@link Ext.container.Container#items items}&lt;/tt&gt; as soon as the {@link Ext.layout.container.Card layout}
 332      * is rendered. If there is a significant amount of content or a lot of heavy controls being
 333      * rendered into panels that are not displayed by default, setting this to &lt;tt&gt;true&lt;/tt&gt; might
 334      * improve performance.&lt;/p&gt;
 335      * &lt;br&gt;&lt;p&gt;The &lt;tt&gt;deferredRender&lt;/tt&gt; property is internally passed to the layout manager for
 336      * TabPanels ({@link Ext.layout.container.Card}) as its {@link Ext.layout.container.Card#deferredRender}
 337      * configuration value.&lt;/p&gt;
 338      * &lt;br&gt;&lt;p&gt;&lt;b&gt;Note&lt;/b&gt;: leaving &lt;tt&gt;deferredRender&lt;/tt&gt; as &lt;tt&gt;true&lt;/tt&gt; means that the content
 339      * within an unactivated tab will not be available&lt;/p&gt;
 340      */
 341     deferredRender : true,
 342
 343     //inherit docs
 344     initComponent: function() {
 345         var me = this,
 346             dockedItems = me.dockedItems || [],
 347             activeTab = me.activeTab || 0;
 348
 349         me.layout = Ext.create('Ext.layout.container.Card', Ext.apply({
 350             owner: me,
 351             deferredRender: me.deferredRender,
 352             itemCls: me.itemCls
 353         }, me.layout));
 354
 355 <span id='Ext-tab-Panel-property-tabBar'>        /**
 356 </span>         * @property tabBar
 357          * @type Ext.TabBar
 358          * Internal reference to the docked TabBar
 359          */
 360         me.tabBar = Ext.create('Ext.tab.Bar', Ext.apply({}, me.tabBar, {
 361             dock: me.tabPosition,
 362             plain: me.plain,
 363             border: me.border,
 364             cardLayout: me.layout,
 365             tabPanel: me
 366         }));
 367
 368         if (dockedItems &amp;&amp; !Ext.isArray(dockedItems)) {
 369             dockedItems = [dockedItems];
 370         }
 371
 372         dockedItems.push(me.tabBar);
 373         me.dockedItems = dockedItems;
 374
 375         me.addEvents(
 376 <span id='Ext-tab-Panel-event-beforetabchange'>            /**
 377 </span>             * @event beforetabchange
 378              * Fires before a tab change (activated by {@link #setActiveTab}). Return false in any listener to cancel
 379              * the tabchange
 380              * @param {Ext.tab.Panel} tabPanel The TabPanel
 381              * @param {Ext.Component} newCard The card that is about to be activated
 382              * @param {Ext.Component} oldCard The card that is currently active
 383              */
 384             'beforetabchange',
 385
 386 <span id='Ext-tab-Panel-event-tabchange'>            /**
 387 </span>             * @event tabchange
 388              * Fires when a new tab has been activated (activated by {@link #setActiveTab}).
 389              * @param {Ext.tab.Panel} tabPanel The TabPanel
 390              * @param {Ext.Component} newCard The newly activated item
 391              * @param {Ext.Component} oldCard The previously active item
 392              */
 393             'tabchange'
 394         );
 395         me.callParent(arguments);
 396
 397         //set the active tab
 398         me.setActiveTab(activeTab);
 399         //set the active tab after initial layout
 400         me.on('afterlayout', me.afterInitialLayout, me, {single: true});
 401     },
 402
 403 <span id='Ext-tab-Panel-method-afterInitialLayout'>    /**
 404 </span>     * @private
 405      * We have to wait until after the initial layout to visually activate the activeTab (if set).
 406      * The active tab has different margins than normal tabs, so if the initial layout happens with
 407      * a tab active, its layout will be offset improperly due to the active margin style. Waiting
 408      * until after the initial layout avoids this issue.
 409      */
 410     afterInitialLayout: function() {
 411         var me = this,
 412             card = me.getComponent(me.activeTab);
 413
 414         if (card) {
 415             me.layout.setActiveItem(card);
 416         }
 417     },
 418
 419 <span id='Ext-tab-Panel-method-setActiveTab'>    /**
 420 </span>     * Makes the given card active (makes it the visible card in the TabPanel's CardLayout and highlights the Tab)
 421      * @param {Ext.Component} card The card to make active
 422      */
 423     setActiveTab: function(card) {
 424         var me = this,
 425             previous;
 426
 427         card = me.getComponent(card);
 428         if (card) {
 429             previous = me.getActiveTab();
 430
 431             if (previous &amp;&amp; previous !== card &amp;&amp; me.fireEvent('beforetabchange', me, card, previous) === false) {
 432                 return false;
 433             }
 434
 435             me.tabBar.setActiveTab(card.tab);
 436             me.activeTab = card;
 437             if (me.rendered) {
 438                 me.layout.setActiveItem(card);
 439             }
 440
 441             if (previous &amp;&amp; previous !== card) {
 442                 me.fireEvent('tabchange', me, card, previous);
 443             }
 444         }
 445     },
 446
 447 <span id='Ext-tab-Panel-method-getActiveTab'>    /**
 448 </span>     * Returns the item that is currently active inside this TabPanel. Note that before the TabPanel first activates a
 449      * child component this will return whatever was configured in the {@link #activeTab} config option
 450      * @return {Ext.Component/Integer} The currently active item
 451      */
 452     getActiveTab: function() {
 453         return this.activeTab;
 454     },
 455
 456 <span id='Ext-tab-Panel-method-getTabBar'>    /**
 457 </span>     * Returns the {@link Ext.tab.Bar} currently used in this TabPanel
 458      * @return {Ext.TabBar} The TabBar
 459      */
 460     getTabBar: function() {
 461         return this.tabBar;
 462     },
 463
 464 <span id='Ext-tab-Panel-method-onAdd'>    /**
 465 </span>     * @ignore
 466      * Makes sure we have a Tab for each item added to the TabPanel
 467      */
 468     onAdd: function(item, index) {
 469         var me = this;
 470
 471         item.tab = me.tabBar.insert(index, {
 472             xtype: 'tab',
 473             card: item,
 474             disabled: item.disabled,
 475             closable: item.closable,
 476             hidden: item.hidden,
 477             tabBar: me.tabBar
 478         });
 479
 480         item.on({
 481             scope : me,
 482             enable: me.onItemEnable,
 483             disable: me.onItemDisable,
 484             beforeshow: me.onItemBeforeShow,
 485             iconchange: me.onItemIconChange,
 486             titlechange: me.onItemTitleChange
 487         });
 488
 489         if (item.isPanel) {
 490             if (me.removePanelHeader) {
 491                 item.preventHeader = true;
 492                 if (item.rendered) {
 493                     item.updateHeader();
 494                 }
 495             }
 496             if (item.isPanel &amp;&amp; me.border) {
 497                 item.setBorder(false);
 498             }
 499         }
 500
 501         // ensure that there is at least one active tab
 502         if (this.rendered &amp;&amp; me.items.getCount() === 1) {
 503             me.setActiveTab(0);
 504         }
 505     },
 506
 507 <span id='Ext-tab-Panel-method-onItemEnable'>    /**
 508 </span>     * @private
 509      * Enable corresponding tab when item is enabled.
 510      */
 511     onItemEnable: function(item){
 512         item.tab.enable();
 513     },
 514
 515 <span id='Ext-tab-Panel-method-onItemDisable'>    /**
 516 </span>     * @private
 517      * Disable corresponding tab when item is enabled.
 518      */
 519     onItemDisable: function(item){
 520         item.tab.disable();
 521     },
 522
 523 <span id='Ext-tab-Panel-method-onItemBeforeShow'>    /**
 524 </span>     * @private
 525      * Sets activeTab before item is shown.
 526      */
 527     onItemBeforeShow: function(item) {
 528         if (item !== this.activeTab) {
 529             this.setActiveTab(item);
 530             return false;
 531         }
 532     },
 533
 534 <span id='Ext-tab-Panel-method-onItemIconChange'>    /**
 535 </span>     * @private
 536      * Update the tab iconCls when panel iconCls has been set or changed.
 537      */
 538     onItemIconChange: function(item, newIconCls) {
 539         item.tab.setIconCls(newIconCls);
 540         this.getTabBar().doLayout();
 541     },
 542
 543 <span id='Ext-tab-Panel-method-onItemTitleChange'>    /**
 544 </span>     * @private
 545      * Update the tab title when panel title has been set or changed.
 546      */
 547     onItemTitleChange: function(item, newTitle) {
 548         item.tab.setText(newTitle);
 549         this.getTabBar().doLayout();
 550     },
 551
 552
 553 <span id='Ext-tab-Panel-method-doRemove'>    /**
 554 </span>     * @ignore
 555      * If we're removing the currently active tab, activate the nearest one. The item is removed when we call super,
 556      * so we can do preprocessing before then to find the card's index
 557      */
 558     doRemove: function(item, autoDestroy) {
 559         var me = this,
 560             items = me.items,
 561 <span id='Ext-tab-Panel-property-hasItemsLeft'>            /**
 562 </span>             * At this point the item hasn't been removed from the items collection.
 563              * As such, if we want to check if there are no more tabs left, we have to
 564              * check for one, as opposed to 0.
 565              */
 566             hasItemsLeft = items.getCount() &gt; 1;
 567
 568         if (me.destroying || !hasItemsLeft) {
 569             me.activeTab = null;
 570         } else if (item === me.activeTab) {
 571              me.setActiveTab(item.next() || items.getAt(0));
 572         }
 573         me.callParent(arguments);
 574
 575         // Remove the two references
 576         delete item.tab.card;
 577         delete item.tab;
 578     },
 579
 580 <span id='Ext-tab-Panel-method-onRemove'>    /**
 581 </span>     * @ignore
 582      * Makes sure we remove the corresponding Tab when an item is removed
 583      */
 584     onRemove: function(item, autoDestroy) {
 585         var me = this;
 586
 587         item.un({
 588             scope : me,
 589             enable: me.onItemEnable,
 590             disable: me.onItemDisable,
 591             beforeshow: me.onItemBeforeShow
 592         });
 593         if (!me.destroying &amp;&amp; item.tab.ownerCt == me.tabBar) {
 594             me.tabBar.remove(item.tab);
 595         }
 596     }
 597 });
 598 </pre>
 599 </body>
 600 </html>