Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / Tool.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="../prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../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-panel-Tool'>/**
19 </span> * @class Ext.panel.Tool
20  * @extends Ext.Component
21
22 This class is used to display small visual icons in the header of a panel. There are a set of
23 25 icons that can be specified by using the {@link #type} config. The {@link #handler} config
24 can be used to provide a function that will respond to any click events. In general, this class
25 will not be instantiated directly, rather it will be created by specifying the {@link Ext.panel.Panel#tools}
26 configuration on the Panel itself.
27
28 __Example Usage__
29
30     Ext.create('Ext.panel.Panel', {
31        width: 200,
32        height: 200,
33        renderTo: document.body,
34        title: 'A Panel',
35        tools: [{
36            type: 'help',
37            handler: function(){
38                // show help here
39            }
40        }, {
41            itemId: 'refresh',
42            type: 'refresh',
43            hidden: true,
44            handler: function(){
45                // do refresh
46            }
47        }, {
48            type: 'search',
49            handler: function(event, target, owner, tool){
50                // do search
51                owner.child('#refresh').show();
52            }
53        }]
54     });
55
56  * @markdown
57  */
58 Ext.define('Ext.panel.Tool', {
59     extend: 'Ext.Component',
60     requires: ['Ext.tip.QuickTipManager'],
61     alias: 'widget.tool',
62
63     baseCls: Ext.baseCSSPrefix + 'tool',
64     disabledCls: Ext.baseCSSPrefix + 'tool-disabled',
65     toolPressedCls: Ext.baseCSSPrefix + 'tool-pressed',
66     toolOverCls: Ext.baseCSSPrefix + 'tool-over',
67     ariaRole: 'button',
68     renderTpl: ['&lt;img src=&quot;{blank}&quot; class=&quot;{baseCls}-{type}&quot; role=&quot;presentation&quot;/&gt;'],
69     
70 <span id='Ext-panel-Tool-cfg-handler'>    /**
71 </span>     * @cfg {Function} handler
72      * A function to execute when the tool is clicked.
73      * Arguments passed are:
74      * &lt;ul&gt;
75      * &lt;li&gt;&lt;b&gt;event&lt;/b&gt; : Ext.EventObject&lt;div class=&quot;sub-desc&quot;&gt;The click event.&lt;/div&gt;&lt;/li&gt;
76      * &lt;li&gt;&lt;b&gt;toolEl&lt;/b&gt; : Ext.core.Element&lt;div class=&quot;sub-desc&quot;&gt;The tool Element.&lt;/div&gt;&lt;/li&gt;
77      * &lt;li&gt;&lt;b&gt;panel&lt;/b&gt; : Ext.panel.Panel&lt;div class=&quot;sub-desc&quot;&gt;The host Panel&lt;/div&gt;&lt;/li&gt;
78      * &lt;li&gt;&lt;b&gt;tool&lt;/b&gt; : Ext.panel.Tool&lt;div class=&quot;sub-desc&quot;&gt;The tool object&lt;/div&gt;&lt;/li&gt;
79      * &lt;/ul&gt;
80      */
81     
82 <span id='Ext-panel-Tool-cfg-scope'>    /**
83 </span>     * @cfg {Object} scope
84      * The scope to execute the {@link #handler} function. Defaults to the tool.
85      */
86     
87 <span id='Ext-panel-Tool-cfg-type'>    /**
88 </span>     * @cfg {String} type
89      * The type of tool to render. The following types are available:
90      * &lt;ul&gt;
91      * &lt;li&gt;close&lt;/li&gt;
92      * &lt;li&gt;collapse&lt;/li&gt;
93      * &lt;li&gt;down&lt;/li&gt;
94      * &lt;li&gt;expand&lt;/li&gt;
95      * &lt;li&gt;gear&lt;/li&gt;
96      * &lt;li&gt;help&lt;/li&gt;
97      * &lt;li&gt;left&lt;/li&gt;
98      * &lt;li&gt;maximize&lt;/li&gt;
99      * &lt;li&gt;minimize&lt;/li&gt;
100      * &lt;li&gt;minus&lt;/li&gt;
101      * &lt;li&gt;move&lt;/li&gt;
102      * &lt;li&gt;next&lt;/li&gt;
103      * &lt;li&gt;pin&lt;/li&gt;
104      * &lt;li&gt;plus&lt;/li&gt;
105      * &lt;li&gt;prev&lt;/li&gt;
106      * &lt;li&gt;print&lt;/li&gt;
107      * &lt;li&gt;refresh&lt;/li&gt;
108      * &lt;li&gt;resize&lt;/li&gt;
109      * &lt;li&gt;restore&lt;/li&gt;
110      * &lt;li&gt;right&lt;/li&gt;
111      * &lt;li&gt;save&lt;/li&gt;
112      * &lt;li&gt;search&lt;/li&gt;
113      * &lt;li&gt;toggle&lt;/li&gt;
114      * &lt;li&gt;unpin&lt;/li&gt;
115      * &lt;li&gt;up&lt;/li&gt;
116      * &lt;/ul&gt;
117      */
118     
119 <span id='Ext-panel-Tool-cfg-tooltip'>    /**
120 </span>     * @cfg {String/Object} tooltip 
121      * The tooltip for the tool - can be a string to be used as innerHTML (html tags are accepted) or QuickTips config object
122      */
123     
124 <span id='Ext-panel-Tool-cfg-stopEvent'>    /**
125 </span>     * @cfg {Boolean} stopEvent
126      * Defaults to true. Specify as false to allow click event to propagate.
127      */
128     stopEvent: true,
129
130     initComponent: function() {
131         var me = this;
132         me.addEvents(
133 <span id='Ext-panel-Tool-event-click'>            /**
134 </span>             * @event click
135              * Fires when the tool is clicked
136              * @param {Ext.panel.Tool} this
137              * @param {Ext.EventObject} e The event object
138              */
139             'click'
140         );
141         
142         //&lt;debug&gt;
143         var types = [
144             'close', 
145             'collapse', 
146             'down', 
147             'expand', 
148             'gear', 
149             'help', 
150             'left', 
151             'maximize', 
152             'minimize', 
153             'minus', 
154             'move', 
155             'next', 
156             'pin', 
157             'plus', 
158             'prev', 
159             'print', 
160             'refresh', 
161             'resize', 
162             'restore', 
163             'right', 
164             'save', 
165             'search', 
166             'toggle',
167             'unpin', 
168             'up'
169         ];
170         
171         if (me.id &amp;&amp; Ext.Array.indexOf(types, me.id) &gt; -1 &amp;&amp; Ext.global.console) {
172             Ext.global.console.warn('When specifying a tool you should use the type option, the id can conflict now that tool is a Component');
173         }
174         //&lt;/debug&gt;
175         
176         me.type = me.type || me.id;
177
178         Ext.applyIf(me.renderData, {
179             baseCls: me.baseCls,
180             blank: Ext.BLANK_IMAGE_URL,
181             type: me.type
182         });
183         me.renderSelectors.toolEl = '.' + me.baseCls + '-' + me.type;
184         me.callParent();
185     },
186
187     // inherit docs
188     afterRender: function() {
189         var me = this;
190         me.callParent(arguments);
191         if (me.qtip) {
192             if (Ext.isObject(me.qtip)) {
193                 Ext.tip.QuickTipManager.register(Ext.apply({
194                     target: me.id
195                 }, me.qtip));
196             }
197             else {
198                 me.toolEl.dom.qtip = me.qtip;
199             }
200         }
201
202         me.mon(me.toolEl, {
203             click: me.onClick,
204             mousedown: me.onMouseDown,
205             mouseover: me.onMouseOver,
206             mouseout: me.onMouseOut,
207             scope: me
208         });
209     },
210
211 <span id='Ext-panel-Tool-method-setType'>    /**
212 </span>     * Set the type of the tool. Allows the icon to be changed.
213      * @param {String} type The new type. See the {@link #type} config.
214      * @return {Ext.panel.Tool} this
215      */
216     setType: function(type) {
217         var me = this;
218         
219         me.type = type;
220         if (me.rendered) {
221             me.toolEl.dom.className = me.baseCls + '-' + type;
222         }
223         return me;
224     },
225
226 <span id='Ext-panel-Tool-method-bindTo'>    /**
227 </span>     * Binds this tool to a component.
228      * @private
229      * @param {Ext.Component} component The component
230      */
231     bindTo: function(component) {
232         this.owner = component;
233     },
234
235 <span id='Ext-panel-Tool-method-onClick'>    /**
236 </span>     * Fired when the tool element is clicked
237      * @private
238      * @param {Ext.EventObject} e
239      * @param {HTMLElement} target The target element
240      */
241     onClick: function(e, target) {
242         var me = this,
243             owner;
244             
245         if (me.disabled) {
246             return false;
247         }
248         owner = me.owner || me.ownerCt;
249
250         //remove the pressed + over class
251         me.el.removeCls(me.toolPressedCls);
252         me.el.removeCls(me.toolOverCls);
253
254         if (me.stopEvent !== false) {
255             e.stopEvent();
256         }
257
258         Ext.callback(me.handler, me.scope || me, [e, target, owner, me]);
259         me.fireEvent('click', me, e);
260         return true;
261     },
262     
263     // inherit docs
264     onDestroy: function(){
265         if (Ext.isObject(this.tooltip)) {
266             Ext.tip.QuickTipManager.unregister(this.id);
267         }    
268         this.callParent();
269     },
270
271 <span id='Ext-panel-Tool-method-onMouseDown'>    /**
272 </span>     * Called then the user pressing their mouse button down on a tool
273      * Adds the press class ({@link #toolPressedCls})
274      * @private
275      */
276     onMouseDown: function() {
277         if (this.disabled) {
278             return false;
279         }
280
281         this.el.addCls(this.toolPressedCls);
282     },
283
284 <span id='Ext-panel-Tool-method-onMouseOver'>    /**
285 </span>     * Called when the user rolls over a tool
286      * Adds the over class ({@link #toolOverCls})
287      * @private
288      */
289     onMouseOver: function() {
290         if (this.disabled) {
291             return false;
292         }
293         this.el.addCls(this.toolOverCls);
294     },
295
296 <span id='Ext-panel-Tool-method-onMouseOut'>    /**
297 </span>     * Called when the user rolls out from a tool.
298      * Removes the over class ({@link #toolOverCls})
299      * @private
300      */
301     onMouseOut: function() {
302         this.el.removeCls(this.toolOverCls);
303     }
304 });</pre>
305 </body>
306 </html>