docs/source/Toolbar.html

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