Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Element-more.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-Element'>/**
19 </span> * @class Ext.Element
20  */
21
22 Ext.Element.addMethods((function(){
23     var focusRe = /button|input|textarea|select|object/;
24     return {
25 <span id='Ext-Element-method-monitorMouseLeave'>        /**
26 </span>         * Monitors this Element for the mouse leaving. Calls the function after the specified delay only if
27          * the mouse was not moved back into the Element within the delay. If the mouse &lt;i&gt;was&lt;/i&gt; moved
28          * back in, the function is not called.
29          * @param {Number} delay The delay &lt;b&gt;in milliseconds&lt;/b&gt; to wait for possible mouse re-entry before calling the handler function.
30          * @param {Function} handler The function to call if the mouse remains outside of this Element for the specified time.
31          * @param {Object} scope The scope (&lt;code&gt;this&lt;/code&gt; reference) in which the handler function executes. Defaults to this Element.
32          * @return {Object} The listeners object which was added to this element so that monitoring can be stopped. Example usage:&lt;pre&gt;&lt;code&gt;
33 // Hide the menu if the mouse moves out for 250ms or more
34 this.mouseLeaveMonitor = this.menuEl.monitorMouseLeave(250, this.hideMenu, this);
35
36 ...
37 // Remove mouseleave monitor on menu destroy
38 this.menuEl.un(this.mouseLeaveMonitor);
39     &lt;/code&gt;&lt;/pre&gt;
40          */
41         monitorMouseLeave: function(delay, handler, scope) {
42             var me = this,
43                 timer,
44                 listeners = {
45                     mouseleave: function(e) {
46                         timer = setTimeout(Ext.Function.bind(handler, scope||me, [e]), delay);
47                     },
48                     mouseenter: function() {
49                         clearTimeout(timer);
50                     },
51                     freezeEvent: true
52                 };
53
54             me.on(listeners);
55             return listeners;
56         },
57
58 <span id='Ext-Element-method-swallowEvent'>        /**
59 </span>         * Stops the specified event(s) from bubbling and optionally prevents the default action
60          * @param {String/String[]} eventName an event / array of events to stop from bubbling
61          * @param {Boolean} preventDefault (optional) true to prevent the default action too
62          * @return {Ext.Element} this
63          */
64         swallowEvent : function(eventName, preventDefault) {
65             var me = this;
66             function fn(e) {
67                 e.stopPropagation();
68                 if (preventDefault) {
69                     e.preventDefault();
70                 }
71             }
72
73             if (Ext.isArray(eventName)) {
74                 Ext.each(eventName, function(e) {
75                      me.on(e, fn);
76                 });
77                 return me;
78             }
79             me.on(eventName, fn);
80             return me;
81         },
82
83 <span id='Ext-Element-method-relayEvent'>        /**
84 </span>         * Create an event handler on this element such that when the event fires and is handled by this element,
85          * it will be relayed to another object (i.e., fired again as if it originated from that object instead).
86          * @param {String} eventName The type of event to relay
87          * @param {Object} object Any object that extends {@link Ext.util.Observable} that will provide the context
88          * for firing the relayed event
89          */
90         relayEvent : function(eventName, observable) {
91             this.on(eventName, function(e) {
92                 observable.fireEvent(eventName, e);
93             });
94         },
95
96 <span id='Ext-Element-method-clean'>        /**
97 </span>         * Removes Empty, or whitespace filled text nodes. Combines adjacent text nodes.
98          * @param {Boolean} forceReclean (optional) By default the element
99          * keeps track if it has been cleaned already so
100          * you can call this over and over. However, if you update the element and
101          * need to force a reclean, you can pass true.
102          */
103         clean : function(forceReclean) {
104             var me  = this,
105                 dom = me.dom,
106                 n   = dom.firstChild,
107                 nx,
108                 ni  = -1;
109     
110             if (Ext.Element.data(dom, 'isCleaned') &amp;&amp; forceReclean !== true) {
111                 return me;
112             }
113
114             while (n) {
115                 nx = n.nextSibling;
116                 if (n.nodeType == 3) {
117                     // Remove empty/whitespace text nodes
118                     if (!(/\S/.test(n.nodeValue))) {
119                         dom.removeChild(n);
120                     // Combine adjacent text nodes
121                     } else if (nx &amp;&amp; nx.nodeType == 3) {
122                         n.appendData(Ext.String.trim(nx.data));
123                         dom.removeChild(nx);
124                         nx = n.nextSibling;
125                         n.nodeIndex = ++ni;
126                     }
127                 } else {
128                     // Recursively clean
129                     Ext.fly(n).clean();
130                     n.nodeIndex = ++ni;
131                 }
132                 n = nx;
133             }
134
135             Ext.Element.data(dom, 'isCleaned', true);
136             return me;
137         },
138
139 <span id='Ext-Element-method-load'>        /**
140 </span>         * Direct access to the Ext.ElementLoader {@link Ext.ElementLoader#load} method. The method takes the same object
141          * parameter as {@link Ext.ElementLoader#load}
142          * @return {Ext.Element} this
143          */
144         load : function(options) {
145             this.getLoader().load(options);
146             return this;
147         },
148
149 <span id='Ext-Element-method-getLoader'>        /**
150 </span>        * Gets this element's {@link Ext.ElementLoader ElementLoader}
151         * @return {Ext.ElementLoader} The loader
152         */
153         getLoader : function() {
154             var dom = this.dom,
155                 data = Ext.Element.data,
156                 loader = data(dom, 'loader');
157     
158             if (!loader) {
159                 loader = Ext.create('Ext.ElementLoader', {
160                     target: this
161                 });
162                 data(dom, 'loader', loader);
163             }
164             return loader;
165         },
166
167 <span id='Ext-Element-method-update'>        /**
168 </span>        * Update the innerHTML of this element, optionally searching for and processing scripts
169         * @param {String} html The new HTML
170         * @param {Boolean} [loadScripts=false] True to look for and process scripts
171         * @param {Function} [callback] For async script loading you can be notified when the update completes
172         * @return {Ext.Element} this
173          */
174         update : function(html, loadScripts, callback) {
175             var me = this,
176                 id,
177                 dom,
178                 interval;
179
180             if (!me.dom) {
181                 return me;
182             }
183             html = html || '';
184             dom = me.dom;
185
186             if (loadScripts !== true) {
187                 dom.innerHTML = html;
188                 Ext.callback(callback, me);
189                 return me;
190             }
191
192             id  = Ext.id();
193             html += '&lt;span id=&quot;' + id + '&quot;&gt;&lt;/span&gt;';
194
195             interval = setInterval(function(){
196                 if (!document.getElementById(id)) {
197                     return false;
198                 }
199                 clearInterval(interval);
200                 var DOC    = document,
201                     hd     = DOC.getElementsByTagName(&quot;head&quot;)[0],
202                     re     = /(?:&lt;script([^&gt;]*)?&gt;)((\n|\r|.)*?)(?:&lt;\/script&gt;)/ig,
203                     srcRe  = /\ssrc=([\'\&quot;])(.*?)\1/i,
204                     typeRe = /\stype=([\'\&quot;])(.*?)\1/i,
205                     match,
206                     attrs,
207                     srcMatch,
208                     typeMatch,
209                     el,
210                     s;
211
212                 while ((match = re.exec(html))) {
213                     attrs = match[1];
214                     srcMatch = attrs ? attrs.match(srcRe) : false;
215                     if (srcMatch &amp;&amp; srcMatch[2]) {
216                        s = DOC.createElement(&quot;script&quot;);
217                        s.src = srcMatch[2];
218                        typeMatch = attrs.match(typeRe);
219                        if (typeMatch &amp;&amp; typeMatch[2]) {
220                            s.type = typeMatch[2];
221                        }
222                        hd.appendChild(s);
223                     } else if (match[2] &amp;&amp; match[2].length &gt; 0) {
224                         if (window.execScript) {
225                            window.execScript(match[2]);
226                         } else {
227                            window.eval(match[2]);
228                         }
229                     }
230                 }
231
232                 el = DOC.getElementById(id);
233                 if (el) {
234                     Ext.removeNode(el);
235                 }
236                 Ext.callback(callback, me);
237             }, 20);
238             dom.innerHTML = html.replace(/(?:&lt;script.*?&gt;)((\n|\r|.)*?)(?:&lt;\/script&gt;)/ig, '');
239             return me;
240         },
241
242         // inherit docs, overridden so we can add removeAnchor
243         removeAllListeners : function() {
244             this.removeAnchor();
245             Ext.EventManager.removeAll(this.dom);
246             return this;
247         },
248     
249 <span id='Ext-Element-method-getScopeParent'>        /**
250 </span>         * Gets the parent node of the current element taking into account Ext.scopeResetCSS
251          * @protected
252          * @return {HTMLElement} The parent element
253          */
254         getScopeParent: function(){
255             var parent = this.dom.parentNode;
256             return Ext.scopeResetCSS ? parent.parentNode : parent;
257         },
258
259 <span id='Ext-Element-method-createProxy'>        /**
260 </span>         * Creates a proxy element of this element
261          * @param {String/Object} config The class name of the proxy element or a DomHelper config object
262          * @param {String/HTMLElement} [renderTo] The element or element id to render the proxy to (defaults to document.body)
263          * @param {Boolean} [matchBox=false] True to align and size the proxy to this element now.
264          * @return {Ext.Element} The new proxy element
265          */
266         createProxy : function(config, renderTo, matchBox) {
267             config = (typeof config == 'object') ? config : {tag : &quot;div&quot;, cls: config};
268
269             var me = this,
270                 proxy = renderTo ? Ext.DomHelper.append(renderTo, config, true) :
271                                    Ext.DomHelper.insertBefore(me.dom, config, true);
272
273             proxy.setVisibilityMode(Ext.Element.DISPLAY);
274             proxy.hide();
275             if (matchBox &amp;&amp; me.setBox &amp;&amp; me.getBox) { // check to make sure Element.position.js is loaded
276                proxy.setBox(me.getBox());
277             }
278             return proxy;
279         },
280     
281 <span id='Ext-Element-method-focusable'>        /**
282 </span>         * Checks whether this element can be focused.
283          * @return {Boolean} True if the element is focusable
284          */
285         focusable: function(){
286             var dom = this.dom,
287                 nodeName = dom.nodeName.toLowerCase(),
288                 canFocus = false,
289                 hasTabIndex = !isNaN(dom.tabIndex);
290             
291             if (!dom.disabled) {
292                 if (focusRe.test(nodeName)) {
293                     canFocus = true;
294                 } else {
295                     canFocus = nodeName == 'a' ? dom.href || hasTabIndex : hasTabIndex;
296                 }
297             }
298             return canFocus &amp;&amp; this.isVisible(true);
299         }    
300     };
301 })());
302 Ext.Element.prototype.clearListeners = Ext.Element.prototype.removeAllListeners;
303 </pre>
304 </body>
305 </html>