src/panel/Tool.js

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