Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / Toolbar.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-toolbar-Toolbar-method-constructor'><span id='Ext-toolbar-Toolbar'>/**
19 </span></span> * @class Ext.toolbar.Toolbar
20  * @extends Ext.container.Container
21
22 Basic Toolbar class. Although the {@link Ext.container.Container#defaultType defaultType} for Toolbar is {@link Ext.button.Button button}, Toolbar 
23 elements (child items for the Toolbar container) may be virtually any type of Component. Toolbar elements can be created explicitly via their 
24 constructors, or implicitly via their xtypes, and can be {@link #add}ed dynamically.
25
26 __Some items have shortcut strings for creation:__
27
28 | Shortcut | xtype         | Class                         | Description                                        |
29 |:---------|:--------------|:------------------------------|:---------------------------------------------------|
30 | `-&gt;`     | `tbspacer`    | {@link Ext.toolbar.Fill}      | begin using the right-justified button container   |
31 | `-`      | `tbseparator` | {@link Ext.toolbar.Separator} | add a vertical separator bar between toolbar items |
32 | ` `      | `tbspacer`    | {@link Ext.toolbar.Spacer}    | add horiztonal space between elements              |
33
34 {@img Ext.toolbar.Toolbar/Ext.toolbar.Toolbar1.png Toolbar component}
35 Example usage:
36
37     Ext.create('Ext.toolbar.Toolbar', {
38         renderTo: document.body,
39         width   : 500,
40         items: [
41             {
42                 // xtype: 'button', // default for Toolbars
43                 text: 'Button'
44             },
45             {
46                 xtype: 'splitbutton',
47                 text : 'Split Button'
48             },
49             // begin using the right-justified button container
50             '-&gt;', // same as {xtype: 'tbfill'}, // Ext.toolbar.Fill
51             {
52                 xtype    : 'textfield',
53                 name     : 'field1',
54                 emptyText: 'enter search term'
55             },
56             // add a vertical separator bar between toolbar items
57             '-', // same as {xtype: 'tbseparator'} to create Ext.toolbar.Separator
58             'text 1', // same as {xtype: 'tbtext', text: 'text1'} to create Ext.toolbar.TextItem
59             {xtype: 'tbspacer'},// same as ' ' to create Ext.toolbar.Spacer
60             'text 2',
61             {xtype: 'tbspacer', width: 50}, // add a 50px space
62             'text 3'
63         ]
64     });
65
66 Toolbars have {@link #enable} and {@link #disable} methods which when called, will enable/disable all items within your toolbar.
67
68 {@img Ext.toolbar.Toolbar/Ext.toolbar.Toolbar2.png Toolbar component}
69 Example usage:
70
71     Ext.create('Ext.toolbar.Toolbar', {
72         renderTo: document.body,
73         width   : 400,
74         items: [
75             {
76                 text: 'Button'
77             },
78             {
79                 xtype: 'splitbutton',
80                 text : 'Split Button'
81             },
82             '-&gt;',
83             {
84                 xtype    : 'textfield',
85                 name     : 'field1',
86                 emptyText: 'enter search term'
87             }
88         ]
89     });
90
91 {@img Ext.toolbar.Toolbar/Ext.toolbar.Toolbar3.png Toolbar component}
92 Example usage:
93     
94     var enableBtn = Ext.create('Ext.button.Button', {
95         text    : 'Enable All Items',
96         disabled: true,
97         scope   : this,
98         handler : function() {
99             //disable the enable button and enable the disable button
100             enableBtn.disable();
101             disableBtn.enable();
102             
103             //enable the toolbar
104             toolbar.enable();
105         }
106     });
107     
108     var disableBtn = Ext.create('Ext.button.Button', {
109         text    : 'Disable All Items',
110         scope   : this,
111         handler : function() {
112             //enable the enable button and disable button
113             disableBtn.disable();
114             enableBtn.enable();
115             
116             //disable the toolbar
117             toolbar.disable();
118         }
119     });
120     
121     var toolbar = Ext.create('Ext.toolbar.Toolbar', {
122         renderTo: document.body,
123         width   : 400,
124         margin  : '5 0 0 0',
125         items   : [enableBtn, disableBtn]
126     });
127
128 Adding items to and removing items from a toolbar is as simple as calling the {@link #add} and {@link #remove} methods. There is also a {@link #removeAll} method 
129 which remove all items within the toolbar.
130
131 {@img Ext.toolbar.Toolbar/Ext.toolbar.Toolbar4.png Toolbar component}
132 Example usage:
133
134     var toolbar = Ext.create('Ext.toolbar.Toolbar', {
135         renderTo: document.body,
136         width   : 700,
137         items: [
138             {
139                 text: 'Example Button'
140             }
141         ]
142     });
143     
144     var addedItems = [];
145     
146     Ext.create('Ext.toolbar.Toolbar', {
147         renderTo: document.body,
148         width   : 700,
149         margin  : '5 0 0 0',
150         items   : [
151             {
152                 text   : 'Add a button',
153                 scope  : this,
154                 handler: function() {
155                     var text = prompt('Please enter the text for your button:');
156                     addedItems.push(toolbar.add({
157                         text: text
158                     }));
159                 }
160             },
161             {
162                 text   : 'Add a text item',
163                 scope  : this,
164                 handler: function() {
165                     var text = prompt('Please enter the text for your item:');
166                     addedItems.push(toolbar.add(text));
167                 }
168             },
169             {
170                 text   : 'Add a toolbar seperator',
171                 scope  : this,
172                 handler: function() {
173                     addedItems.push(toolbar.add('-'));
174                 }
175             },
176             {
177                 text   : 'Add a toolbar spacer',
178                 scope  : this,
179                 handler: function() {
180                     addedItems.push(toolbar.add('-&gt;'));
181                 }
182             },
183             '-&gt;',
184             {
185                 text   : 'Remove last inserted item',
186                 scope  : this,
187                 handler: function() {
188                     if (addedItems.length) {
189                         toolbar.remove(addedItems.pop());
190                     } else if (toolbar.items.length) {
191                         toolbar.remove(toolbar.items.last());
192                     } else {
193                         alert('No items in the toolbar');
194                     }
195                 }
196             },
197             {
198                 text   : 'Remove all items',
199                 scope  : this,
200                 handler: function() {
201                     toolbar.removeAll();
202                 }
203             }
204         ]
205     });
206
207  * @constructor
208  * Creates a new Toolbar
209  * @param {Object/Array} config A config object or an array of buttons to &lt;code&gt;{@link #add}&lt;/code&gt;
210  * @docauthor Robert Dougan &lt;rob@sencha.com&gt;
211  * @markdown
212  */
213 Ext.define('Ext.toolbar.Toolbar', {
214     extend: 'Ext.container.Container',
215     requires: [
216         'Ext.toolbar.Fill',
217         'Ext.layout.container.HBox',
218         'Ext.layout.container.VBox',
219         'Ext.FocusManager'
220     ],
221     uses: [
222         'Ext.toolbar.Separator'
223     ],
224     alias: 'widget.toolbar',
225     alternateClassName: 'Ext.Toolbar',
226     
227     isToolbar: true,
228     baseCls  : Ext.baseCSSPrefix + 'toolbar',
229     ariaRole : 'toolbar',
230     
231     defaultType: 'button',
232     
233 <span id='Ext-toolbar-Toolbar-cfg-vertical'>    /**
234 </span>     * @cfg {Boolean} vertical
235      * Set to `true` to make the toolbar vertical. The layout will become a `vbox`.
236      * (defaults to `false`)
237      */
238     vertical: false,
239
240 <span id='Ext-toolbar-Toolbar-cfg-layout'>    /**
241 </span>     * @cfg {String/Object} layout
242      * This class assigns a default layout (&lt;code&gt;layout:'&lt;b&gt;hbox&lt;/b&gt;'&lt;/code&gt;).
243      * Developers &lt;i&gt;may&lt;/i&gt; override this configuration option if another layout
244      * is required (the constructor must be passed a configuration object in this
245      * case instead of an array).
246      * See {@link Ext.container.Container#layout} for additional information.
247      */
248
249 <span id='Ext-toolbar-Toolbar-cfg-enableOverflow'>    /**
250 </span>     * @cfg {Boolean} enableOverflow
251      * Defaults to false. Configure &lt;code&gt;true&lt;/code&gt; to make the toolbar provide a button
252      * which activates a dropdown Menu to show items which overflow the Toolbar's width.
253      */
254     enableOverflow: false,
255     
256     // private
257     trackMenus: true,
258     
259     itemCls: Ext.baseCSSPrefix + 'toolbar-item',
260     
261     initComponent: function() {
262         var me = this,
263             keys;
264
265         // check for simplified (old-style) overflow config:
266         if (!me.layout &amp;&amp; me.enableOverflow) {
267             me.layout = { overflowHandler: 'Menu' };
268         }
269         
270         if (me.dock === 'right' || me.dock === 'left') {
271             me.vertical = true;
272         }
273
274         me.layout = Ext.applyIf(Ext.isString(me.layout) ? {
275             type: me.layout
276         } : me.layout || {}, {
277             type: me.vertical ? 'vbox' : 'hbox',
278             align: me.vertical ? 'stretchmax' : 'middle',
279             clearInnerCtOnLayout: true
280         });
281         
282         if (me.vertical) {
283             me.addClsWithUI('vertical');
284         }
285         
286         // @TODO: remove this hack and implement a more general solution
287         if (me.ui === 'footer') {
288             me.ignoreBorderManagement = true;
289         }
290         
291         me.callParent();
292
293 <span id='Ext-toolbar-Toolbar-event-overflowchange'>        /**
294 </span>         * @event overflowchange
295          * Fires after the overflow state has changed.
296          * @param {Object} c The Container
297          * @param {Boolean} lastOverflow overflow state
298          */
299         me.addEvents('overflowchange');
300         
301         // Subscribe to Ext.FocusManager for key navigation
302         keys = me.vertical ? ['up', 'down'] : ['left', 'right'];
303         Ext.FocusManager.subscribe(me, {
304             keys: keys
305         });
306     },
307
308 <span id='Ext-toolbar-Toolbar-method-add'>    /**
309 </span>     * &lt;p&gt;Adds element(s) to the toolbar -- this function takes a variable number of
310      * arguments of mixed type and adds them to the toolbar.&lt;/p&gt;
311      * &lt;br&gt;&lt;p&gt;&lt;b&gt;Note&lt;/b&gt;: See the notes within {@link Ext.container.Container#add}.&lt;/p&gt;
312      * @param {Mixed} arg1 The following types of arguments are all valid:&lt;br /&gt;
313      * &lt;ul&gt;
314      * &lt;li&gt;{@link Ext.button.Button} config: A valid button config object (equivalent to {@link #addButton})&lt;/li&gt;
315      * &lt;li&gt;HtmlElement: Any standard HTML element (equivalent to {@link #addElement})&lt;/li&gt;
316      * &lt;li&gt;Field: Any form field (equivalent to {@link #addField})&lt;/li&gt;
317      * &lt;li&gt;Item: Any subclass of {@link Ext.toolbar.Item} (equivalent to {@link #addItem})&lt;/li&gt;
318      * &lt;li&gt;String: Any generic string (gets wrapped in a {@link Ext.toolbar.TextItem}, equivalent to {@link #addText}).
319      * Note that there are a few special strings that are treated differently as explained next.&lt;/li&gt;
320      * &lt;li&gt;'-': Creates a separator element (equivalent to {@link #addSeparator})&lt;/li&gt;
321      * &lt;li&gt;' ': Creates a spacer element (equivalent to {@link #addSpacer})&lt;/li&gt;
322      * &lt;li&gt;'-&gt;': Creates a fill element (equivalent to {@link #addFill})&lt;/li&gt;
323      * &lt;/ul&gt;
324      * @param {Mixed} arg2
325      * @param {Mixed} etc.
326      * @method add
327      */
328
329     // private
330     lookupComponent: function(c) {
331         if (Ext.isString(c)) {
332             var shortcut = Ext.toolbar.Toolbar.shortcuts[c];
333             if (shortcut) {
334                 c = {
335                     xtype: shortcut
336                 };
337             } else {
338                 c = {
339                     xtype: 'tbtext',
340                     text: c
341                 };
342             }
343             this.applyDefaults(c);
344         }
345         return this.callParent(arguments);
346     },
347
348     // private
349     applyDefaults: function(c) {
350         if (!Ext.isString(c)) {
351             c = this.callParent(arguments);
352             var d = this.internalDefaults;
353             if (c.events) {
354                 Ext.applyIf(c.initialConfig, d);
355                 Ext.apply(c, d);
356             } else {
357                 Ext.applyIf(c, d);
358             }
359         }
360         return c;
361     },
362
363     // private
364     trackMenu: function(item, remove) {
365         if (this.trackMenus &amp;&amp; item.menu) {
366             var method = remove ? 'mun' : 'mon',
367                 me = this;
368
369             me[method](item, 'menutriggerover', me.onButtonTriggerOver, me);
370             me[method](item, 'menushow', me.onButtonMenuShow, me);
371             me[method](item, 'menuhide', me.onButtonMenuHide, me);
372         }
373     },
374
375     // private
376     constructButton: function(item) {
377         return item.events ? item : this.createComponent(item, item.split ? 'splitbutton' : this.defaultType);
378     },
379
380     // private
381     onBeforeAdd: function(component) {
382         if (component.is('field') || (component.is('button') &amp;&amp; this.ui != 'footer')) {
383             component.ui = component.ui + '-toolbar';
384         }
385         
386         // Any separators needs to know if is vertical or not
387         if (component instanceof Ext.toolbar.Separator) {
388             component.setUI((this.vertical) ? 'vertical' : 'horizontal');
389         }
390         
391         this.callParent(arguments);
392     },
393
394     // private
395     onAdd: function(component) {
396         this.callParent(arguments);
397
398         this.trackMenu(component);
399         if (this.disabled) {
400             component.disable();
401         }
402     },
403
404     // private
405     onRemove: function(c) {
406         this.callParent(arguments);
407         this.trackMenu(c, true);
408     },
409
410     // private
411     onButtonTriggerOver: function(btn){
412         if (this.activeMenuBtn &amp;&amp; this.activeMenuBtn != btn) {
413             this.activeMenuBtn.hideMenu();
414             btn.showMenu();
415             this.activeMenuBtn = btn;
416         }
417     },
418
419     // private
420     onButtonMenuShow: function(btn) {
421         this.activeMenuBtn = btn;
422     },
423
424     // private
425     onButtonMenuHide: function(btn) {
426         delete this.activeMenuBtn;
427     }
428 }, function() {
429     this.shortcuts = {
430         '-' : 'tbseparator',
431         ' ' : 'tbspacer',
432         '-&gt;': 'tbfill'
433     };
434 });</pre>
435 </body>
436 </html>