src/widgets/ComponentMgr.js

   1 /*!
   2  * Ext JS Library 3.2.0
   3  * Copyright(c) 2006-2010 Ext JS, Inc.
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**
   8  * @class Ext.ComponentMgr
   9  * <p>Provides a registry of all Components (instances of {@link Ext.Component} or any subclass
  10  * thereof) on a page so that they can be easily accessed by {@link Ext.Component component}
  11  * {@link Ext.Component#id id} (see {@link #get}, or the convenience method {@link Ext#getCmp Ext.getCmp}).</p>
  12  * <p>This object also provides a registry of available Component <i>classes</i>
  13  * indexed by a mnemonic code known as the Component's {@link Ext.Component#xtype xtype}.
  14  * The <code>{@link Ext.Component#xtype xtype}</code> provides a way to avoid instantiating child Components
  15  * when creating a full, nested config object for a complete Ext page.</p>
  16  * <p>A child Component may be specified simply as a <i>config object</i>
  17  * as long as the correct <code>{@link Ext.Component#xtype xtype}</code> is specified so that if and when the Component
  18  * needs rendering, the correct type can be looked up for lazy instantiation.</p>
  19  * <p>For a list of all available <code>{@link Ext.Component#xtype xtypes}</code>, see {@link Ext.Component}.</p>
  20  * @singleton
  21  */
  22 Ext.ComponentMgr = function(){
  23     var all = new Ext.util.MixedCollection();
  24     var types = {};
  25     var ptypes = {};
  26
  27     return {
  28         /**
  29          * Registers a component.
  30          * @param {Ext.Component} c The component
  31          */
  32         register : function(c){
  33             all.add(c);
  34         },
  35
  36         /**
  37          * Unregisters a component.
  38          * @param {Ext.Component} c The component
  39          */
  40         unregister : function(c){
  41             all.remove(c);
  42         },
  43
  44         /**
  45          * Returns a component by {@link Ext.Component#id id}.
  46          * For additional details see {@link Ext.util.MixedCollection#get}.
  47          * @param {String} id The component {@link Ext.Component#id id}
  48          * @return Ext.Component The Component, <code>undefined</code> if not found, or <code>null</code> if a
  49          * Class was found.
  50          */
  51         get : function(id){
  52             return all.get(id);
  53         },
  54
  55         /**
  56          * Registers a function that will be called when a Component with the specified id is added to ComponentMgr. This will happen on instantiation.
  57          * @param {String} id The component {@link Ext.Component#id id}
  58          * @param {Function} fn The callback function
  59          * @param {Object} scope The scope (<code>this</code> reference) in which the callback is executed. Defaults to the Component.
  60          */
  61         onAvailable : function(id, fn, scope){
  62             all.on("add", function(index, o){
  63                 if(o.id == id){
  64                     fn.call(scope || o, o);
  65                     all.un("add", fn, scope);
  66                 }
  67             });
  68         },
  69
  70         /**
  71          * The MixedCollection used internally for the component cache. An example usage may be subscribing to
  72          * events on the MixedCollection to monitor addition or removal.  Read-only.
  73          * @type {MixedCollection}
  74          */
  75         all : all,
  76
  77         /**
  78          * The xtypes that have been registered with the component manager.
  79          * @type {Object}
  80          */
  81         types : types,
  82
  83         /**
  84          * The ptypes that have been registered with the component manager.
  85          * @type {Object}
  86          */
  87         ptypes: ptypes,
  88
  89         /**
  90          * Checks if a Component type is registered.
  91          * @param {Ext.Component} xtype The mnemonic string by which the Component class may be looked up
  92          * @return {Boolean} Whether the type is registered.
  93          */
  94         isRegistered : function(xtype){
  95             return types[xtype] !== undefined;
  96         },
  97
  98         /**
  99          * Checks if a Plugin type is registered.
 100          * @param {Ext.Component} ptype The mnemonic string by which the Plugin class may be looked up
 101          * @return {Boolean} Whether the type is registered.
 102          */
 103         isPluginRegistered : function(ptype){
 104             return ptypes[ptype] !== undefined;
 105         },
 106
 107         /**
 108          * <p>Registers a new Component constructor, keyed by a new
 109          * {@link Ext.Component#xtype}.</p>
 110          * <p>Use this method (or its alias {@link Ext#reg Ext.reg}) to register new
 111          * subclasses of {@link Ext.Component} so that lazy instantiation may be used when specifying
 112          * child Components.
 113          * see {@link Ext.Container#items}</p>
 114          * @param {String} xtype The mnemonic string by which the Component class may be looked up.
 115          * @param {Constructor} cls The new Component class.
 116          */
 117         registerType : function(xtype, cls){
 118             types[xtype] = cls;
 119             cls.xtype = xtype;
 120         },
 121
 122         /**
 123          * Creates a new Component from the specified config object using the
 124          * config object's {@link Ext.component#xtype xtype} to determine the class to instantiate.
 125          * @param {Object} config A configuration object for the Component you wish to create.
 126          * @param {Constructor} defaultType The constructor to provide the default Component type if
 127          * the config object does not contain a <code>xtype</code>. (Optional if the config contains a <code>xtype</code>).
 128          * @return {Ext.Component} The newly instantiated Component.
 129          */
 130         create : function(config, defaultType){
 131             return config.render ? config : new types[config.xtype || defaultType](config);
 132         },
 133
 134         /**
 135          * <p>Registers a new Plugin constructor, keyed by a new
 136          * {@link Ext.Component#ptype}.</p>
 137          * <p>Use this method (or its alias {@link Ext#preg Ext.preg}) to register new
 138          * plugins for {@link Ext.Component}s so that lazy instantiation may be used when specifying
 139          * Plugins.</p>
 140          * @param {String} ptype The mnemonic string by which the Plugin class may be looked up.
 141          * @param {Constructor} cls The new Plugin class.
 142          */
 143         registerPlugin : function(ptype, cls){
 144             ptypes[ptype] = cls;
 145             cls.ptype = ptype;
 146         },
 147
 148         /**
 149          * Creates a new Plugin from the specified config object using the
 150          * config object's {@link Ext.component#ptype ptype} to determine the class to instantiate.
 151          * @param {Object} config A configuration object for the Plugin you wish to create.
 152          * @param {Constructor} defaultType The constructor to provide the default Plugin type if
 153          * the config object does not contain a <code>ptype</code>. (Optional if the config contains a <code>ptype</code>).
 154          * @return {Ext.Component} The newly instantiated Plugin.
 155          */
 156         createPlugin : function(config, defaultType){
 157             var PluginCls = ptypes[config.ptype || defaultType];
 158             if (PluginCls.init) {
 159                 return PluginCls;
 160             } else {
 161                 return new PluginCls(config);
 162             }
 163         }
 164     };
 165 }();
 166
 167 /**
 168  * Shorthand for {@link Ext.ComponentMgr#registerType}
 169  * @param {String} xtype The {@link Ext.component#xtype mnemonic string} by which the Component class
 170  * may be looked up.
 171  * @param {Constructor} cls The new Component class.
 172  * @member Ext
 173  * @method reg
 174  */
 175 Ext.reg = Ext.ComponentMgr.registerType; // this will be called a lot internally, shorthand to keep the bytes down
 176 /**
 177  * Shorthand for {@link Ext.ComponentMgr#registerPlugin}
 178  * @param {String} ptype The {@link Ext.component#ptype mnemonic string} by which the Plugin class
 179  * may be looked up.
 180  * @param {Constructor} cls The new Plugin class.
 181  * @member Ext
 182  * @method preg
 183  */
 184 Ext.preg = Ext.ComponentMgr.registerPlugin;
 185 /**
 186  * Shorthand for {@link Ext.ComponentMgr#create}
 187  * Creates a new Component from the specified config object using the
 188  * config object's {@link Ext.component#xtype xtype} to determine the class to instantiate.
 189  * @param {Object} config A configuration object for the Component you wish to create.
 190  * @param {Constructor} defaultType The constructor to provide the default Component type if
 191  * the config object does not contain a <code>xtype</code>. (Optional if the config contains a <code>xtype</code>).
 192  * @return {Ext.Component} The newly instantiated Component.
 193  * @member Ext
 194  * @method create
 195  */
 196 Ext.create = Ext.ComponentMgr.create;