extjs/classic/classic/src/Action.js

   1 /**
   2  * An Action is a piece of reusable functionality that can be abstracted out of any particular component so that it
   3  * can be usefully shared among multiple components.  Actions let you share handlers, configuration options and UI
   4  * updates across any components that support the Action interface (primarily {@link Ext.toolbar.Toolbar},
   5  * {@link Ext.button.Button} and {@link Ext.menu.Menu} components).
   6  *
   7  * Use a single Action instance as the config object for any number of UI Components which share the same configuration. The
   8  * Action not only supplies the configuration, but allows all Components based upon it to have a common set of methods
   9  * called at once through a single call to the Action.
  10  *
  11  * Any Component that is to be configured with an Action must also support
  12  * the following methods:
  13  *
  14  * - setText(string)
  15  * - setIconCls(string)
  16  * - setDisabled(boolean)
  17  * - setVisible(boolean)
  18  * - setHandler(function)
  19  *
  20  * This allows the Action to control its associated Components.
  21  *
  22  * Example usage:
  23  *
  24  *     // Define the shared Action.  Each Component below will have the same
  25  *     // display text and icon, and will display the same message on click.
  26  *     var action = new Ext.Action({
  27  *         {@link #text}: 'Do something',
  28  *         {@link #handler}: function(){
  29  *             Ext.Msg.alert('Click', 'You did something.');
  30  *         },
  31  *         {@link #iconCls}: 'do-something',
  32  *         {@link #itemId}: 'myAction'
  33  *     });
  34  *
  35  *     var panel = new Ext.panel.Panel({
  36  *         title: 'Actions',
  37  *         width: 500,
  38  *         height: 300,
  39  *         tbar: [
  40  *             // Add the Action directly to a toolbar as a menu button
  41  *             action,
  42  *             {
  43  *                 text: 'Action Menu',
  44  *                 // Add the Action to a menu as a text item
  45  *                 menu: [action]
  46  *             }
  47  *         ],
  48  *         items: [
  49  *             // Add the Action to the panel body as a standard button
  50  *             new Ext.button.Button(action)
  51  *         ],
  52  *         renderTo: Ext.getBody()
  53  *     });
  54  *
  55  *     // Change the text for all components using the Action
  56  *     action.setText('Something else');
  57  *
  58  *     // Reference an Action through a container using the itemId
  59  *     var btn = panel.getComponent('myAction');
  60  *     var aRef = btn.baseAction;
  61  *     aRef.setText('New text');
  62  */
  63 Ext.define('Ext.Action', {
  64
  65     /* Begin Definitions */
  66
  67     /* End Definitions */
  68
  69     /**
  70      * @cfg {String} [text='']
  71      * The text to set for all components configured by this Action.
  72      */
  73     /**
  74      * @cfg {String} [iconCls='']
  75      * @localdoc **Note:** The CSS class(es) specifying the background image will apply
  76      * to all components configured by this Action.
  77      * @inheritdoc Ext.panel.Header#cfg-iconCls
  78      */
  79     /**
  80      * @cfg {Boolean} [disabled=false]
  81      * True to disable all components configured by this Action, false to enable them.
  82      */
  83     /**
  84      * @cfg {Boolean} [hidden=false]
  85      * True to hide all components configured by this Action, false to show them.
  86      */
  87     /**
  88      * @cfg {Function} handler
  89      * The function that will be invoked by each component tied to this Action
  90      * when the component's primary event is triggered.
  91      */
  92     /**
  93      * @cfg {String} itemId
  94      * See {@link Ext.Component}.{@link Ext.Component#itemId itemId}.
  95      */
  96     /**
  97      * @cfg {Object} scope
  98      * The scope (this reference) in which the {@link #handler} is executed.
  99      * Defaults to the browser window.
 100      */
 101
 102     /**
 103      * Creates new Action.
 104      * @param {Object} config Config object.
 105      */
 106     constructor : function(config){
 107         this.initialConfig = config;
 108         this.itemId = config.itemId = (config.itemId || config.id || Ext.id());
 109         this.items = [];
 110     },
 111
 112     /**
 113      * @property {Boolean} isAction
 114      * `true` in this class to identify an object as an instantiated Action, or subclass thereof.
 115      */
 116     isAction : true,
 117
 118     /**
 119      * Sets the text to be displayed by all components configured by this Action.
 120      * @param {String} text The text to display
 121      */
 122     setText : function(text){
 123         this.initialConfig.text = text;
 124         this.callEach('setText', [text]);
 125     },
 126
 127     /**
 128      * Gets the text currently displayed by all components configured by this Action.
 129      */
 130     getText : function(){
 131         return this.initialConfig.text;
 132     },
 133
 134     /**
 135      * Sets the {@link #iconCls icon CSS class} for all components configured by this
 136      * Action.  The class should supply a background image that will be used as the icon
 137      * image.
 138      * @param {String} cls The CSS class supplying the icon image
 139      */
 140     setIconCls : function(cls){
 141         this.initialConfig.iconCls = cls;
 142         this.callEach('setIconCls', [cls]);
 143     },
 144
 145     /**
 146      * Gets the icon CSS class currently used by all components configured by this Action.
 147      */
 148     getIconCls : function(){
 149         return this.initialConfig.iconCls;
 150     },
 151
 152     /**
 153      * Sets the disabled state of all components configured by this Action.  Shortcut method
 154      * for {@link #enable} and {@link #disable}.
 155      * @param {Boolean} disabled True to disable the component, false to enable it
 156      */
 157     setDisabled : function(v){
 158         this.initialConfig.disabled = v;
 159         this.callEach('setDisabled', [v]);
 160     },
 161
 162     /**
 163      * Enables all components configured by this Action.
 164      */
 165     enable : function(){
 166         this.setDisabled(false);
 167     },
 168
 169     /**
 170      * Disables all components configured by this Action.
 171      */
 172     disable : function(){
 173         this.setDisabled(true);
 174     },
 175
 176     /**
 177      * Returns true if the components using this Action are currently disabled, else returns false.
 178      */
 179     isDisabled : function(){
 180         return this.initialConfig.disabled;
 181     },
 182
 183     /**
 184      * Sets the hidden state of all components configured by this Action.  Shortcut method
 185      * for `{@link #hide}` and `{@link #show}`.
 186      * @param {Boolean} hidden True to hide the component, false to show it.
 187      */
 188     setHidden : function(v){
 189         this.initialConfig.hidden = v;
 190         this.callEach('setVisible', [!v]);
 191     },
 192
 193     /**
 194      * Shows all components configured by this Action.
 195      */
 196     show : function(){
 197         this.setHidden(false);
 198     },
 199
 200     /**
 201      * Hides all components configured by this Action.
 202      */
 203     hide : function(){
 204         this.setHidden(true);
 205     },
 206
 207     /**
 208      * Returns true if the components configured by this Action are currently hidden, else returns false.
 209      */
 210     isHidden : function(){
 211         return this.initialConfig.hidden;
 212     },
 213
 214     /**
 215      * Sets the function that will be called by each Component using this action when its primary event is triggered.
 216      * @param {Function} fn The function that will be invoked by the action's components.  The function
 217      * will be called with no arguments.
 218      * @param {Object} scope The scope (this reference) in which the function is executed. Defaults to the Component
 219      * firing the event.
 220      */
 221     setHandler : function(fn, scope){
 222         this.initialConfig.handler = fn;
 223         this.initialConfig.scope = scope;
 224         this.callEach('setHandler', [fn, scope]);
 225     },
 226
 227     /**
 228      * Executes the specified function once for each Component currently tied to this Action.  The function passed
 229      * in should accept a single argument that will be an object that supports the basic Action config/method interface.
 230      * @param {Function} fn The function to execute for each component
 231      * @param {Object} scope The scope (this reference) in which the function is executed.
 232      * Defaults to the Component.
 233      */
 234     each : function(fn, scope){
 235         Ext.each(this.items, fn, scope);
 236     },
 237
 238     /**
 239      * @private
 240      */
 241     callEach : function(fnName, args){
 242         var items = this.items,
 243             i = 0,
 244             len = items.length,
 245             item;
 246
 247         Ext.suspendLayouts();
 248         for(; i < len; i++){
 249             item = items[i];
 250             item[fnName].apply(item, args);
 251         }
 252         Ext.resumeLayouts(true);
 253     },
 254
 255     /**
 256      * @private
 257      */
 258     addComponent : function(comp){
 259         this.items.push(comp);
 260         comp.on('destroy', this.removeComponent, this);
 261     },
 262
 263     /**
 264      * @private
 265      */
 266     removeComponent : function(comp){
 267         Ext.Array.remove(this.items, comp);
 268     },
 269
 270     /**
 271      * Executes this Action manually using the handler function specified in the original config object
 272      * or the handler function set with {@link #setHandler}.  Any arguments passed to this
 273      * function will be passed on to the handler function.
 274      * @param {Object...} args Variable number of arguments passed to the handler function
 275      */
 276     execute : function(){
 277         this.initialConfig.handler.apply(this.initialConfig.scope || Ext.global, arguments);
 278     }
 279 });