Upgrade to ExtJS 3.2.1 - Released 04/27/2010
[extjs.git] / docs / source / ToolbarLayout.html
1 <html>
2 <head>
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
4   <title>The source code</title>
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
7 </head>
8 <body  onload="prettyPrint();">
9     <pre class="prettyprint lang-js">/*!
10  * Ext JS Library 3.2.1
11  * Copyright(c) 2006-2010 Ext JS, Inc.
12  * licensing@extjs.com
13  * http://www.extjs.com/license
14  */
15 <div id="cls-Ext.layout.ToolbarLayout"></div>/**
16  * @class Ext.layout.ToolbarLayout
17  * @extends Ext.layout.ContainerLayout
18  * Layout manager used by Ext.Toolbar. This is highly specialised for use by Toolbars and would not
19  * usually be used by any other class.
20  */
21 Ext.layout.ToolbarLayout = Ext.extend(Ext.layout.ContainerLayout, {
22     monitorResize : true,
23
24     type: 'toolbar',
25
26     <div id="prop-Ext.layout.ToolbarLayout-triggerWidth"></div>/**
27      * @property triggerWidth
28      * @type Number
29      * The width allocated for the menu trigger at the extreme right end of the Toolbar
30      */
31     triggerWidth: 18,
32
33     <div id="prop-Ext.layout.ToolbarLayout-noItemsMenuText"></div>/**
34      * @property noItemsMenuText
35      * @type String
36      * HTML fragment to render into the toolbar overflow menu if there are no items to display
37      */
38     noItemsMenuText : '<div class="x-toolbar-no-items">(None)</div>',
39
40     /**
41      * @private
42      * @property lastOverflow
43      * @type Boolean
44      * Used internally to record whether the last layout caused an overflow or not
45      */
46     lastOverflow: false,
47
48     /**
49      * @private
50      * @property tableHTML
51      * @type String
52      * String used to build the HTML injected to support the Toolbar's layout. The align property is
53      * injected into this string inside the td.x-toolbar-left element during onLayout.
54      */
55     tableHTML: [
56         '<table cellspacing="0" class="x-toolbar-ct">',
57             '<tbody>',
58                 '<tr>',
59                     '<td class="x-toolbar-left" align="{0}">',
60                         '<table cellspacing="0">',
61                             '<tbody>',
62                                 '<tr class="x-toolbar-left-row"></tr>',
63                             '</tbody>',
64                         '</table>',
65                     '</td>',
66                     '<td class="x-toolbar-right" align="right">',
67                         '<table cellspacing="0" class="x-toolbar-right-ct">',
68                             '<tbody>',
69                                 '<tr>',
70                                     '<td>',
71                                         '<table cellspacing="0">',
72                                             '<tbody>',
73                                                 '<tr class="x-toolbar-right-row"></tr>',
74                                             '</tbody>',
75                                         '</table>',
76                                     '</td>',
77                                     '<td>',
78                                         '<table cellspacing="0">',
79                                             '<tbody>',
80                                                 '<tr class="x-toolbar-extras-row"></tr>',
81                                             '</tbody>',
82                                         '</table>',
83                                     '</td>',
84                                 '</tr>',
85                             '</tbody>',
86                         '</table>',
87                     '</td>',
88                 '</tr>',
89             '</tbody>',
90         '</table>'
91     ].join(""),
92
93     /**
94      * @private
95      * Create the wrapping Toolbar HTML and render/move all the items into the correct places
96      */
97     onLayout : function(ct, target) {
98         //render the Toolbar <table> HTML if it's not already present
99         if (!this.leftTr) {
100             var align = ct.buttonAlign == 'center' ? 'center' : 'left';
101
102             target.addClass('x-toolbar-layout-ct');
103             target.insertHtml('beforeEnd', String.format(this.tableHTML, align));
104
105             this.leftTr   = target.child('tr.x-toolbar-left-row', true);
106             this.rightTr  = target.child('tr.x-toolbar-right-row', true);
107             this.extrasTr = target.child('tr.x-toolbar-extras-row', true);
108
109             if (this.hiddenItem == undefined) {
110                 <div id="prop-Ext.layout.ToolbarLayout-hiddenItems"></div>/**
111                  * @property hiddenItems
112                  * @type Array
113                  * Holds all items that are currently hidden due to there not being enough space to render them
114                  * These items will appear on the expand menu.
115                  */
116                 this.hiddenItems = [];
117             }
118         }
119
120         var side     = ct.buttonAlign == 'right' ? this.rightTr : this.leftTr,
121             items    = ct.items.items,
122             position = 0;
123
124         //render each item if not already rendered, place it into the correct (left or right) target
125         for (var i = 0, len = items.length, c; i < len; i++, position++) {
126             c = items[i];
127
128             if (c.isFill) {
129                 side   = this.rightTr;
130                 position = -1;
131             } else if (!c.rendered) {
132                 c.render(this.insertCell(c, side, position));
133             } else {
134                 if (!c.xtbHidden && !this.isValidParent(c, side.childNodes[position])) {
135                     var td = this.insertCell(c, side, position);
136                     td.appendChild(c.getPositionEl().dom);
137                     c.container = Ext.get(td);
138                 }
139             }
140         }
141
142         //strip extra empty cells
143         this.cleanup(this.leftTr);
144         this.cleanup(this.rightTr);
145         this.cleanup(this.extrasTr);
146         this.fitToSize(target);
147     },
148
149     /**
150      * @private
151      * Removes any empty nodes from the given element
152      * @param {Ext.Element} el The element to clean up
153      */
154     cleanup : function(el) {
155         var cn = el.childNodes, i, c;
156
157         for (i = cn.length-1; i >= 0 && (c = cn[i]); i--) {
158             if (!c.firstChild) {
159                 el.removeChild(c);
160             }
161         }
162     },
163
164     /**
165      * @private
166      * Inserts the given Toolbar item into the given element
167      * @param {Ext.Component} c The component to add
168      * @param {Ext.Element} target The target to add the component to
169      * @param {Number} position The position to add the component at
170      */
171     insertCell : function(c, target, position) {
172         var td = document.createElement('td');
173         td.className = 'x-toolbar-cell';
174
175         target.insertBefore(td, target.childNodes[position] || null);
176
177         return td;
178     },
179
180     /**
181      * @private
182      * Hides an item because it will not fit in the available width. The item will be unhidden again
183      * if the Toolbar is resized to be large enough to show it
184      * @param {Ext.Component} item The item to hide
185      */
186     hideItem : function(item) {
187         this.hiddenItems.push(item);
188
189         item.xtbHidden = true;
190         item.xtbWidth = item.getPositionEl().dom.parentNode.offsetWidth;
191         item.hide();
192     },
193
194     /**
195      * @private
196      * Unhides an item that was previously hidden due to there not being enough space left on the Toolbar
197      * @param {Ext.Component} item The item to show
198      */
199     unhideItem : function(item) {
200         item.show();
201         item.xtbHidden = false;
202         this.hiddenItems.remove(item);
203     },
204
205     /**
206      * @private
207      * Returns the width of the given toolbar item. If the item is currently hidden because there
208      * is not enough room to render it, its previous width is returned
209      * @param {Ext.Component} c The component to measure
210      * @return {Number} The width of the item
211      */
212     getItemWidth : function(c) {
213         return c.hidden ? (c.xtbWidth || 0) : c.getPositionEl().dom.parentNode.offsetWidth;
214     },
215
216     /**
217      * @private
218      * Called at the end of onLayout. At this point the Toolbar has already been resized, so we need
219      * to fit the items into the available width. We add up the width required by all of the items in
220      * the toolbar - if we don't have enough space we hide the extra items and render the expand menu
221      * trigger.
222      * @param {Ext.Element} target The Element the Toolbar is currently laid out within
223      */
224     fitToSize : function(target) {
225         if (this.container.enableOverflow === false) {
226             return;
227         }
228
229         var width       = target.dom.clientWidth,
230             tableWidth  = target.dom.firstChild.offsetWidth,
231             clipWidth   = width - this.triggerWidth,
232             lastWidth   = this.lastWidth || 0,
233
234             hiddenItems = this.hiddenItems,
235             hasHiddens  = hiddenItems.length != 0,
236             isLarger    = width >= lastWidth;
237
238         this.lastWidth  = width;
239
240         if (tableWidth > width || (hasHiddens && isLarger)) {
241             var items     = this.container.items.items,
242                 len       = items.length,
243                 loopWidth = 0,
244                 item;
245
246             for (var i = 0; i < len; i++) {
247                 item = items[i];
248
249                 if (!item.isFill) {
250                     loopWidth += this.getItemWidth(item);
251                     if (loopWidth > clipWidth) {
252                         if (!(item.hidden || item.xtbHidden)) {
253                             this.hideItem(item);
254                         }
255                     } else if (item.xtbHidden) {
256                         this.unhideItem(item);
257                     }
258                 }
259             }
260         }
261
262         //test for number of hidden items again here because they may have changed above
263         hasHiddens = hiddenItems.length != 0;
264
265         if (hasHiddens) {
266             this.initMore();
267
268             if (!this.lastOverflow) {
269                 this.container.fireEvent('overflowchange', this.container, true);
270                 this.lastOverflow = true;
271             }
272         } else if (this.more) {
273             this.clearMenu();
274             this.more.destroy();
275             delete this.more;
276
277             if (this.lastOverflow) {
278                 this.container.fireEvent('overflowchange', this.container, false);
279                 this.lastOverflow = false;
280             }
281         }
282     },
283
284     /**
285      * @private
286      * Returns a menu config for a given component. This config is used to create a menu item
287      * to be added to the expander menu
288      * @param {Ext.Component} component The component to create the config for
289      * @param {Boolean} hideOnClick Passed through to the menu item
290      */
291     createMenuConfig : function(component, hideOnClick){
292         var config = Ext.apply({}, component.initialConfig),
293             group  = component.toggleGroup;
294
295         Ext.copyTo(config, component, [
296             'iconCls', 'icon', 'itemId', 'disabled', 'handler', 'scope', 'menu'
297         ]);
298
299         Ext.apply(config, {
300             text       : component.overflowText || component.text,
301             hideOnClick: hideOnClick
302         });
303
304         if (group || component.enableToggle) {
305             Ext.apply(config, {
306                 group  : group,
307                 checked: component.pressed,
308                 listeners: {
309                     checkchange: function(item, checked){
310                         component.toggle(checked);
311                     }
312                 }
313             });
314         }
315
316         delete config.ownerCt;
317         delete config.xtype;
318         delete config.id;
319
320         return config;
321     },
322
323     /**
324      * @private
325      * Adds the given Toolbar item to the given menu. Buttons inside a buttongroup are added individually.
326      * @param {Ext.menu.Menu} menu The menu to add to
327      * @param {Ext.Component} component The component to add
328      */
329     addComponentToMenu : function(menu, component) {
330         if (component instanceof Ext.Toolbar.Separator) {
331             menu.add('-');
332
333         } else if (Ext.isFunction(component.isXType)) {
334             if (component.isXType('splitbutton')) {
335                 menu.add(this.createMenuConfig(component, true));
336
337             } else if (component.isXType('button')) {
338                 menu.add(this.createMenuConfig(component, !component.menu));
339
340             } else if (component.isXType('buttongroup')) {
341                 component.items.each(function(item){
342                      this.addComponentToMenu(menu, item);
343                 }, this);
344             }
345         }
346     },
347
348     /**
349      * @private
350      * Deletes the sub-menu of each item in the expander menu. Submenus are created for items such as
351      * splitbuttons and buttongroups, where the Toolbar item cannot be represented by a single menu item
352      */
353     clearMenu : function(){
354         var menu = this.moreMenu;
355         if (menu && menu.items) {
356             menu.items.each(function(item){
357                 delete item.menu;
358             });
359         }
360     },
361
362     /**
363      * @private
364      * Called before the expand menu is shown, this rebuilds the menu since it was last shown because
365      * it is possible that the items hidden due to space limitations on the Toolbar have changed since.
366      * @param {Ext.menu.Menu} m The menu
367      */
368     beforeMoreShow : function(menu) {
369         var items = this.container.items.items,
370             len   = items.length,
371             item,
372             prev;
373
374         var needsSep = function(group, item){
375             return group.isXType('buttongroup') && !(item instanceof Ext.Toolbar.Separator);
376         };
377
378         this.clearMenu();
379         menu.removeAll();
380         for (var i = 0; i < len; i++) {
381             item = items[i];
382             if (item.xtbHidden) {
383                 if (prev && (needsSep(item, prev) || needsSep(prev, item))) {
384                     menu.add('-');
385                 }
386                 this.addComponentToMenu(menu, item);
387                 prev = item;
388             }
389         }
390
391         // put something so the menu isn't empty if no compatible items found
392         if (menu.items.length < 1) {
393             menu.add(this.noItemsMenuText);
394         }
395     },
396
397     /**
398      * @private
399      * Creates the expand trigger and menu, adding them to the <tr> at the extreme right of the
400      * Toolbar table
401      */
402     initMore : function(){
403         if (!this.more) {
404             /**
405              * @private
406              * @property moreMenu
407              * @type Ext.menu.Menu
408              * The expand menu - holds items for every Toolbar item that cannot be shown
409              * because the Toolbar is currently not wide enough.
410              */
411             this.moreMenu = new Ext.menu.Menu({
412                 ownerCt : this.container,
413                 listeners: {
414                     beforeshow: this.beforeMoreShow,
415                     scope: this
416                 }
417             });
418
419             /**
420              * @private
421              * @property more
422              * @type Ext.Button
423              * The expand button which triggers the overflow menu to be shown
424              */
425             this.more = new Ext.Button({
426                 iconCls: 'x-toolbar-more-icon',
427                 cls    : 'x-toolbar-more',
428                 menu   : this.moreMenu,
429                 ownerCt: this.container
430             });
431
432             var td = this.insertCell(this.more, this.extrasTr, 100);
433             this.more.render(td);
434         }
435     },
436
437     destroy : function(){
438         Ext.destroy(this.more, this.moreMenu);
439         delete this.leftTr;
440         delete this.rightTr;
441         delete this.extrasTr;
442         Ext.layout.ToolbarLayout.superclass.destroy.call(this);
443     }
444 });
445
446 Ext.Container.LAYOUTS.toolbar = Ext.layout.ToolbarLayout;
447 </pre>    
448 </body>
449 </html>