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