Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Cycle.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="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../resources/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-button-Cycle'>/**
19 </span> * A specialized SplitButton that contains a menu of {@link Ext.menu.CheckItem} elements. The button automatically
20  * cycles through each menu item on click, raising the button's {@link #change} event (or calling the button's
21  * {@link #changeHandler} function, if supplied) for the active menu item. Clicking on the arrow section of the
22  * button displays the dropdown menu just like a normal SplitButton.  Example usage:
23  *
24  *     @example
25  *     Ext.create('Ext.button.Cycle', {
26  *         showText: true,
27  *         prependText: 'View as ',
28  *         renderTo: Ext.getBody(),
29  *         menu: {
30  *             id: 'view-type-menu',
31  *             items: [{
32  *                 text: 'text only',
33  *                 iconCls: 'view-text',
34  *                 checked: true
35  *             },{
36  *                 text: 'HTML',
37  *                 iconCls: 'view-html'
38  *             }]
39  *         },
40  *         changeHandler: function(cycleBtn, activeItem) {
41  *             Ext.Msg.alert('Change View', activeItem.text);
42  *         }
43  *     });
44  */
45 Ext.define('Ext.button.Cycle', {
46
47     /* Begin Definitions */
48
49     alias: 'widget.cycle',
50
51     extend: 'Ext.button.Split',
52     alternateClassName: 'Ext.CycleButton',
53
54     /* End Definitions */
55
56 <span id='Ext-button-Cycle-cfg-items'>    /**
57 </span>     * @cfg {Object[]} items
58      * An array of {@link Ext.menu.CheckItem} **config** objects to be used when creating the button's menu items (e.g.,
59      * `{text:'Foo', iconCls:'foo-icon'}`)
60      * 
61      * @deprecated 4.0 Use the {@link #menu} config instead. All menu items will be created as
62      * {@link Ext.menu.CheckItem CheckItems}.
63      */
64 <span id='Ext-button-Cycle-cfg-showText'>    /**
65 </span>     * @cfg {Boolean} [showText=false]
66      * True to display the active item's text as the button text. The Button will show its
67      * configured {@link #text} if this config is omitted.
68      */
69 <span id='Ext-button-Cycle-cfg-prependText'>    /**
70 </span>     * @cfg {String} [prependText='']
71      * A static string to prepend before the active item's text when displayed as the button's text (only applies when
72      * showText = true).
73      */
74 <span id='Ext-button-Cycle-cfg-changeHandler'>    /**
75 </span>     * @cfg {Function} changeHandler
76      * A callback function that will be invoked each time the active menu item in the button's menu has changed. If this
77      * callback is not supplied, the SplitButton will instead fire the {@link #change} event on active item change. The
78      * changeHandler function will be called with the following argument list: (SplitButton this, Ext.menu.CheckItem
79      * item)
80      */
81 <span id='Ext-button-Cycle-cfg-forceIcon'>    /**
82 </span>     * @cfg {String} forceIcon
83      * A css class which sets an image to be used as the static icon for this button. This icon will always be displayed
84      * regardless of which item is selected in the dropdown list. This overrides the default behavior of changing the
85      * button's icon to match the selected item's icon on change.
86      */
87 <span id='Ext-button-Cycle-property-menu'>    /**
88 </span>     * @property {Ext.menu.Menu} menu
89      * The {@link Ext.menu.Menu Menu} object used to display the {@link Ext.menu.CheckItem CheckItems} representing the
90      * available choices.
91      */
92
93     // private
94     getButtonText: function(item) {
95         var me = this,
96             text = '';
97
98         if (item &amp;&amp; me.showText === true) {
99             if (me.prependText) {
100                 text += me.prependText;
101             }
102             text += item.text;
103             return text;
104         }
105         return me.text;
106     },
107
108 <span id='Ext-button-Cycle-method-setActiveItem'>    /**
109 </span>     * Sets the button's active menu item.
110      * @param {Ext.menu.CheckItem} item The item to activate
111      * @param {Boolean} [suppressEvent=false] True to prevent the button's change event from firing.
112      */
113     setActiveItem: function(item, suppressEvent) {
114         var me = this;
115
116         if (!Ext.isObject(item)) {
117             item = me.menu.getComponent(item);
118         }
119         if (item) {
120             if (!me.rendered) {
121                 me.text = me.getButtonText(item);
122                 me.iconCls = item.iconCls;
123             } else {
124                 me.setText(me.getButtonText(item));
125                 me.setIconCls(item.iconCls);
126             }
127             me.activeItem = item;
128             if (!item.checked) {
129                 item.setChecked(true, false);
130             }
131             if (me.forceIcon) {
132                 me.setIconCls(me.forceIcon);
133             }
134             if (!suppressEvent) {
135                 me.fireEvent('change', me, item);
136             }
137         }
138     },
139
140 <span id='Ext-button-Cycle-method-getActiveItem'>    /**
141 </span>     * Gets the currently active menu item.
142      * @return {Ext.menu.CheckItem} The active item
143      */
144     getActiveItem: function() {
145         return this.activeItem;
146     },
147
148     // private
149     initComponent: function() {
150         var me = this,
151             checked = 0,
152             items;
153
154         me.addEvents(
155 <span id='Ext-button-Cycle-event-change'>            /**
156 </span>             * @event change
157              * Fires after the button's active menu item has changed. Note that if a {@link #changeHandler} function is
158              * set on this CycleButton, it will be called instead on active item change and this change event will not
159              * be fired.
160              * @param {Ext.button.Cycle} this
161              * @param {Ext.menu.CheckItem} item The menu item that was selected
162              */
163             &quot;change&quot;
164         );
165
166         if (me.changeHandler) {
167             me.on('change', me.changeHandler, me.scope || me);
168             delete me.changeHandler;
169         }
170
171         // Allow them to specify a menu config which is a standard Button config.
172         // Remove direct use of &quot;items&quot; in 5.0.
173         items = (me.menu.items||[]).concat(me.items||[]);
174         me.menu = Ext.applyIf({
175             cls: Ext.baseCSSPrefix + 'cycle-menu',
176             items: []
177         }, me.menu);
178
179         // Convert all items to CheckItems
180         Ext.each(items, function(item, i) {
181             item = Ext.applyIf({
182                 group: me.id,
183                 itemIndex: i,
184                 checkHandler: me.checkHandler,
185                 scope: me,
186                 checked: item.checked || false
187             }, item);
188             me.menu.items.push(item);
189             if (item.checked) {
190                 checked = i;
191             }
192         });
193         me.itemCount = me.menu.items.length;
194         me.callParent(arguments);
195         me.on('click', me.toggleSelected, me);
196         me.setActiveItem(checked, me);
197
198         // If configured with a fixed width, the cycling will center a different child item's text each click. Prevent this.
199         if (me.width &amp;&amp; me.showText) {
200             me.addCls(Ext.baseCSSPrefix + 'cycle-fixed-width');
201         }
202     },
203
204     // private
205     checkHandler: function(item, pressed) {
206         if (pressed) {
207             this.setActiveItem(item);
208         }
209     },
210
211 <span id='Ext-button-Cycle-method-toggleSelected'>    /**
212 </span>     * This is normally called internally on button click, but can be called externally to advance the button's active
213      * item programmatically to the next one in the menu. If the current item is the last one in the menu the active
214      * item will be set to the first item in the menu.
215      */
216     toggleSelected: function() {
217         var me = this,
218             m = me.menu,
219             checkItem;
220
221         checkItem = me.activeItem.next(':not([disabled])') || m.items.getAt(0);
222         checkItem.setChecked(true);
223     }
224 });</pre>
225 </body>
226 </html>