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  * This class is used to display small visual icons in the header of a panel. There are a set of
  17  * 25 icons that can be specified by using the {@link #type} config. The {@link #handler} config
  18  * can be used to provide a function that will respond to any click events. In general, this class
  19  * will not be instantiated directly, rather it will be created by specifying the {@link Ext.panel.Panel#tools}
  20  * configuration on the Panel itself.
  21  *
  22  *     @example
  23  *     Ext.create('Ext.panel.Panel', {
  24  *         width: 200,
  25  *         height: 200,
  26  *         renderTo: document.body,
  27  *         title: 'A Panel',
  28  *         tools: [{
  29  *             type: 'help',
  30  *             handler: function(){
  31  *                 // show help here
  32  *             }
  33  *         }, {
  34  *             itemId: 'refresh',
  35  *             type: 'refresh',
  36  *             hidden: true,
  37  *             handler: function(){
  38  *                 // do refresh
  39  *             }
  40  *         }, {
  41  *             type: 'search',
  42  *             handler: function(event, target, owner, tool){
  43  *                 // do search
  44  *                 owner.child('#refresh').show();
  45  *             }
  46  *         }]
  47  *     });
  48  */
  49 Ext.define('Ext.panel.Tool', {
  50     extend: 'Ext.Component',
  51     requires: ['Ext.tip.QuickTipManager'],
  52     alias: 'widget.tool',
  53
  54     baseCls: Ext.baseCSSPrefix + 'tool',
  55     disabledCls: Ext.baseCSSPrefix + 'tool-disabled',
  56     toolPressedCls: Ext.baseCSSPrefix + 'tool-pressed',
  57     toolOverCls: Ext.baseCSSPrefix + 'tool-over',
  58     ariaRole: 'button',
  59     renderTpl: ['<img id="{id}-toolEl" src="{blank}" class="{baseCls}-{type}" role="presentation"/>'],
  60
  61     /**
  62      * @cfg {Function} handler
  63      * A function to execute when the tool is clicked. Arguments passed are:
  64      *
  65      * - **event** : Ext.EventObject - The click event.
  66      * - **toolEl** : Ext.Element - The tool Element.
  67      * - **owner** : Ext.panel.Header - The host panel header.
  68      * - **tool** : Ext.panel.Tool - The tool object
  69      */
  70
  71     /**
  72      * @cfg {Object} scope
  73      * The scope to execute the {@link #handler} function. Defaults to the tool.
  74      */
  75
  76     /**
  77      * @cfg {String} type
  78      * The type of tool to render. The following types are available:
  79      *
  80      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-close"></span> close
  81      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-minimize"></span> minimize
  82      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-maximize"></span> maximize
  83      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-restore"></span> restore
  84      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-toggle"></span> toggle
  85      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-gear"></span> gear
  86      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-prev"></span> prev
  87      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-next"></span> next
  88      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-pin"></span> pin
  89      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-unpin"></span> unpin
  90      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-right"></span> right
  91      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-left"></span> left
  92      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-down"></span> down
  93      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-up"></span> up
  94      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-refresh"></span> refresh
  95      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-plus"></span> plus
  96      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-minus"></span> minus
  97      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-search"></span> search
  98      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-save"></span> save
  99      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-help"></span> help
 100      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-print"></span> print
 101      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-expand"></span> expand
 102      * - <span class="x-tool"><img src="data:image/gif;base64,R0lGODlhAQABAID/AMDAwAAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==" class="x-tool-collapse"></span> collapse
 103      */
 104
 105     /**
 106      * @cfg {String/Object} tooltip
 107      * The tooltip for the tool - can be a string to be used as innerHTML (html tags are accepted) or QuickTips config
 108      * object
 109      */
 110
 111      /**
 112      * @cfg {String} tooltipType
 113      * The type of tooltip to use. Either 'qtip' (default) for QuickTips or 'title' for title attribute.
 114      */
 115     tooltipType: 'qtip',
 116
 117     /**
 118      * @cfg {Boolean} stopEvent
 119      * Specify as false to allow click event to propagate.
 120      */
 121     stopEvent: true,
 122
 123     initComponent: function() {
 124         var me = this;
 125         me.addEvents(
 126             /**
 127              * @event click
 128              * Fires when the tool is clicked
 129              * @param {Ext.panel.Tool} this
 130              * @param {Ext.EventObject} e The event object
 131              */
 132             'click'
 133         );
 134
 135         //<debug>
 136         var types = [
 137             'close',
 138             'collapse',
 139             'down',
 140             'expand',
 141             'gear',
 142             'help',
 143             'left',
 144             'maximize',
 145             'minimize',
 146             'minus',
 147             'move',
 148             'next',
 149             'pin',
 150             'plus',
 151             'prev',
 152             'print',
 153             'refresh',
 154             'resize',
 155             'restore',
 156             'right',
 157             'save',
 158             'search',
 159             'toggle',
 160             'unpin',
 161             'up'
 162         ];
 163
 164         if (me.id && Ext.Array.indexOf(types, me.id) > -1 && Ext.global.console) {
 165             Ext.global.console.warn('When specifying a tool you should use the type option, the id can conflict now that tool is a Component');
 166         }
 167         //</debug>
 168
 169         me.type = me.type || me.id;
 170
 171         Ext.applyIf(me.renderData, {
 172             baseCls: me.baseCls,
 173             blank: Ext.BLANK_IMAGE_URL,
 174             type: me.type
 175         });
 176
 177         me.addChildEls('toolEl');
 178
 179         // alias qtip, should use tooltip since it's what we have in the docs
 180         me.tooltip = me.tooltip || me.qtip;
 181         me.callParent();
 182     },
 183
 184     // inherit docs
 185     afterRender: function() {
 186         var me = this,
 187             attr;
 188
 189         me.callParent(arguments);
 190         if (me.tooltip) {
 191             if (Ext.isObject(me.tooltip)) {
 192                 Ext.tip.QuickTipManager.register(Ext.apply({
 193                     target: me.id
 194                 }, me.tooltip));
 195             }
 196             else {
 197                 attr = me.tooltipType == 'qtip' ? 'data-qtip' : 'title';
 198                 me.toolEl.dom.setAttribute(attr, me.tooltip);
 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     /**
 212      * Sets 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     /**
 227      * 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     /**
 236      * Called 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     /**
 272      * Called when the user presses 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     /**
 285      * 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     /**
 297      * 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 });