Upgrade to ExtJS 3.0.3 - Released 10/11/2009
[extjs.git] / docs / source / CycleButton.html
1 <html>
2 <head>
3   <title>The source code</title>
4     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
5     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
6 </head>
7 <body  onload="prettyPrint();">
8     <pre class="prettyprint lang-js">/*!
9  * Ext JS Library 3.0.3
10  * Copyright(c) 2006-2009 Ext JS, LLC
11  * licensing@extjs.com
12  * http://www.extjs.com/license
13  */
14 <div id="cls-Ext.CycleButton"></div>/**\r
15  * @class Ext.CycleButton\r
16  * @extends Ext.SplitButton\r
17  * A specialized SplitButton that contains a menu of {@link Ext.menu.CheckItem} elements.  The button automatically\r
18  * cycles through each menu item on click, raising the button's {@link #change} event (or calling the button's\r
19  * {@link #changeHandler} function, if supplied) for the active menu item. Clicking on the arrow section of the\r
20  * button displays the dropdown menu just like a normal SplitButton.  Example usage:\r
21  * <pre><code>\r
22 var btn = new Ext.CycleButton({\r
23     showText: true,\r
24     prependText: 'View as ',\r
25     items: [{\r
26         text:'text only',\r
27         iconCls:'view-text',\r
28         checked:true\r
29     },{\r
30         text:'HTML',\r
31         iconCls:'view-html'\r
32     }],\r
33     changeHandler:function(btn, item){\r
34         Ext.Msg.alert('Change View', item.text);\r
35     }\r
36 });\r
37 </code></pre>\r
38  * @constructor\r
39  * Create a new split button\r
40  * @param {Object} config The config object\r
41  * @xtype cycle\r
42  */\r
43 Ext.CycleButton = Ext.extend(Ext.SplitButton, {\r
44     <div id="cfg-Ext.CycleButton-items"></div>/**\r
45      * @cfg {Array} items An array of {@link Ext.menu.CheckItem} <b>config</b> objects to be used when creating the\r
46      * button's menu items (e.g., {text:'Foo', iconCls:'foo-icon'})\r
47      */\r
48     <div id="cfg-Ext.CycleButton-showText"></div>/**\r
49      * @cfg {Boolean} showText True to display the active item's text as the button text (defaults to false)\r
50      */\r
51     <div id="cfg-Ext.CycleButton-prependText"></div>/**\r
52      * @cfg {String} prependText A static string to prepend before the active item's text when displayed as the\r
53      * button's text (only applies when showText = true, defaults to '')\r
54      */\r
55     <div id="cfg-Ext.CycleButton-changeHandler"></div>/**\r
56      * @cfg {Function} changeHandler A callback function that will be invoked each time the active menu\r
57      * item in the button's menu has changed.  If this callback is not supplied, the SplitButton will instead\r
58      * fire the {@link #change} event on active item change.  The changeHandler function will be called with the\r
59      * following argument list: (SplitButton this, Ext.menu.CheckItem item)\r
60      */\r
61     <div id="cfg-Ext.CycleButton-forceIcon"></div>/**\r
62      * @cfg {String} forceIcon A css class which sets an image to be used as the static icon for this button.  This\r
63      * icon will always be displayed regardless of which item is selected in the dropdown list.  This overrides the \r
64      * default behavior of changing the button's icon to match the selected item's icon on change.\r
65      */\r
66     <div id="prop-Ext.CycleButton-menu"></div>/**\r
67      * @property menu\r
68      * @type Menu\r
69      * The {@link Ext.menu.Menu Menu} object used to display the {@link Ext.menu.CheckItem CheckItems} representing the available choices.\r
70      */\r
71 \r
72     // private\r
73     getItemText : function(item){\r
74         if(item && this.showText === true){\r
75             var text = '';\r
76             if(this.prependText){\r
77                 text += this.prependText;\r
78             }\r
79             text += item.text;\r
80             return text;\r
81         }\r
82         return undefined;\r
83     },\r
84 \r
85     <div id="method-Ext.CycleButton-setActiveItem"></div>/**\r
86      * Sets the button's active menu item.\r
87      * @param {Ext.menu.CheckItem} item The item to activate\r
88      * @param {Boolean} suppressEvent True to prevent the button's change event from firing (defaults to false)\r
89      */\r
90     setActiveItem : function(item, suppressEvent){\r
91         if(!Ext.isObject(item)){\r
92             item = this.menu.getComponent(item);\r
93         }\r
94         if(item){\r
95             if(!this.rendered){\r
96                 this.text = this.getItemText(item);\r
97                 this.iconCls = item.iconCls;\r
98             }else{\r
99                 var t = this.getItemText(item);\r
100                 if(t){\r
101                     this.setText(t);\r
102                 }\r
103                 this.setIconClass(item.iconCls);\r
104             }\r
105             this.activeItem = item;\r
106             if(!item.checked){\r
107                 item.setChecked(true, true);\r
108             }\r
109             if(this.forceIcon){\r
110                 this.setIconClass(this.forceIcon);\r
111             }\r
112             if(!suppressEvent){\r
113                 this.fireEvent('change', this, item);\r
114             }\r
115         }\r
116     },\r
117 \r
118     <div id="method-Ext.CycleButton-getActiveItem"></div>/**\r
119      * Gets the currently active menu item.\r
120      * @return {Ext.menu.CheckItem} The active item\r
121      */\r
122     getActiveItem : function(){\r
123         return this.activeItem;\r
124     },\r
125 \r
126     // private\r
127     initComponent : function(){\r
128         this.addEvents(\r
129             <div id="event-Ext.CycleButton-change"></div>/**\r
130              * @event change\r
131              * Fires after the button's active menu item has changed.  Note that if a {@link #changeHandler} function\r
132              * is set on this CycleButton, it will be called instead on active item change and this change event will\r
133              * not be fired.\r
134              * @param {Ext.CycleButton} this\r
135              * @param {Ext.menu.CheckItem} item The menu item that was selected\r
136              */\r
137             "change"\r
138         );\r
139 \r
140         if(this.changeHandler){\r
141             this.on('change', this.changeHandler, this.scope||this);\r
142             delete this.changeHandler;\r
143         }\r
144 \r
145         this.itemCount = this.items.length;\r
146 \r
147         this.menu = {cls:'x-cycle-menu', items:[]};\r
148         var checked;\r
149         Ext.each(this.items, function(item, i){\r
150             Ext.apply(item, {\r
151                 group: item.group || this.id,\r
152                 itemIndex: i,\r
153                 checkHandler: this.checkHandler,\r
154                 scope: this,\r
155                 checked: item.checked || false\r
156             });\r
157             this.menu.items.push(item);\r
158             if(item.checked){\r
159                 checked = item;\r
160             }\r
161         }, this);\r
162         this.setActiveItem(checked, true);\r
163         Ext.CycleButton.superclass.initComponent.call(this);\r
164 \r
165         this.on('click', this.toggleSelected, this);\r
166     },\r
167 \r
168     // private\r
169     checkHandler : function(item, pressed){\r
170         if(pressed){\r
171             this.setActiveItem(item);\r
172         }\r
173     },\r
174 \r
175     <div id="method-Ext.CycleButton-toggleSelected"></div>/**\r
176      * This is normally called internally on button click, but can be called externally to advance the button's\r
177      * active item programmatically to the next one in the menu.  If the current item is the last one in the menu\r
178      * the active item will be set to the first item in the menu.\r
179      */\r
180     toggleSelected : function(){\r
181         var m = this.menu;\r
182         m.render();\r
183         // layout if we haven't before so the items are active\r
184         if(!m.hasLayout){\r
185             m.doLayout();\r
186         }\r
187         \r
188         var nextIdx, checkItem;\r
189         for (var i = 1; i < this.itemCount; i++) {\r
190             nextIdx = (this.activeItem.itemIndex + i) % this.itemCount;\r
191             // check the potential item\r
192             checkItem = m.items.itemAt(nextIdx);\r
193             // if its not disabled then check it.\r
194             if (!checkItem.disabled) {\r
195                 checkItem.setChecked(true);\r
196                 break;\r
197             }\r
198         }\r
199     }\r
200 });\r
201 Ext.reg('cycle', Ext.CycleButton);</pre>
202 </body>
203 </html>