Upgrade to ExtJS 3.0.3 - Released 10/11/2009
[extjs.git] / docs / source / TabPanel.html
1 <html>
2 <head>
3   <title>The source code</title>
4     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
5     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
6 </head>
7 <body  onload="prettyPrint();">
8     <pre class="prettyprint lang-js">/*!
9  * Ext JS Library 3.0.3
10  * Copyright(c) 2006-2009 Ext JS, LLC
11  * licensing@extjs.com
12  * http://www.extjs.com/license
13  */
14 <div id="cls-Ext.TabPanel"></div>/**
15  * @class Ext.TabPanel
16  * <p>A basic tab container. TabPanels can be used exactly like a standard {@link Ext.Panel}
17  * for layout purposes, but also have special support for containing child Components
18  * (<tt>{@link Ext.Container#items items}</tt>) that are managed using a
19  * {@link Ext.layout.CardLayout CardLayout layout manager}, and displayed as separate tabs.</p>
20  *
21  * <b>Note:</b> By default, a tab's close tool <i>destroys</i> the child tab Component
22  * and all its descendants. This makes the child tab Component, and all its descendants <b>unusable</b>. To enable
23  * re-use of a tab, configure the TabPanel with <b><code>{@link #autoDestroy autoDestroy: false}</code></b>.
24  *
25  * <p><b><u>TabPanel header/footer elements</u></b></p>
26  * <p>TabPanels use their {@link Ext.Panel#header header} or {@link Ext.Panel#footer footer} element
27  * (depending on the {@link #tabPosition} configuration) to accommodate the tab selector buttons.
28  * This means that a TabPanel will not display any configured title, and will not display any
29  * configured header {@link Ext.Panel#tools tools}.</p>
30  * <p>To display a header, embed the TabPanel in a {@link Ext.Panel Panel} which uses
31  * <b><tt>{@link Ext.Container#layout layout:'fit'}</tt></b>.</p>
32  *
33  * <p><b><u>Tab Events</u></b></p>
34  * <p>There is no actual tab class &mdash; each tab is simply a {@link Ext.BoxComponent Component}
35  * such as a {@link Ext.Panel Panel}. However, when rendered in a TabPanel, each child Component
36  * can fire additional events that only exist for tabs and are not available from other Components.
37  * These events are:</p>
38  * <div><ul class="mdetail-params">
39  * <li><tt><b>{@link Ext.Panel#activate activate}</b></tt> : Fires when this Component becomes
40  * the active tab.</li>
41  * <li><tt><b>{@link Ext.Panel#deactivate deactivate}</b></tt> : Fires when the Component that
42  * was the active tab becomes deactivated.</li>
43  * </ul></div>
44  * <p><b><u>Creating TabPanels from Code</u></b></p>
45  * <p>TabPanels can be created and rendered completely in code, as in this example:</p>
46  * <pre><code>
47 var tabs = new Ext.TabPanel({
48     renderTo: Ext.getBody(),
49     activeTab: 0,
50     items: [{
51         title: 'Tab 1',
52         html: 'A simple tab'
53     },{
54         title: 'Tab 2',
55         html: 'Another one'
56     }]
57 });
58 </code></pre>
59  * <p><b><u>Creating TabPanels from Existing Markup</u></b></p>
60  * <p>TabPanels can also be rendered from pre-existing markup in a couple of ways.</p>
61  * <div><ul class="mdetail-params">
62  *
63  * <li>Pre-Structured Markup</li>
64  * <div class="sub-desc">
65  * <p>A container div with one or more nested tab divs with class <tt>'x-tab'</tt> can be rendered entirely
66  * from existing markup (See the {@link #autoTabs} example).</p>
67  * </div>
68  *
69  * <li>Un-Structured Markup</li>
70  * <div class="sub-desc">
71  * <p>A TabPanel can also be rendered from markup that is not strictly structured by simply specifying by id
72  * which elements should be the container and the tabs. Using this method tab content can be pulled from different
73  * elements within the page by id regardless of page structure. For example:</p>
74  * <pre><code>
75 var tabs = new Ext.TabPanel({
76     renderTo: 'my-tabs',
77     activeTab: 0,
78     items:[
79         {contentEl:'tab1', title:'Tab 1'},
80         {contentEl:'tab2', title:'Tab 2'}
81     ]
82 });
83
84 // Note that the tabs do not have to be nested within the container (although they can be)
85 &lt;div id="my-tabs">&lt;/div>
86 &lt;div id="tab1" class="x-hide-display">A simple tab&lt;/div>
87 &lt;div id="tab2" class="x-hide-display">Another one&lt;/div>
88 </code></pre>
89  * Note that the tab divs in this example contain the class <tt>'x-hide-display'</tt> so that they can be rendered
90  * deferred without displaying outside the tabs. You could alternately set <tt>{@link #deferredRender} = false </tt>
91  * to render all content tabs on page load.
92  * </div>
93  *
94  * </ul></div>
95  *
96  * @extends Ext.Panel
97  * @constructor
98  * @param {Object} config The configuration options
99  * @xtype tabpanel
100  */
101 Ext.TabPanel = Ext.extend(Ext.Panel,  {
102     <div id="cfg-Ext.TabPanel-layoutOnTabChange"></div>/**
103      * @cfg {Boolean} layoutOnTabChange
104      * Set to true to force a layout of the active tab when the tab is changed. Defaults to false.
105      * See {@link Ext.layout.CardLayout}.<code>{@link Ext.layout.CardLayout#layoutOnCardChange layoutOnCardChange}</code>.
106      */
107     <div id="cfg-Ext.TabPanel-tabCls"></div>/**
108      * @cfg {String} tabCls <b>This config option is used on <u>child Components</u> of ths TabPanel.</b> A CSS
109      * class name applied to the tab strip item representing the child Component, allowing special
110      * styling to be applied.
111      */
112     <div id="cfg-Ext.TabPanel-monitorResize"></div>/**
113      * @cfg {Boolean} monitorResize True to automatically monitor window resize events and rerender the layout on
114      * browser resize (defaults to true).
115      */
116     monitorResize : true,
117     <div id="cfg-Ext.TabPanel-deferredRender"></div>/**
118      * @cfg {Boolean} deferredRender
119      * <p><tt>true</tt> by default to defer the rendering of child <tt>{@link Ext.Container#items items}</tt>
120      * to the browsers DOM until a tab is activated. <tt>false</tt> will render all contained
121      * <tt>{@link Ext.Container#items items}</tt> as soon as the {@link Ext.layout.CardLayout layout}
122      * is rendered. If there is a significant amount of content or a lot of heavy controls being
123      * rendered into panels that are not displayed by default, setting this to <tt>true</tt> might
124      * improve performance.</p>
125      * <br><p>The <tt>deferredRender</tt> property is internally passed to the layout manager for
126      * TabPanels ({@link Ext.layout.CardLayout}) as its {@link Ext.layout.CardLayout#deferredRender}
127      * configuration value.</p>
128      * <br><p><b>Note</b>: leaving <tt>deferredRender</tt> as <tt>true</tt> means that the content
129      * within an unactivated tab will not be available. For example, this means that if the TabPanel
130      * is within a {@link Ext.form.FormPanel form}, then until a tab is activated, any Fields within
131      * unactivated tabs will not be rendered, and will therefore not be submitted and will not be
132      * available to either {@link Ext.form.BasicForm#getValues getValues} or
133      * {@link Ext.form.BasicForm#setValues setValues}.</p>
134      */
135     deferredRender : true,
136     <div id="cfg-Ext.TabPanel-tabWidth"></div>/**
137      * @cfg {Number} tabWidth The initial width in pixels of each new tab (defaults to 120).
138      */
139     tabWidth : 120,
140     <div id="cfg-Ext.TabPanel-minTabWidth"></div>/**
141      * @cfg {Number} minTabWidth The minimum width in pixels for each tab when {@link #resizeTabs} = true (defaults to 30).
142      */
143     minTabWidth : 30,
144     <div id="cfg-Ext.TabPanel-resizeTabs"></div>/**
145      * @cfg {Boolean} resizeTabs True to automatically resize each tab so that the tabs will completely fill the
146      * tab strip (defaults to false).  Setting this to true may cause specific widths that might be set per tab to
147      * be overridden in order to fit them all into view (although {@link #minTabWidth} will always be honored).
148      */
149     resizeTabs : false,
150     <div id="cfg-Ext.TabPanel-enableTabScroll"></div>/**
151      * @cfg {Boolean} enableTabScroll True to enable scrolling to tabs that may be invisible due to overflowing the
152      * overall TabPanel width. Only available with tabPosition:'top' (defaults to false).
153      */
154     enableTabScroll : false,
155     <div id="cfg-Ext.TabPanel-scrollIncrement"></div>/**
156      * @cfg {Number} scrollIncrement The number of pixels to scroll each time a tab scroll button is pressed
157      * (defaults to <tt>100</tt>, or if <tt>{@link #resizeTabs} = true</tt>, the calculated tab width).  Only
158      * applies when <tt>{@link #enableTabScroll} = true</tt>.
159      */
160     scrollIncrement : 0,
161     <div id="cfg-Ext.TabPanel-scrollRepeatInterval"></div>/**
162      * @cfg {Number} scrollRepeatInterval Number of milliseconds between each scroll while a tab scroll button is
163      * continuously pressed (defaults to <tt>400</tt>).
164      */
165     scrollRepeatInterval : 400,
166     <div id="cfg-Ext.TabPanel-scrollDuration"></div>/**
167      * @cfg {Float} scrollDuration The number of milliseconds that each scroll animation should last (defaults
168      * to <tt>.35</tt>). Only applies when <tt>{@link #animScroll} = true</tt>.
169      */
170     scrollDuration : 0.35,
171     <div id="cfg-Ext.TabPanel-animScroll"></div>/**
172      * @cfg {Boolean} animScroll True to animate tab scrolling so that hidden tabs slide smoothly into view (defaults
173      * to <tt>true</tt>).  Only applies when <tt>{@link #enableTabScroll} = true</tt>.
174      */
175     animScroll : true,
176     <div id="cfg-Ext.TabPanel-tabPosition"></div>/**
177      * @cfg {String} tabPosition The position where the tab strip should be rendered (defaults to <tt>'top'</tt>).
178      * The only other supported value is <tt>'bottom'</tt>.  <b>Note</b>: tab scrolling is only supported for
179      * <tt>tabPosition: 'top'</tt>.
180      */
181     tabPosition : 'top',
182     <div id="cfg-Ext.TabPanel-baseCls"></div>/**
183      * @cfg {String} baseCls The base CSS class applied to the panel (defaults to <tt>'x-tab-panel'</tt>).
184      */
185     baseCls : 'x-tab-panel',
186     <div id="cfg-Ext.TabPanel-autoTabs"></div>/**
187      * @cfg {Boolean} autoTabs
188      * <p><tt>true</tt> to query the DOM for any divs with a class of 'x-tab' to be automatically converted
189      * to tabs and added to this panel (defaults to <tt>false</tt>).  Note that the query will be executed within
190      * the scope of the container element only (so that multiple tab panels from markup can be supported via this
191      * method).</p>
192      * <p>This method is only possible when the markup is structured correctly as a container with nested divs
193      * containing the class <tt>'x-tab'</tt>. To create TabPanels without these limitations, or to pull tab content
194      * from other elements on the page, see the example at the top of the class for generating tabs from markup.</p>
195      * <p>There are a couple of things to note when using this method:<ul>
196      * <li>When using the <tt>autoTabs</tt> config (as opposed to passing individual tab configs in the TabPanel's
197      * {@link #items} collection), you must use <tt>{@link #applyTo}</tt> to correctly use the specified <tt>id</tt>
198      * as the tab container. The <tt>autoTabs</tt> method <em>replaces</em> existing content with the TabPanel
199      * components.</li>
200      * <li>Make sure that you set <tt>{@link #deferredRender}: false</tt> so that the content elements for each
201      * tab will be rendered into the TabPanel immediately upon page load, otherwise they will not be transformed
202      * until each tab is activated and will be visible outside the TabPanel.</li>
203      * </ul>Example usage:</p>
204      * <pre><code>
205 var tabs = new Ext.TabPanel({
206     applyTo: 'my-tabs',
207     activeTab: 0,
208     deferredRender: false,
209     autoTabs: true
210 });
211
212 // This markup will be converted to a TabPanel from the code above
213 &lt;div id="my-tabs">
214     &lt;div class="x-tab" title="Tab 1">A simple tab&lt;/div>
215     &lt;div class="x-tab" title="Tab 2">Another one&lt;/div>
216 &lt;/div>
217 </code></pre>
218      */
219     autoTabs : false,
220     <div id="cfg-Ext.TabPanel-autoTabSelector"></div>/**
221      * @cfg {String} autoTabSelector The CSS selector used to search for tabs in existing markup when
222      * <tt>{@link #autoTabs} = true</tt> (defaults to <tt>'div.x-tab'</tt>).  This can be any valid selector
223      * supported by {@link Ext.DomQuery#select}. Note that the query will be executed within the scope of this
224      * tab panel only (so that multiple tab panels from markup can be supported on a page).
225      */
226     autoTabSelector : 'div.x-tab',
227     <div id="cfg-Ext.TabPanel-activeTab"></div>/**
228      * @cfg {String/Number} activeTab A string id or the numeric index of the tab that should be initially
229      * activated on render (defaults to none).
230      */
231     activeTab : null,
232     <div id="cfg-Ext.TabPanel-tabMargin"></div>/**
233      * @cfg {Number} tabMargin The number of pixels of space to calculate into the sizing and scrolling of
234      * tabs. If you change the margin in CSS, you will need to update this value so calculations are correct
235      * with either <tt>{@link #resizeTabs}</tt> or scrolling tabs. (defaults to <tt>2</tt>)
236      */
237     tabMargin : 2,
238     <div id="cfg-Ext.TabPanel-plain"></div>/**
239      * @cfg {Boolean} plain </tt>true</tt> to render the tab strip without a background container image
240      * (defaults to <tt>false</tt>).
241      */
242     plain : false,
243     <div id="cfg-Ext.TabPanel-wheelIncrement"></div>/**
244      * @cfg {Number} wheelIncrement For scrolling tabs, the number of pixels to increment on mouse wheel
245      * scrolling (defaults to <tt>20</tt>).
246      */
247     wheelIncrement : 20,
248
249     /*
250      * This is a protected property used when concatenating tab ids to the TabPanel id for internal uniqueness.
251      * It does not generally need to be changed, but can be if external code also uses an id scheme that can
252      * potentially clash with this one.
253      */
254     idDelimiter : '__',
255
256     // private
257     itemCls : 'x-tab-item',
258
259     // private config overrides
260     elements : 'body',
261     headerAsText : false,
262     frame : false,
263     hideBorders :true,
264
265     // private
266     initComponent : function(){
267         this.frame = false;
268         Ext.TabPanel.superclass.initComponent.call(this);
269         this.addEvents(
270             <div id="event-Ext.TabPanel-beforetabchange"></div>/**
271              * @event beforetabchange
272              * Fires before the active tab changes. Handlers can <tt>return false</tt> to cancel the tab change.
273              * @param {TabPanel} this
274              * @param {Panel} newTab The tab being activated
275              * @param {Panel} currentTab The current active tab
276              */
277             'beforetabchange',
278             <div id="event-Ext.TabPanel-tabchange"></div>/**
279              * @event tabchange
280              * Fires after the active tab has changed.
281              * @param {TabPanel} this
282              * @param {Panel} tab The new active tab
283              */
284             'tabchange',
285             <div id="event-Ext.TabPanel-contextmenu"></div>/**
286              * @event contextmenu
287              * Relays the contextmenu event from a tab selector element in the tab strip.
288              * @param {TabPanel} this
289              * @param {Panel} tab The target tab
290              * @param {EventObject} e
291              */
292             'contextmenu'
293         );
294         <div id="cfg-Ext.TabPanel-layoutConfig"></div>/**
295          * @cfg {Object} layoutConfig
296          * TabPanel implicitly uses {@link Ext.layout.CardLayout} as its layout manager.
297          * <code>layoutConfig</code> may be used to configure this layout manager.
298          * <code>{@link #deferredRender}</code> and <code>{@link #layoutOnTabChange}</code>
299          * configured on the TabPanel will be applied as configs to the layout manager.
300          */
301         this.setLayout(new Ext.layout.CardLayout(Ext.apply({
302             layoutOnCardChange: this.layoutOnTabChange,
303             deferredRender: this.deferredRender
304         }, this.layoutConfig)));
305
306         if(this.tabPosition == 'top'){
307             this.elements += ',header';
308             this.stripTarget = 'header';
309         }else {
310             this.elements += ',footer';
311             this.stripTarget = 'footer';
312         }
313         if(!this.stack){
314             this.stack = Ext.TabPanel.AccessStack();
315         }
316         this.initItems();
317     },
318
319     // private
320     onRender : function(ct, position){
321         Ext.TabPanel.superclass.onRender.call(this, ct, position);
322
323         if(this.plain){
324             var pos = this.tabPosition == 'top' ? 'header' : 'footer';
325             this[pos].addClass('x-tab-panel-'+pos+'-plain');
326         }
327
328         var st = this[this.stripTarget];
329
330         this.stripWrap = st.createChild({cls:'x-tab-strip-wrap', cn:{
331             tag:'ul', cls:'x-tab-strip x-tab-strip-'+this.tabPosition}});
332
333         var beforeEl = (this.tabPosition=='bottom' ? this.stripWrap : null);
334         this.stripSpacer = st.createChild({cls:'x-tab-strip-spacer'}, beforeEl);
335         this.strip = new Ext.Element(this.stripWrap.dom.firstChild);
336
337         this.edge = this.strip.createChild({tag:'li', cls:'x-tab-edge'});
338         this.strip.createChild({cls:'x-clear'});
339
340         this.body.addClass('x-tab-panel-body-'+this.tabPosition);
341
342         <div id="cfg-Ext.TabPanel-itemTpl"></div>/**
343          * @cfg {Template/XTemplate} itemTpl <p>(Optional) A {@link Ext.Template Template} or
344          * {@link Ext.XTemplate XTemplate} which may be provided to process the data object returned from
345          * <tt>{@link #getTemplateArgs}</tt> to produce a clickable selector element in the tab strip.</p>
346          * <p>The main element created should be a <tt>&lt;li></tt> element. In order for a click event on
347          * a selector element to be connected to its item, it must take its <i>id</i> from the TabPanel's
348          * native <tt>{@link #getTemplateArgs}</tt>.</p>
349          * <p>The child element which contains the title text must be marked by the CSS class
350          * <tt>x-tab-strip-inner</tt>.</p>
351          * <p>To enable closability, the created element should contain an element marked by the CSS class
352          * <tt>x-tab-strip-close</tt>.</p>
353          * <p>If a custom <tt>itemTpl</tt> is supplied, it is the developer's responsibility to create CSS
354          * style rules to create the desired appearance.</p>
355          * Below is an example of how to create customized tab selector items:<pre><code>
356 new Ext.TabPanel({
357     renderTo: document.body,
358     minTabWidth: 115,
359     tabWidth: 135,
360     enableTabScroll: true,
361     width: 600,
362     height: 250,
363     defaults: {autoScroll:true},
364     itemTpl: new Ext.XTemplate(
365     '&lt;li class="{cls}" id="{id}" style="overflow:hidden">',
366          '&lt;tpl if="closable">',
367             '&lt;a class="x-tab-strip-close" onclick="return false;">&lt;/a>',
368          '&lt;/tpl>',
369          '&lt;a class="x-tab-right" href="#" onclick="return false;" style="padding-left:6px">',
370             '&lt;em class="x-tab-left">',
371                 '&lt;span class="x-tab-strip-inner">',
372                     '&lt;img src="{src}" style="float:left;margin:3px 3px 0 0">',
373                     '&lt;span style="margin-left:20px" class="x-tab-strip-text {iconCls}">{text} {extra}&lt;/span>',
374                 '&lt;/span>',
375             '&lt;/em>',
376         '&lt;/a>',
377     '&lt;/li>'
378     ),
379     getTemplateArgs: function(item) {
380 //      Call the native method to collect the base data. Like the ID!
381         var result = Ext.TabPanel.prototype.getTemplateArgs.call(this, item);
382
383 //      Add stuff used in our template
384         return Ext.apply(result, {
385             closable: item.closable,
386             src: item.iconSrc,
387             extra: item.extraText || ''
388         });
389     },
390     items: [{
391         title: 'New Tab 1',
392         iconSrc: '../shared/icons/fam/grid.png',
393         html: 'Tab Body 1',
394         closable: true
395     }, {
396         title: 'New Tab 2',
397         iconSrc: '../shared/icons/fam/grid.png',
398         html: 'Tab Body 2',
399         extraText: 'Extra stuff in the tab button'
400     }]
401 });
402 </code></pre>
403          */
404         if(!this.itemTpl){
405             var tt = new Ext.Template(
406                  '<li class="{cls}" id="{id}"><a class="x-tab-strip-close" onclick="return false;"></a>',
407                  '<a class="x-tab-right" href="#" onclick="return false;"><em class="x-tab-left">',
408                  '<span class="x-tab-strip-inner"><span class="x-tab-strip-text {iconCls}">{text}</span></span>',
409                  '</em></a></li>'
410             );
411             tt.disableFormats = true;
412             tt.compile();
413             Ext.TabPanel.prototype.itemTpl = tt;
414         }
415
416         this.items.each(this.initTab, this);
417     },
418
419     // private
420     afterRender : function(){
421         Ext.TabPanel.superclass.afterRender.call(this);
422         if(this.autoTabs){
423             this.readTabs(false);
424         }
425         if(this.activeTab !== undefined){
426             var item = Ext.isObject(this.activeTab) ? this.activeTab : this.items.get(this.activeTab);
427             delete this.activeTab;
428             this.setActiveTab(item);
429         }
430     },
431
432     // private
433     initEvents : function(){
434         Ext.TabPanel.superclass.initEvents.call(this);
435         this.mon(this.strip, {
436             scope: this,
437             mousedown: this.onStripMouseDown,
438             contextmenu: this.onStripContextMenu
439         });
440         if(this.enableTabScroll){
441             this.mon(this.strip, 'mousewheel', this.onWheel, this);
442         }
443     },
444
445     // private
446     findTargets : function(e){
447         var item = null;
448         var itemEl = e.getTarget('li', this.strip);
449         if(itemEl){
450             item = this.getComponent(itemEl.id.split(this.idDelimiter)[1]);
451             if(item.disabled){
452                 return {
453                     close : null,
454                     item : null,
455                     el : null
456                 };
457             }
458         }
459         return {
460             close : e.getTarget('.x-tab-strip-close', this.strip),
461             item : item,
462             el : itemEl
463         };
464     },
465
466     // private
467     onStripMouseDown : function(e){
468         if(e.button !== 0){
469             return;
470         }
471         e.preventDefault();
472         var t = this.findTargets(e);
473         if(t.close){
474             if (t.item.fireEvent('beforeclose', t.item) !== false) {
475                 t.item.fireEvent('close', t.item);
476                 delete t.item.tabEl;
477                 this.remove(t.item);
478             }
479             return;
480         }
481         if(t.item && t.item != this.activeTab){
482             this.setActiveTab(t.item);
483         }
484     },
485
486     // private
487     onStripContextMenu : function(e){
488         e.preventDefault();
489         var t = this.findTargets(e);
490         if(t.item){
491             this.fireEvent('contextmenu', this, t.item, e);
492         }
493     },
494
495     <div id="method-Ext.TabPanel-readTabs"></div>/**
496      * True to scan the markup in this tab panel for <tt>{@link #autoTabs}</tt> using the
497      * <tt>{@link #autoTabSelector}</tt>
498      * @param {Boolean} removeExisting True to remove existing tabs
499      */
500     readTabs : function(removeExisting){
501         if(removeExisting === true){
502             this.items.each(function(item){
503                 this.remove(item);
504             }, this);
505         }
506         var tabs = this.el.query(this.autoTabSelector);
507         for(var i = 0, len = tabs.length; i < len; i++){
508             var tab = tabs[i];
509             var title = tab.getAttribute('title');
510             tab.removeAttribute('title');
511             this.add({
512                 title: title,
513                 contentEl: tab
514             });
515         }
516     },
517
518     // private
519     initTab : function(item, index){
520         var before = this.strip.dom.childNodes[index];
521         var p = this.getTemplateArgs(item);
522         var el = before ?
523                  this.itemTpl.insertBefore(before, p) :
524                  this.itemTpl.append(this.strip, p);
525
526         Ext.fly(el).addClassOnOver('x-tab-strip-over');
527
528         if(item.tabTip){
529             Ext.fly(el).child('span.x-tab-strip-text', true).qtip = item.tabTip;
530         }
531         item.tabEl = el;
532
533         item.on('disable', this.onItemDisabled, this);
534         item.on('enable', this.onItemEnabled, this);
535         item.on('titlechange', this.onItemTitleChanged, this);
536         item.on('iconchange', this.onItemIconChanged, this);
537         item.on('beforeshow', this.onBeforeShowItem, this);
538     },
539
540     <div id="method-Ext.TabPanel-getTemplateArgs"></div>/**
541      * <p>Provides template arguments for rendering a tab selector item in the tab strip.</p>
542      * <p>This method returns an object hash containing properties used by the TabPanel's <tt>{@link #itemTpl}</tt>
543      * to create a formatted, clickable tab selector element. The properties which must be returned
544      * are:</p><div class="mdetail-params"><ul>
545      * <li><b>id</b> : String<div class="sub-desc">A unique identifier which links to the item</div></li>
546      * <li><b>text</b> : String<div class="sub-desc">The text to display</div></li>
547      * <li><b>cls</b> : String<div class="sub-desc">The CSS class name</div></li>
548      * <li><b>iconCls</b> : String<div class="sub-desc">A CSS class to provide appearance for an icon.</div></li>
549      * </ul></div>
550      * @param {BoxComponent} item The {@link Ext.BoxComponent BoxComponent} for which to create a selector element in the tab strip.
551      * @return {Object} An object hash containing the properties required to render the selector element.
552      */
553     getTemplateArgs : function(item) {
554         var cls = item.closable ? 'x-tab-strip-closable' : '';
555         if(item.disabled){
556             cls += ' x-item-disabled';
557         }
558         if(item.iconCls){
559             cls += ' x-tab-with-icon';
560         }
561         if(item.tabCls){
562             cls += ' ' + item.tabCls;
563         }
564
565         return {
566             id: this.id + this.idDelimiter + item.getItemId(),
567             text: item.title,
568             cls: cls,
569             iconCls: item.iconCls || ''
570         };
571     },
572
573     // private
574     onAdd : function(c){
575         Ext.TabPanel.superclass.onAdd.call(this, c);
576         if(this.rendered){
577             var items = this.items;
578             this.initTab(c, items.indexOf(c));
579             if(items.getCount() == 1){
580                 this.syncSize();
581             }
582             this.delegateUpdates();
583         }
584     },
585
586     // private
587     onBeforeAdd : function(item){
588         var existing = item.events ? (this.items.containsKey(item.getItemId()) ? item : null) : this.items.get(item);
589         if(existing){
590             this.setActiveTab(item);
591             return false;
592         }
593         Ext.TabPanel.superclass.onBeforeAdd.apply(this, arguments);
594         var es = item.elements;
595         item.elements = es ? es.replace(',header', '') : es;
596         item.border = (item.border === true);
597     },
598
599     // private
600     onRemove : function(c){
601         Ext.TabPanel.superclass.onRemove.call(this, c);
602         Ext.destroy(Ext.get(this.getTabEl(c)));
603         this.stack.remove(c);
604         c.un('disable', this.onItemDisabled, this);
605         c.un('enable', this.onItemEnabled, this);
606         c.un('titlechange', this.onItemTitleChanged, this);
607         c.un('iconchange', this.onItemIconChanged, this);
608         c.un('beforeshow', this.onBeforeShowItem, this);
609         if(c == this.activeTab){
610             var next = this.stack.next();
611             if(next){
612                 this.setActiveTab(next);
613             }else if(this.items.getCount() > 0){
614                 this.setActiveTab(0);
615             }else{
616                 this.activeTab = null;
617             }
618         }
619         this.delegateUpdates();
620     },
621
622     // private
623     onBeforeShowItem : function(item){
624         if(item != this.activeTab){
625             this.setActiveTab(item);
626             return false;
627         }
628     },
629
630     // private
631     onItemDisabled : function(item){
632         var el = this.getTabEl(item);
633         if(el){
634             Ext.fly(el).addClass('x-item-disabled');
635         }
636         this.stack.remove(item);
637     },
638
639     // private
640     onItemEnabled : function(item){
641         var el = this.getTabEl(item);
642         if(el){
643             Ext.fly(el).removeClass('x-item-disabled');
644         }
645     },
646
647     // private
648     onItemTitleChanged : function(item){
649         var el = this.getTabEl(item);
650         if(el){
651             Ext.fly(el).child('span.x-tab-strip-text', true).innerHTML = item.title;
652         }
653     },
654
655     //private
656     onItemIconChanged : function(item, iconCls, oldCls){
657         var el = this.getTabEl(item);
658         if(el){
659             el = Ext.get(el);
660             el.child('span.x-tab-strip-text').replaceClass(oldCls, iconCls);
661             el[Ext.isEmpty(iconCls) ? 'removeClass' : 'addClass']('x-tab-with-icon');
662         }
663     },
664
665     <div id="method-Ext.TabPanel-getTabEl"></div>/**
666      * Gets the DOM element for the tab strip item which activates the child panel with the specified
667      * ID. Access this to change the visual treatment of the item, for example by changing the CSS class name.
668      * @param {Panel/Number/String} tab The tab component, or the tab's index, or the tabs id or itemId.
669      * @return {HTMLElement} The DOM node
670      */
671     getTabEl : function(item){
672         return document.getElementById(this.id + this.idDelimiter + this.getComponent(item).getItemId());
673     },
674
675     // private
676     onResize : function(){
677         Ext.TabPanel.superclass.onResize.apply(this, arguments);
678         this.delegateUpdates();
679     },
680
681     <div id="method-Ext.TabPanel-beginUpdate"></div>/**
682      * Suspends any internal calculations or scrolling while doing a bulk operation. See {@link #endUpdate}
683      */
684     beginUpdate : function(){
685         this.suspendUpdates = true;
686     },
687
688     <div id="method-Ext.TabPanel-endUpdate"></div>/**
689      * Resumes calculations and scrolling at the end of a bulk operation. See {@link #beginUpdate}
690      */
691     endUpdate : function(){
692         this.suspendUpdates = false;
693         this.delegateUpdates();
694     },
695
696     <div id="method-Ext.TabPanel-hideTabStripItem"></div>/**
697      * Hides the tab strip item for the passed tab
698      * @param {Number/String/Panel} item The tab index, id or item
699      */
700     hideTabStripItem : function(item){
701         item = this.getComponent(item);
702         var el = this.getTabEl(item);
703         if(el){
704             el.style.display = 'none';
705             this.delegateUpdates();
706         }
707         this.stack.remove(item);
708     },
709
710     <div id="method-Ext.TabPanel-unhideTabStripItem"></div>/**
711      * Unhides the tab strip item for the passed tab
712      * @param {Number/String/Panel} item The tab index, id or item
713      */
714     unhideTabStripItem : function(item){
715         item = this.getComponent(item);
716         var el = this.getTabEl(item);
717         if(el){
718             el.style.display = '';
719             this.delegateUpdates();
720         }
721     },
722
723     // private
724     delegateUpdates : function(){
725         if(this.suspendUpdates){
726             return;
727         }
728         if(this.resizeTabs && this.rendered){
729             this.autoSizeTabs();
730         }
731         if(this.enableTabScroll && this.rendered){
732             this.autoScrollTabs();
733         }
734     },
735
736     // private
737     autoSizeTabs : function(){
738         var count = this.items.length;
739         var ce = this.tabPosition != 'bottom' ? 'header' : 'footer';
740         var ow = this[ce].dom.offsetWidth;
741         var aw = this[ce].dom.clientWidth;
742
743         if(!this.resizeTabs || count < 1 || !aw){ // !aw for display:none
744             return;
745         }
746
747         var each = Math.max(Math.min(Math.floor((aw-4) / count) - this.tabMargin, this.tabWidth), this.minTabWidth); // -4 for float errors in IE
748         this.lastTabWidth = each;
749         var lis = this.strip.query("li:not([className^=x-tab-edge])");
750         for(var i = 0, len = lis.length; i < len; i++) {
751             var li = lis[i];
752             var inner = Ext.fly(li).child('.x-tab-strip-inner', true);
753             var tw = li.offsetWidth;
754             var iw = inner.offsetWidth;
755             inner.style.width = (each - (tw-iw)) + 'px';
756         }
757     },
758
759     // private
760     adjustBodyWidth : function(w){
761         if(this.header){
762             this.header.setWidth(w);
763         }
764         if(this.footer){
765             this.footer.setWidth(w);
766         }
767         return w;
768     },
769
770     <div id="method-Ext.TabPanel-setActiveTab"></div>/**
771      * Sets the specified tab as the active tab. This method fires the {@link #beforetabchange} event which
772      * can <tt>return false</tt> to cancel the tab change.
773      * @param {String/Number} item
774      * The id or tab Panel to activate. This parameter may be any of the following:
775      * <div><ul class="mdetail-params">
776      * <li>a <b><tt>String</tt></b> : representing the <code>{@link Ext.Component#itemId itemId}</code>
777      * or <code>{@link Ext.Component#id id}</code> of the child component </li>
778      * <li>a <b><tt>Number</tt></b> : representing the position of the child component
779      * within the <code>{@link Ext.Container#items items}</code> <b>property</b></li>
780      * </ul></div>
781      * <p>For additional information see {@link Ext.util.MixedCollection#get}.
782      */
783     setActiveTab : function(item){
784         item = this.getComponent(item);
785         if(!item || this.fireEvent('beforetabchange', this, item, this.activeTab) === false){
786             return;
787         }
788         if(!this.rendered){
789             this.activeTab = item;
790             return;
791         }
792         if(this.activeTab != item){
793             if(this.activeTab){
794                 var oldEl = this.getTabEl(this.activeTab);
795                 if(oldEl){
796                     Ext.fly(oldEl).removeClass('x-tab-strip-active');
797                 }
798                 this.activeTab.fireEvent('deactivate', this.activeTab);
799             }
800             var el = this.getTabEl(item);
801             Ext.fly(el).addClass('x-tab-strip-active');
802             this.activeTab = item;
803             this.stack.add(item);
804
805             this.layout.setActiveItem(item);
806             if(this.scrolling){
807                 this.scrollToTab(item, this.animScroll);
808             }
809
810             item.fireEvent('activate', item);
811             this.fireEvent('tabchange', this, item);
812         }
813     },
814
815     <div id="method-Ext.TabPanel-getActiveTab"></div>/**
816      * Gets the currently active tab.
817      * @return {Panel} The active tab
818      */
819     getActiveTab : function(){
820         return this.activeTab || null;
821     },
822
823     <div id="method-Ext.TabPanel-getItem"></div>/**
824      * Gets the specified tab by id.
825      * @param {String} id The tab id
826      * @return {Panel} The tab
827      */
828     getItem : function(item){
829         return this.getComponent(item);
830     },
831
832     // private
833     autoScrollTabs : function(){
834         this.pos = this.tabPosition=='bottom' ? this.footer : this.header;
835         var count = this.items.length;
836         var ow = this.pos.dom.offsetWidth;
837         var tw = this.pos.dom.clientWidth;
838
839         var wrap = this.stripWrap;
840         var wd = wrap.dom;
841         var cw = wd.offsetWidth;
842         var pos = this.getScrollPos();
843         var l = this.edge.getOffsetsTo(this.stripWrap)[0] + pos;
844
845         if(!this.enableTabScroll || count < 1 || cw < 20){ // 20 to prevent display:none issues
846             return;
847         }
848         if(l <= tw){
849             wd.scrollLeft = 0;
850             wrap.setWidth(tw);
851             if(this.scrolling){
852                 this.scrolling = false;
853                 this.pos.removeClass('x-tab-scrolling');
854                 this.scrollLeft.hide();
855                 this.scrollRight.hide();
856                 // See here: http://extjs.com/forum/showthread.php?t=49308&highlight=isSafari
857                 if(Ext.isAir || Ext.isWebKit){
858                     wd.style.marginLeft = '';
859                     wd.style.marginRight = '';
860                 }
861             }
862         }else{
863             if(!this.scrolling){
864                 this.pos.addClass('x-tab-scrolling');
865                 // See here: http://extjs.com/forum/showthread.php?t=49308&highlight=isSafari
866                 if(Ext.isAir || Ext.isWebKit){
867                     wd.style.marginLeft = '18px';
868                     wd.style.marginRight = '18px';
869                 }
870             }
871             tw -= wrap.getMargins('lr');
872             wrap.setWidth(tw > 20 ? tw : 20);
873             if(!this.scrolling){
874                 if(!this.scrollLeft){
875                     this.createScrollers();
876                 }else{
877                     this.scrollLeft.show();
878                     this.scrollRight.show();
879                 }
880             }
881             this.scrolling = true;
882             if(pos > (l-tw)){ // ensure it stays within bounds
883                 wd.scrollLeft = l-tw;
884             }else{ // otherwise, make sure the active tab is still visible
885                 this.scrollToTab(this.activeTab, false);
886             }
887             this.updateScrollButtons();
888         }
889     },
890
891     // private
892     createScrollers : function(){
893         this.pos.addClass('x-tab-scrolling-' + this.tabPosition);
894         var h = this.stripWrap.dom.offsetHeight;
895
896         // left
897         var sl = this.pos.insertFirst({
898             cls:'x-tab-scroller-left'
899         });
900         sl.setHeight(h);
901         sl.addClassOnOver('x-tab-scroller-left-over');
902         this.leftRepeater = new Ext.util.ClickRepeater(sl, {
903             interval : this.scrollRepeatInterval,
904             handler: this.onScrollLeft,
905             scope: this
906         });
907         this.scrollLeft = sl;
908
909         // right
910         var sr = this.pos.insertFirst({
911             cls:'x-tab-scroller-right'
912         });
913         sr.setHeight(h);
914         sr.addClassOnOver('x-tab-scroller-right-over');
915         this.rightRepeater = new Ext.util.ClickRepeater(sr, {
916             interval : this.scrollRepeatInterval,
917             handler: this.onScrollRight,
918             scope: this
919         });
920         this.scrollRight = sr;
921     },
922
923     // private
924     getScrollWidth : function(){
925         return this.edge.getOffsetsTo(this.stripWrap)[0] + this.getScrollPos();
926     },
927
928     // private
929     getScrollPos : function(){
930         return parseInt(this.stripWrap.dom.scrollLeft, 10) || 0;
931     },
932
933     // private
934     getScrollArea : function(){
935         return parseInt(this.stripWrap.dom.clientWidth, 10) || 0;
936     },
937
938     // private
939     getScrollAnim : function(){
940         return {duration:this.scrollDuration, callback: this.updateScrollButtons, scope: this};
941     },
942
943     // private
944     getScrollIncrement : function(){
945         return this.scrollIncrement || (this.resizeTabs ? this.lastTabWidth+2 : 100);
946     },
947
948     <div id="method-Ext.TabPanel-scrollToTab"></div>/**
949      * Scrolls to a particular tab if tab scrolling is enabled
950      * @param {Panel} item The item to scroll to
951      * @param {Boolean} animate True to enable animations
952      */
953
954     scrollToTab : function(item, animate){
955         if(!item){ return; }
956         var el = this.getTabEl(item);
957         var pos = this.getScrollPos(), area = this.getScrollArea();
958         var left = Ext.fly(el).getOffsetsTo(this.stripWrap)[0] + pos;
959         var right = left + el.offsetWidth;
960         if(left < pos){
961             this.scrollTo(left, animate);
962         }else if(right > (pos + area)){
963             this.scrollTo(right - area, animate);
964         }
965     },
966
967     // private
968     scrollTo : function(pos, animate){
969         this.stripWrap.scrollTo('left', pos, animate ? this.getScrollAnim() : false);
970         if(!animate){
971             this.updateScrollButtons();
972         }
973     },
974
975     onWheel : function(e){
976         var d = e.getWheelDelta()*this.wheelIncrement*-1;
977         e.stopEvent();
978
979         var pos = this.getScrollPos();
980         var newpos = pos + d;
981         var sw = this.getScrollWidth()-this.getScrollArea();
982
983         var s = Math.max(0, Math.min(sw, newpos));
984         if(s != pos){
985             this.scrollTo(s, false);
986         }
987     },
988
989     // private
990     onScrollRight : function(){
991         var sw = this.getScrollWidth()-this.getScrollArea();
992         var pos = this.getScrollPos();
993         var s = Math.min(sw, pos + this.getScrollIncrement());
994         if(s != pos){
995             this.scrollTo(s, this.animScroll);
996         }
997     },
998
999     // private
1000     onScrollLeft : function(){
1001         var pos = this.getScrollPos();
1002         var s = Math.max(0, pos - this.getScrollIncrement());
1003         if(s != pos){
1004             this.scrollTo(s, this.animScroll);
1005         }
1006     },
1007
1008     // private
1009     updateScrollButtons : function(){
1010         var pos = this.getScrollPos();
1011         this.scrollLeft[pos === 0 ? 'addClass' : 'removeClass']('x-tab-scroller-left-disabled');
1012         this.scrollRight[pos >= (this.getScrollWidth()-this.getScrollArea()) ? 'addClass' : 'removeClass']('x-tab-scroller-right-disabled');
1013     },
1014
1015     // private
1016     beforeDestroy : function() {
1017         if(this.items){
1018             this.items.each(function(item){
1019                 if(item && item.tabEl){
1020                     Ext.get(item.tabEl).removeAllListeners();
1021                     item.tabEl = null;
1022                 }
1023             }, this);
1024         }
1025         if(this.strip){
1026             this.strip.removeAllListeners();
1027         }
1028         Ext.TabPanel.superclass.beforeDestroy.apply(this);
1029     }
1030
1031     <div id="cfg-Ext.TabPanel-collapsible"></div>/**
1032      * @cfg {Boolean} collapsible
1033      * @hide
1034      */
1035     <div id="cfg-Ext.TabPanel-header"></div>/**
1036      * @cfg {String} header
1037      * @hide
1038      */
1039     <div id="cfg-Ext.TabPanel-headerAsText"></div>/**
1040      * @cfg {Boolean} headerAsText
1041      * @hide
1042      */
1043     <div id="prop-Ext.TabPanel-header"></div>/**
1044      * @property header
1045      * @hide
1046      */
1047     <div id="cfg-Ext.TabPanel-null"></div>/**
1048      * @cfg title
1049      * @hide
1050      */
1051     <div id="cfg-Ext.TabPanel-tools"></div>/**
1052      * @cfg {Array} tools
1053      * @hide
1054      */
1055     <div id="cfg-Ext.TabPanel-toolTemplate"></div>/**
1056      * @cfg {Array} toolTemplate
1057      * @hide
1058      */
1059     <div id="cfg-Ext.TabPanel-hideCollapseTool"></div>/**
1060      * @cfg {Boolean} hideCollapseTool
1061      * @hide
1062      */
1063     <div id="cfg-Ext.TabPanel-titleCollapse"></div>/**
1064      * @cfg {Boolean} titleCollapse
1065      * @hide
1066      */
1067     <div id="cfg-Ext.TabPanel-collapsed"></div>/**
1068      * @cfg {Boolean} collapsed
1069      * @hide
1070      */
1071     <div id="cfg-Ext.TabPanel-layout"></div>/**
1072      * @cfg {String} layout
1073      * @hide
1074      */
1075     <div id="cfg-Ext.TabPanel-preventBodyReset"></div>/**
1076      * @cfg {Boolean} preventBodyReset
1077      * @hide
1078      */
1079 });
1080 Ext.reg('tabpanel', Ext.TabPanel);
1081
1082 <div id="method-Ext.TabPanel-activate"></div>/**
1083  * See {@link #setActiveTab}. Sets the specified tab as the active tab. This method fires
1084  * the {@link #beforetabchange} event which can <tt>return false</tt> to cancel the tab change.
1085  * @param {String/Panel} tab The id or tab Panel to activate
1086  * @method activate
1087  */
1088 Ext.TabPanel.prototype.activate = Ext.TabPanel.prototype.setActiveTab;
1089
1090 // private utility class used by TabPanel
1091 Ext.TabPanel.AccessStack = function(){
1092     var items = [];
1093     return {
1094         add : function(item){
1095             items.push(item);
1096             if(items.length > 10){
1097                 items.shift();
1098             }
1099         },
1100
1101         remove : function(item){
1102             var s = [];
1103             for(var i = 0, len = items.length; i < len; i++) {
1104                 if(items[i] != item){
1105                     s.push(items[i]);
1106                 }
1107             }
1108             items = s;
1109         },
1110
1111         next : function(){
1112             return items.pop();
1113         }
1114     };
1115 };
1116 </pre>
1117 </body>
1118 </html>