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