docs/source/Action.html

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