Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Toolbar.html
index e627c73..fcf060a 100644 (file)
@@ -3,8 +3,8 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
-  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   <style type="text/css">
     .highlight { display: block; background-color: #ddd; }
   </style>
 </head>
 <body onload="prettyPrint(); highlight();">
   <pre class="prettyprint lang-js"><span id='Ext-toolbar-Toolbar-method-constructor'><span id='Ext-toolbar-Toolbar'>/**
-</span></span> * @class Ext.toolbar.Toolbar
- * @extends Ext.container.Container
-
-Basic Toolbar class. Although the {@link Ext.container.Container#defaultType defaultType} for Toolbar is {@link Ext.button.Button button}, Toolbar 
-elements (child items for the Toolbar container) may be virtually any type of Component. Toolbar elements can be created explicitly via their 
-constructors, or implicitly via their xtypes, and can be {@link #add}ed dynamically.
-
-__Some items have shortcut strings for creation:__
-
-| Shortcut | xtype         | Class                         | Description                                        |
-|:---------|:--------------|:------------------------------|:---------------------------------------------------|
-| `-&gt;`     | `tbspacer`    | {@link Ext.toolbar.Fill}      | begin using the right-justified button container   |
-| `-`      | `tbseparator` | {@link Ext.toolbar.Separator} | add a vertical separator bar between toolbar items |
-| ` `      | `tbspacer`    | {@link Ext.toolbar.Spacer}    | add horiztonal space between elements              |
-
-{@img Ext.toolbar.Toolbar/Ext.toolbar.Toolbar1.png Toolbar component}
-Example usage:
-
-    Ext.create('Ext.toolbar.Toolbar', {
-        renderTo: document.body,
-        width   : 500,
-        items: [
-            {
-                // xtype: 'button', // default for Toolbars
-                text: 'Button'
-            },
-            {
-                xtype: 'splitbutton',
-                text : 'Split Button'
-            },
-            // begin using the right-justified button container
-            '-&gt;', // same as {xtype: 'tbfill'}, // Ext.toolbar.Fill
-            {
-                xtype    : 'textfield',
-                name     : 'field1',
-                emptyText: 'enter search term'
-            },
-            // add a vertical separator bar between toolbar items
-            '-', // same as {xtype: 'tbseparator'} to create Ext.toolbar.Separator
-            'text 1', // same as {xtype: 'tbtext', text: 'text1'} to create Ext.toolbar.TextItem
-            {xtype: 'tbspacer'},// same as ' ' to create Ext.toolbar.Spacer
-            'text 2',
-            {xtype: 'tbspacer', width: 50}, // add a 50px space
-            'text 3'
-        ]
-    });
-
-Toolbars have {@link #enable} and {@link #disable} methods which when called, will enable/disable all items within your toolbar.
-
-{@img Ext.toolbar.Toolbar/Ext.toolbar.Toolbar2.png Toolbar component}
-Example usage:
-
-    Ext.create('Ext.toolbar.Toolbar', {
-        renderTo: document.body,
-        width   : 400,
-        items: [
-            {
-                text: 'Button'
-            },
-            {
-                xtype: 'splitbutton',
-                text : 'Split Button'
-            },
-            '-&gt;',
-            {
-                xtype    : 'textfield',
-                name     : 'field1',
-                emptyText: 'enter search term'
-            }
-        ]
-    });
-
-{@img Ext.toolbar.Toolbar/Ext.toolbar.Toolbar3.png Toolbar component}
-Example usage:
-    
-    var enableBtn = Ext.create('Ext.button.Button', {
-        text    : 'Enable All Items',
-        disabled: true,
-        scope   : this,
-        handler : function() {
-            //disable the enable button and enable the disable button
-            enableBtn.disable();
-            disableBtn.enable();
-            
-            //enable the toolbar
-            toolbar.enable();
-        }
-    });
-    
-    var disableBtn = Ext.create('Ext.button.Button', {
-        text    : 'Disable All Items',
-        scope   : this,
-        handler : function() {
-            //enable the enable button and disable button
-            disableBtn.disable();
-            enableBtn.enable();
-            
-            //disable the toolbar
-            toolbar.disable();
-        }
-    });
-    
-    var toolbar = Ext.create('Ext.toolbar.Toolbar', {
-        renderTo: document.body,
-        width   : 400,
-        margin  : '5 0 0 0',
-        items   : [enableBtn, disableBtn]
-    });
-
-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 
-which remove all items within the toolbar.
-
-{@img Ext.toolbar.Toolbar/Ext.toolbar.Toolbar4.png Toolbar component}
-Example usage:
-
-    var toolbar = Ext.create('Ext.toolbar.Toolbar', {
-        renderTo: document.body,
-        width   : 700,
-        items: [
-            {
-                text: 'Example Button'
-            }
-        ]
-    });
-    
-    var addedItems = [];
-    
-    Ext.create('Ext.toolbar.Toolbar', {
-        renderTo: document.body,
-        width   : 700,
-        margin  : '5 0 0 0',
-        items   : [
-            {
-                text   : 'Add a button',
-                scope  : this,
-                handler: function() {
-                    var text = prompt('Please enter the text for your button:');
-                    addedItems.push(toolbar.add({
-                        text: text
-                    }));
-                }
-            },
-            {
-                text   : 'Add a text item',
-                scope  : this,
-                handler: function() {
-                    var text = prompt('Please enter the text for your item:');
-                    addedItems.push(toolbar.add(text));
-                }
-            },
-            {
-                text   : 'Add a toolbar seperator',
-                scope  : this,
-                handler: function() {
-                    addedItems.push(toolbar.add('-'));
-                }
-            },
-            {
-                text   : 'Add a toolbar spacer',
-                scope  : this,
-                handler: function() {
-                    addedItems.push(toolbar.add('-&gt;'));
-                }
-            },
-            '-&gt;',
-            {
-                text   : 'Remove last inserted item',
-                scope  : this,
-                handler: function() {
-                    if (addedItems.length) {
-                        toolbar.remove(addedItems.pop());
-                    } else if (toolbar.items.length) {
-                        toolbar.remove(toolbar.items.last());
-                    } else {
-                        alert('No items in the toolbar');
-                    }
-                }
-            },
-            {
-                text   : 'Remove all items',
-                scope  : this,
-                handler: function() {
-                    toolbar.removeAll();
-                }
-            }
-        ]
-    });
-
+</span></span> * Basic Toolbar class. Although the {@link Ext.container.Container#defaultType defaultType} for Toolbar is {@link Ext.button.Button button}, Toolbar
+ * elements (child items for the Toolbar container) may be virtually any type of Component. Toolbar elements can be created explicitly via their
+ * constructors, or implicitly via their xtypes, and can be {@link #add}ed dynamically.
+ *
+ * ## Some items have shortcut strings for creation:
+ *
+ * | Shortcut | xtype         | Class                         | Description
+ * |:---------|:--------------|:------------------------------|:---------------------------------------------------
+ * | `-&gt;`     | `tbfill`      | {@link Ext.toolbar.Fill}      | begin using the right-justified button container
+ * | `-`      | `tbseparator` | {@link Ext.toolbar.Separator} | add a vertical separator bar between toolbar items
+ * | ` `      | `tbspacer`    | {@link Ext.toolbar.Spacer}    | add horiztonal space between elements
+ *
+ *     @example
+ *     Ext.create('Ext.toolbar.Toolbar', {
+ *         renderTo: document.body,
+ *         width   : 500,
+ *         items: [
+ *             {
+ *                 // xtype: 'button', // default for Toolbars
+ *                 text: 'Button'
+ *             },
+ *             {
+ *                 xtype: 'splitbutton',
+ *                 text : 'Split Button'
+ *             },
+ *             // begin using the right-justified button container
+ *             '-&gt;', // same as { xtype: 'tbfill' }
+ *             {
+ *                 xtype    : 'textfield',
+ *                 name     : 'field1',
+ *                 emptyText: 'enter search term'
+ *             },
+ *             // add a vertical separator bar between toolbar items
+ *             '-', // same as {xtype: 'tbseparator'} to create Ext.toolbar.Separator
+ *             'text 1', // same as {xtype: 'tbtext', text: 'text1'} to create Ext.toolbar.TextItem
+ *             { xtype: 'tbspacer' },// same as ' ' to create Ext.toolbar.Spacer
+ *             'text 2',
+ *             { xtype: 'tbspacer', width: 50 }, // add a 50px space
+ *             'text 3'
+ *         ]
+ *     });
+ *
+ * Toolbars have {@link #enable} and {@link #disable} methods which when called, will enable/disable all items within your toolbar.
+ *
+ *     @example
+ *     Ext.create('Ext.toolbar.Toolbar', {
+ *         renderTo: document.body,
+ *         width   : 400,
+ *         items: [
+ *             {
+ *                 text: 'Button'
+ *             },
+ *             {
+ *                 xtype: 'splitbutton',
+ *                 text : 'Split Button'
+ *             },
+ *             '-&gt;',
+ *             {
+ *                 xtype    : 'textfield',
+ *                 name     : 'field1',
+ *                 emptyText: 'enter search term'
+ *             }
+ *         ]
+ *     });
+ *
+ * Example
+ *
+ *     @example
+ *     var enableBtn = Ext.create('Ext.button.Button', {
+ *         text    : 'Enable All Items',
+ *         disabled: true,
+ *         scope   : this,
+ *         handler : function() {
+ *             //disable the enable button and enable the disable button
+ *             enableBtn.disable();
+ *             disableBtn.enable();
+ *
+ *             //enable the toolbar
+ *             toolbar.enable();
+ *         }
+ *     });
+ *
+ *     var disableBtn = Ext.create('Ext.button.Button', {
+ *         text    : 'Disable All Items',
+ *         scope   : this,
+ *         handler : function() {
+ *             //enable the enable button and disable button
+ *             disableBtn.disable();
+ *             enableBtn.enable();
+ *
+ *             //disable the toolbar
+ *             toolbar.disable();
+ *         }
+ *     });
+ *
+ *     var toolbar = Ext.create('Ext.toolbar.Toolbar', {
+ *         renderTo: document.body,
+ *         width   : 400,
+ *         margin  : '5 0 0 0',
+ *         items   : [enableBtn, disableBtn]
+ *     });
+ *
+ * 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
+ * which remove all items within the toolbar.
+ *
+ *     @example
+ *     var toolbar = Ext.create('Ext.toolbar.Toolbar', {
+ *         renderTo: document.body,
+ *         width   : 700,
+ *         items: [
+ *             {
+ *                 text: 'Example Button'
+ *             }
+ *         ]
+ *     });
+ *
+ *     var addedItems = [];
+ *
+ *     Ext.create('Ext.toolbar.Toolbar', {
+ *         renderTo: document.body,
+ *         width   : 700,
+ *         margin  : '5 0 0 0',
+ *         items   : [
+ *             {
+ *                 text   : 'Add a button',
+ *                 scope  : this,
+ *                 handler: function() {
+ *                     var text = prompt('Please enter the text for your button:');
+ *                     addedItems.push(toolbar.add({
+ *                         text: text
+ *                     }));
+ *                 }
+ *             },
+ *             {
+ *                 text   : 'Add a text item',
+ *                 scope  : this,
+ *                 handler: function() {
+ *                     var text = prompt('Please enter the text for your item:');
+ *                     addedItems.push(toolbar.add(text));
+ *                 }
+ *             },
+ *             {
+ *                 text   : 'Add a toolbar seperator',
+ *                 scope  : this,
+ *                 handler: function() {
+ *                     addedItems.push(toolbar.add('-'));
+ *                 }
+ *             },
+ *             {
+ *                 text   : 'Add a toolbar spacer',
+ *                 scope  : this,
+ *                 handler: function() {
+ *                     addedItems.push(toolbar.add('-&gt;'));
+ *                 }
+ *             },
+ *             '-&gt;',
+ *             {
+ *                 text   : 'Remove last inserted item',
+ *                 scope  : this,
+ *                 handler: function() {
+ *                     if (addedItems.length) {
+ *                         toolbar.remove(addedItems.pop());
+ *                     } else if (toolbar.items.length) {
+ *                         toolbar.remove(toolbar.items.last());
+ *                     } else {
+ *                         alert('No items in the toolbar');
+ *                     }
+ *                 }
+ *             },
+ *             {
+ *                 text   : 'Remove all items',
+ *                 scope  : this,
+ *                 handler: function() {
+ *                     toolbar.removeAll();
+ *                 }
+ *             }
+ *         ]
+ *     });
+ *
  * @constructor
  * Creates a new Toolbar
- * @param {Object/Array} config A config object or an array of buttons to &lt;code&gt;{@link #add}&lt;/code&gt;
- * @xtype toolbar
+ * @param {Object/Object[]} config A config object or an array of buttons to &lt;code&gt;{@link #add}&lt;/code&gt;
  * @docauthor Robert Dougan &lt;rob@sencha.com&gt;
- * @markdown
  */
 Ext.define('Ext.toolbar.Toolbar', {
     extend: 'Ext.container.Container',
@@ -224,24 +213,23 @@ Ext.define('Ext.toolbar.Toolbar', {
     ],
     alias: 'widget.toolbar',
     alternateClassName: 'Ext.Toolbar',
-    
+
     isToolbar: true,
     baseCls  : Ext.baseCSSPrefix + 'toolbar',
     ariaRole : 'toolbar',
-    
+
     defaultType: 'button',
-    
+
 <span id='Ext-toolbar-Toolbar-cfg-vertical'>    /**
 </span>     * @cfg {Boolean} vertical
      * Set to `true` to make the toolbar vertical. The layout will become a `vbox`.
-     * (defaults to `false`)
      */
     vertical: false,
 
 <span id='Ext-toolbar-Toolbar-cfg-layout'>    /**
 </span>     * @cfg {String/Object} layout
-     * This class assigns a default layout (&lt;code&gt;layout:'&lt;b&gt;hbox&lt;/b&gt;'&lt;/code&gt;).
-     * Developers &lt;i&gt;may&lt;/i&gt; override this configuration option if another layout
+     * This class assigns a default layout (`layout: 'hbox'`).
+     * Developers _may_ override this configuration option if another layout
      * is required (the constructor must be passed a configuration object in this
      * case instead of an array).
      * See {@link Ext.container.Container#layout} for additional information.
@@ -249,16 +237,22 @@ Ext.define('Ext.toolbar.Toolbar', {
 
 <span id='Ext-toolbar-Toolbar-cfg-enableOverflow'>    /**
 </span>     * @cfg {Boolean} enableOverflow
-     * Defaults to false. Configure &lt;code&gt;true&lt;/code&gt; to make the toolbar provide a button
-     * which activates a dropdown Menu to show items which overflow the Toolbar's width.
+     * Configure true to make the toolbar provide a button which activates a dropdown Menu to show
+     * items which overflow the Toolbar's width.
      */
     enableOverflow: false,
+
+<span id='Ext-toolbar-Toolbar-cfg-menuTriggerCls'>    /**
+</span>     * @cfg {String} menuTriggerCls
+     * Configure the icon class of the overflow button.
+     */
+    menuTriggerCls: Ext.baseCSSPrefix + 'toolbar-more-icon',
     
     // private
     trackMenus: true,
-    
+
     itemCls: Ext.baseCSSPrefix + 'toolbar-item',
-    
+
     initComponent: function() {
         var me = this,
             keys;
@@ -267,7 +261,7 @@ Ext.define('Ext.toolbar.Toolbar', {
         if (!me.layout &amp;&amp; me.enableOverflow) {
             me.layout = { overflowHandler: 'Menu' };
         }
-        
+
         if (me.dock === 'right' || me.dock === 'left') {
             me.vertical = true;
         }
@@ -276,18 +270,19 @@ Ext.define('Ext.toolbar.Toolbar', {
             type: me.layout
         } : me.layout || {}, {
             type: me.vertical ? 'vbox' : 'hbox',
-            align: me.vertical ? 'stretchmax' : 'middle'
+            align: me.vertical ? 'stretchmax' : 'middle',
+            clearInnerCtOnLayout: true
         });
-        
+
         if (me.vertical) {
             me.addClsWithUI('vertical');
         }
-        
+
         // @TODO: remove this hack and implement a more general solution
         if (me.ui === 'footer') {
             me.ignoreBorderManagement = true;
         }
-        
+
         me.callParent();
 
 <span id='Ext-toolbar-Toolbar-event-overflowchange'>        /**
@@ -297,7 +292,7 @@ Ext.define('Ext.toolbar.Toolbar', {
          * @param {Boolean} lastOverflow overflow state
          */
         me.addEvents('overflowchange');
-        
+
         // Subscribe to Ext.FocusManager for key navigation
         keys = me.vertical ? ['up', 'down'] : ['left', 'right'];
         Ext.FocusManager.subscribe(me, {
@@ -305,24 +300,38 @@ Ext.define('Ext.toolbar.Toolbar', {
         });
     },
 
+    getRefItems: function(deep) {
+        var me = this,
+            items = me.callParent(arguments),
+            layout = me.layout,
+            handler;
+
+        if (deep &amp;&amp; me.enableOverflow) {
+            handler = layout.overflowHandler;
+            if (handler &amp;&amp; handler.menu) {
+                items = items.concat(handler.menu.getRefItems(deep));
+            }
+        }
+        return items;
+    },
+
 <span id='Ext-toolbar-Toolbar-method-add'>    /**
-</span>     * &lt;p&gt;Adds element(s) to the toolbar -- this function takes a variable number of
-     * arguments of mixed type and adds them to the toolbar.&lt;/p&gt;
-     * &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;
-     * @param {Mixed} arg1 The following types of arguments are all valid:&lt;br /&gt;
-     * &lt;ul&gt;
-     * &lt;li&gt;{@link Ext.button.Button} config: A valid button config object (equivalent to {@link #addButton})&lt;/li&gt;
-     * &lt;li&gt;HtmlElement: Any standard HTML element (equivalent to {@link #addElement})&lt;/li&gt;
-     * &lt;li&gt;Field: Any form field (equivalent to {@link #addField})&lt;/li&gt;
-     * &lt;li&gt;Item: Any subclass of {@link Ext.toolbar.Item} (equivalent to {@link #addItem})&lt;/li&gt;
-     * &lt;li&gt;String: Any generic string (gets wrapped in a {@link Ext.toolbar.TextItem}, equivalent to {@link #addText}).
-     * Note that there are a few special strings that are treated differently as explained next.&lt;/li&gt;
-     * &lt;li&gt;'-': Creates a separator element (equivalent to {@link #addSeparator})&lt;/li&gt;
-     * &lt;li&gt;' ': Creates a spacer element (equivalent to {@link #addSpacer})&lt;/li&gt;
-     * &lt;li&gt;'-&gt;': Creates a fill element (equivalent to {@link #addFill})&lt;/li&gt;
-     * &lt;/ul&gt;
-     * @param {Mixed} arg2
-     * @param {Mixed} etc.
+</span>     * Adds element(s) to the toolbar -- this function takes a variable number of
+     * arguments of mixed type and adds them to the toolbar.
+     *
+     * **Note**: See the notes within {@link Ext.container.Container#add}.
+     *
+     * @param {Object...} args The following types of arguments are all valid:
+     *  - `{@link Ext.button.Button config}`: A valid button config object
+     *  - `HtmlElement`: Any standard HTML element
+     *  - `Field`: Any form field
+     *  - `Item`: Any subclass of {@link Ext.toolbar.Item}
+     *  - `String`: Any generic string (gets wrapped in a {@link Ext.toolbar.TextItem}).
+     *  Note that there are a few special strings that are treated differently as explained next.
+     *  - `'-'`: Creates a separator element
+     *  - `' '`: Creates a spacer element
+     *  - `'-&gt;'`: Creates a fill element
+     *
      * @method add
      */
 
@@ -366,7 +375,7 @@ Ext.define('Ext.toolbar.Toolbar', {
             var method = remove ? 'mun' : 'mon',
                 me = this;
 
-            me[method](item, 'menutriggerover', me.onButtonTriggerOver, me);
+            me[method](item, 'mouseover', me.onButtonOver, me);
             me[method](item, 'menushow', me.onButtonMenuShow, me);
             me[method](item, 'menuhide', me.onButtonMenuHide, me);
         }
@@ -382,12 +391,12 @@ Ext.define('Ext.toolbar.Toolbar', {
         if (component.is('field') || (component.is('button') &amp;&amp; this.ui != 'footer')) {
             component.ui = component.ui + '-toolbar';
         }
-        
+
         // Any separators needs to know if is vertical or not
         if (component instanceof Ext.toolbar.Separator) {
             component.setUI((this.vertical) ? 'vertical' : 'horizontal');
         }
-        
+
         this.callParent(arguments);
     },
 
@@ -408,7 +417,7 @@ Ext.define('Ext.toolbar.Toolbar', {
     },
 
     // private
-    onButtonTriggerOver: function(btn){
+    onButtonOver: function(btn){
         if (this.activeMenuBtn &amp;&amp; this.activeMenuBtn != btn) {
             this.activeMenuBtn.hideMenu();
             btn.showMenu();