source/widgets/Action.js

   1 /*\r
   2  * Ext JS Library 2.2.1\r
   3  * Copyright(c) 2006-2009, Ext JS, LLC.\r
   4  * licensing@extjs.com\r
   5  * \r
   6  * http://extjs.com/license\r
   7  */\r
   8 \r
   9 /**\r
  10  * @class Ext.Action\r
  11  * <p>An Action is a piece of reusable functionality that can be abstracted out of any particular component so that it\r
  12  * can be usefully shared among multiple components.  Actions let you share handlers, configuration options and UI\r
  13  * updates across any components that support the Action interface (primarily {@link Ext.Toolbar}, {@link Ext.Button}\r
  14  * and {@link Ext.menu.Menu} components).</p>\r
  15  * <p>Aside from supporting the config object interface, any component that needs to use Actions must also support\r
  16  * the following method list, as these will be called as needed by the Action class: setText(string), setIconCls(string),\r
  17  * setDisabled(boolean), setVisible(boolean) and setHandler(function).</p>\r
  18  * Example usage:<br>\r
  19  * <pre><code>\r
  20 // Define the shared action.  Each component below will have the same\r
  21 // display text and icon, and will display the same message on click.\r
  22 var action = new Ext.Action({\r
  23     text: 'Do something',\r
  24     handler: function(){\r
  25         Ext.Msg.alert('Click', 'You did something.');\r
  26     },\r
  27     iconCls: 'do-something'\r
  28 });\r
  29 \r
  30 var panel = new Ext.Panel({\r
  31     title: 'Actions',\r
  32     width:500,\r
  33     height:300,\r
  34     tbar: [\r
  35         // Add the action directly to a toolbar as a menu button\r
  36         action, {\r
  37             text: 'Action Menu',\r
  38             // Add the action to a menu as a text item\r
  39             menu: [action]\r
  40         }\r
  41     ],\r
  42     items: [\r
  43         // Add the action to the panel body as a standard button\r
  44         new Ext.Button(action)\r
  45     ],\r
  46     renderTo: Ext.getBody()\r
  47 });\r
  48 \r
  49 // Change the text for all components using the action\r
  50 action.setText('Something else');\r
  51 </code></pre>\r
  52  * @constructor\r
  53  * @param {Object} config The configuration options\r
  54  */\r
  55 Ext.Action = function(config){\r
  56     this.initialConfig = config;\r
  57     this.items = [];\r
  58 }\r
  59 \r
  60 Ext.Action.prototype = {\r
  61     /**\r
  62      * @cfg {String} text The text to set for all components using this action (defaults to '').\r
  63      */\r
  64     /**\r
  65      * @cfg {String} iconCls The icon CSS class for all components using this action (defaults to '').\r
  66      * The class should supply a background image that will be used as the icon image.\r
  67      */\r
  68     /**\r
  69      * @cfg {Boolean} disabled True to disable all components using this action, false to enable them (defaults to false).\r
  70      */\r
  71     /**\r
  72      * @cfg {Boolean} hidden True to hide all components using this action, false to show them (defaults to false).\r
  73      */\r
  74     /**\r
  75      * @cfg {Function} handler The function that will be invoked by each component tied to this action\r
  76      * when the component's primary event is triggered (defaults to undefined).\r
  77      */\r
  78     /**\r
  79      * @cfg {Object} scope The scope in which the {@link #handler} function will execute.\r
  80      */\r
  81 \r
  82     // private\r
  83     isAction : true,\r
  84 \r
  85     /**\r
  86      * Sets the text to be displayed by all components using this action.\r
  87      * @param {String} text The text to display\r
  88      */\r
  89     setText : function(text){\r
  90         this.initialConfig.text = text;\r
  91         this.callEach('setText', [text]);\r
  92     },\r
  93 \r
  94     /**\r
  95      * Gets the text currently displayed by all components using this action.\r
  96      */\r
  97     getText : function(){\r
  98         return this.initialConfig.text;\r
  99     },\r
 100 \r
 101     /**\r
 102      * Sets the icon CSS class for all components using this action.  The class should supply\r
 103      * a background image that will be used as the icon image.\r
 104      * @param {String} cls The CSS class supplying the icon image\r
 105      */\r
 106     setIconClass : function(cls){\r
 107         this.initialConfig.iconCls = cls;\r
 108         this.callEach('setIconClass', [cls]);\r
 109     },\r
 110 \r
 111     /**\r
 112      * Gets the icon CSS class currently used by all components using this action.\r
 113      */\r
 114     getIconClass : function(){\r
 115         return this.initialConfig.iconCls;\r
 116     },\r
 117 \r
 118     /**\r
 119      * Sets the disabled state of all components using this action.  Shortcut method\r
 120      * for {@link #enable} and {@link #disable}.\r
 121      * @param {Boolean} disabled True to disable the component, false to enable it\r
 122      */\r
 123     setDisabled : function(v){\r
 124         this.initialConfig.disabled = v;\r
 125         this.callEach('setDisabled', [v]);\r
 126     },\r
 127 \r
 128     /**\r
 129      * Enables all components using this action.\r
 130      */\r
 131     enable : function(){\r
 132         this.setDisabled(false);\r
 133     },\r
 134 \r
 135     /**\r
 136      * Disables all components using this action.\r
 137      */\r
 138     disable : function(){\r
 139         this.setDisabled(true);\r
 140     },\r
 141 \r
 142     /**\r
 143      * Returns true if the components using this action are currently disabled, else returns false.  Read-only.\r
 144      * @property\r
 145      */\r
 146     isDisabled : function(){\r
 147         return this.initialConfig.disabled;\r
 148     },\r
 149 \r
 150     /**\r
 151      * Sets the hidden state of all components using this action.  Shortcut method\r
 152      * for {@link #hide} and {@link #show}.\r
 153      * @param {Boolean} hidden True to hide the component, false to show it\r
 154      */\r
 155     setHidden : function(v){\r
 156         this.initialConfig.hidden = v;\r
 157         this.callEach('setVisible', [!v]);\r
 158     },\r
 159 \r
 160     /**\r
 161      * Shows all components using this action.\r
 162      */\r
 163     show : function(){\r
 164         this.setHidden(false);\r
 165     },\r
 166 \r
 167     /**\r
 168      * Hides all components using this action.\r
 169      */\r
 170     hide : function(){\r
 171         this.setHidden(true);\r
 172     },\r
 173 \r
 174     /**\r
 175      * Returns true if the components using this action are currently hidden, else returns false.  Read-only.\r
 176      * @property\r
 177      */\r
 178     isHidden : function(){\r
 179         return this.initialConfig.hidden;\r
 180     },\r
 181 \r
 182     /**\r
 183      * Sets the function that will be called by each component using this action when its primary event is triggered.\r
 184      * @param {Function} fn The function that will be invoked by the action's components.  The function\r
 185      * will be called with no arguments.\r
 186      * @param {Object} scope The scope in which the function will execute\r
 187      */\r
 188     setHandler : function(fn, scope){\r
 189         this.initialConfig.handler = fn;\r
 190         this.initialConfig.scope = scope;\r
 191         this.callEach('setHandler', [fn, scope]);\r
 192     },\r
 193 \r
 194     /**\r
 195      * Executes the specified function once for each component currently tied to this action.  The function passed\r
 196      * in should accept a single argument that will be an object that supports the basic Action config/method interface.\r
 197      * @param {Function} fn The function to execute for each component\r
 198      * @param {Object} scope The scope in which the function will execute\r
 199      */\r
 200     each : function(fn, scope){\r
 201         Ext.each(this.items, fn, scope);\r
 202     },\r
 203 \r
 204     // private\r
 205     callEach : function(fnName, args){\r
 206         var cs = this.items;\r
 207         for(var i = 0, len = cs.length; i < len; i++){\r
 208             cs[i][fnName].apply(cs[i], args);\r
 209         }\r
 210     },\r
 211 \r
 212     // private\r
 213     addComponent : function(comp){\r
 214         this.items.push(comp);\r
 215         comp.on('destroy', this.removeComponent, this);\r
 216     },\r
 217 \r
 218     // private\r
 219     removeComponent : function(comp){\r
 220         this.items.remove(comp);\r
 221     },\r
 222 \r
 223     /**\r
 224      * Executes this action manually using the default handler specified in the original config object.  Any arguments\r
 225      * passed to this function will be passed on to the handler function.\r
 226      * @param {Mixed} arg1 (optional) Variable number of arguments passed to the handler function \r
 227      * @param {Mixed} arg2 (optional)\r
 228      * @param {Mixed} etc... (optional)\r
 229      */\r
 230     execute : function(){\r
 231         this.initialConfig.handler.apply(this.initialConfig.scope || window, arguments);\r
 232     }\r
 233 };