docs/source/Action.html

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