Upgrade to ExtJS 4.0.1 - Released 05/18/2011
[extjs.git] / docs / source / Element-more.html
index 472487c..38ea7bb 100644 (file)
@@ -1,36 +1,75 @@
+<!DOCTYPE html>
 <html>
 <head>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
 </head>
-<body  onload="prettyPrint();">
-    <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.2.0
- * Copyright(c) 2006-2010 Ext JS, Inc.
- * licensing@extjs.com
- * http://www.extjs.com/license
- */
-/**
- * @class Ext.Element
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-core-Element'>/**
+</span> * @class Ext.core.Element
  */
-Ext.Element.addMethods({
-    <div id="method-Ext.Element-swallowEvent"></div>/**
-     * Stops the specified event(s) from bubbling and optionally prevents the default action
+
+Ext.core.Element.addMethods({
+
+<span id='Ext-core-Element-method-monitorMouseLeave'>    /**
+</span>     * Monitors this Element for the mouse leaving. Calls the function after the specified delay only if
+     * the mouse was not moved back into the Element within the delay. If the mouse &lt;i&gt;was&lt;/i&gt; moved
+     * back in, the function is not called.
+     * @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.
+     * @param {Function} handler The function to call if the mouse remains outside of this Element for the specified time.
+     * @param {Object} scope The scope (&lt;code&gt;this&lt;/code&gt; reference) in which the handler function executes. Defaults to this Element.
+     * @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;
+// Hide the menu if the mouse moves out for 250ms or more
+this.mouseLeaveMonitor = this.menuEl.monitorMouseLeave(250, this.hideMenu, this);
+
+...
+// Remove mouseleave monitor on menu destroy
+this.menuEl.un(this.mouseLeaveMonitor);
+&lt;/code&gt;&lt;/pre&gt;
+     */
+    monitorMouseLeave: function(delay, handler, scope) {
+        var me = this,
+            timer,
+            listeners = {
+                mouseleave: function(e) {
+                    timer = setTimeout(Ext.Function.bind(handler, scope||me, [e]), delay);
+                },
+                mouseenter: function() {
+                    clearTimeout(timer);
+                },
+                freezeEvent: true
+            };
+
+        me.on(listeners);
+        return listeners;
+    },
+
+<span id='Ext-core-Element-method-swallowEvent'>    /**
+</span>     * Stops the specified event(s) from bubbling and optionally prevents the default action
      * @param {String/Array} eventName an event / array of events to stop from bubbling
      * @param {Boolean} preventDefault (optional) true to prevent the default action too
-     * @return {Ext.Element} this
+     * @return {Ext.core.Element} this
      */
-    swallowEvent : function(eventName, preventDefault){
+    swallowEvent : function(eventName, preventDefault) {
         var me = this;
-        function fn(e){
+        function fn(e) {
             e.stopPropagation();
-            if(preventDefault){
+            if (preventDefault) {
                 e.preventDefault();
             }
         }
-        if(Ext.isArray(eventName)){
+        
+        if (Ext.isArray(eventName)) {
             Ext.each(eventName, function(e) {
                  me.on(e, fn);
             });
@@ -40,100 +79,128 @@ Ext.Element.addMethods({
         return me;
     },
 
-    <div id="method-Ext.Element-relayEvent"></div>/**
-     * Create an event handler on this element such that when the event fires and is handled by this element,
+<span id='Ext-core-Element-method-relayEvent'>    /**
+</span>     * Create an event handler on this element such that when the event fires and is handled by this element,
      * it will be relayed to another object (i.e., fired again as if it originated from that object instead).
      * @param {String} eventName The type of event to relay
      * @param {Object} object Any object that extends {@link Ext.util.Observable} that will provide the context
      * for firing the relayed event
      */
-    relayEvent : function(eventName, observable){
-        this.on(eventName, function(e){
+    relayEvent : function(eventName, observable) {
+        this.on(eventName, function(e) {
             observable.fireEvent(eventName, e);
         });
     },
 
-    <div id="method-Ext.Element-clean"></div>/**
-     * Removes worthless text nodes
+<span id='Ext-core-Element-method-clean'>    /**
+</span>     * Removes Empty, or whitespace filled text nodes. Combines adjacent text nodes.
      * @param {Boolean} forceReclean (optional) By default the element
      * keeps track if it has been cleaned already so
      * you can call this over and over. However, if you update the element and
      * need to force a reclean, you can pass true.
      */
-    clean : function(forceReclean){
-        var me = this,
+    clean : function(forceReclean) {
+        var me  = this,
             dom = me.dom,
-            n = dom.firstChild,
-            ni = -1;
+            n   = dom.firstChild,
+            nx,
+            ni  = -1;
 
-        if(Ext.Element.data(dom, 'isCleaned') && forceReclean !== true){
+        if (Ext.core.Element.data(dom, 'isCleaned') &amp;&amp; forceReclean !== true) {
             return me;
         }
 
-        while(n){
-            var nx = n.nextSibling;
-            if(n.nodeType == 3 && !/\S/.test(n.nodeValue)){
-                dom.removeChild(n);
-            }else{
+        while (n) {
+            nx = n.nextSibling;
+            if (n.nodeType == 3) {
+                // Remove empty/whitespace text nodes
+                if (!(/\S/.test(n.nodeValue))) {
+                    dom.removeChild(n);
+                // Combine adjacent text nodes
+                } else if (nx &amp;&amp; nx.nodeType == 3) {
+                    n.appendData(Ext.String.trim(nx.data));
+                    dom.removeChild(nx);
+                    nx = n.nextSibling;
+                    n.nodeIndex = ++ni;
+                }
+            } else {
+                // Recursively clean
+                Ext.fly(n).clean();
                 n.nodeIndex = ++ni;
             }
             n = nx;
         }
-        Ext.Element.data(dom, 'isCleaned', true);
+
+        Ext.core.Element.data(dom, 'isCleaned', true);
         return me;
     },
 
-    <div id="method-Ext.Element-load"></div>/**
-     * Direct access to the Updater {@link Ext.Updater#update} method. The method takes the same object
-     * parameter as {@link Ext.Updater#update}
-     * @return {Ext.Element} this
+<span id='Ext-core-Element-method-load'>    /**
+</span>     * Direct access to the Ext.ElementLoader {@link Ext.ElementLoader#load} method. The method takes the same object
+     * parameter as {@link Ext.ElementLoader#load}
+     * @return {Ext.core.Element} this
      */
-    load : function(){
-        var um = this.getUpdater();
-        um.update.apply(um, arguments);
+    load : function(options) {
+        this.getLoader().load(options);
         return this;
     },
 
-    <div id="method-Ext.Element-getUpdater"></div>/**
-    * Gets this element's {@link Ext.Updater Updater}
-    * @return {Ext.Updater} The Updater
+<span id='Ext-core-Element-method-getLoader'>    /**
+</span>    * Gets this element's {@link Ext.ElementLoader ElementLoader}
+    * @return {Ext.ElementLoader} The loader
     */
-    getUpdater : function(){
-        return this.updateManager || (this.updateManager = new Ext.Updater(this));
+    getLoader : function() {
+        var dom = this.dom,
+            data = Ext.core.Element.data,
+            loader = data(dom, 'loader');
+            
+        if (!loader) {
+            loader = Ext.create('Ext.ElementLoader', {
+                target: this
+            });
+            data(dom, 'loader', loader);
+        }
+        return loader;
     },
 
-    <div id="method-Ext.Element-update"></div>/**
-    * Update the innerHTML of this element, optionally searching for and processing scripts
+<span id='Ext-core-Element-method-update'>    /**
+</span>    * Update the innerHTML of this element, optionally searching for and processing scripts
     * @param {String} html The new HTML
     * @param {Boolean} loadScripts (optional) True to look for and process scripts (defaults to false)
     * @param {Function} callback (optional) For async script loading you can be notified when the update completes
-    * @return {Ext.Element} this
+    * @return {Ext.core.Element} this
      */
-    update : function(html, loadScripts, callback){
-        if (!this.dom) {
-            return this;
+    update : function(html, loadScripts, callback) {
+        var me = this,
+            id,
+            dom,
+            interval;
+            
+        if (!me.dom) {
+            return me;
         }
-        html = html || "";
+        html = html || '';
+        dom = me.dom;
 
-        if(loadScripts !== true){
-            this.dom.innerHTML = html;
-            if(Ext.isFunction(callback)){
-                callback();
-            }
-            return this;
+        if (loadScripts !== true) {
+            dom.innerHTML = html;
+            Ext.callback(callback, me);
+            return me;
         }
 
-        var id = Ext.id(),
-            dom = this.dom;
+        id  = Ext.id();
+        html += '&lt;span id=&quot;' + id + '&quot;&gt;&lt;/span&gt;';
 
-        html += '<span id="' + id + '"></span>';
-
-        Ext.lib.Event.onAvailable(id, function(){
-            var DOC = document,
-                hd = DOC.getElementsByTagName("head")[0],
-                re = /(?:<script([^>]*)?>)((\n|\r|.)*?)(?:<\/script>)/ig,
-                srcRe = /\ssrc=([\'\"])(.*?)\1/i,
-                typeRe = /\stype=([\'\"])(.*?)\1/i,
+        interval = setInterval(function(){
+            if (!document.getElementById(id)) {
+                return false;    
+            }
+            clearInterval(interval);
+            var DOC    = document,
+                hd     = DOC.getElementsByTagName(&quot;head&quot;)[0],
+                re     = /(?:&lt;script([^&gt;]*)?&gt;)((\n|\r|.)*?)(?:&lt;\/script&gt;)/ig,
+                srcRe  = /\ssrc=([\'\&quot;])(.*?)\1/i,
+                typeRe = /\stype=([\'\&quot;])(.*?)\1/i,
                 match,
                 attrs,
                 srcMatch,
@@ -141,64 +208,66 @@ Ext.Element.addMethods({
                 el,
                 s;
 
-            while((match = re.exec(html))){
+            while ((match = re.exec(html))) {
                 attrs = match[1];
                 srcMatch = attrs ? attrs.match(srcRe) : false;
-                if(srcMatch && srcMatch[2]){
-                   s = DOC.createElement("script");
+                if (srcMatch &amp;&amp; srcMatch[2]) {
+                   s = DOC.createElement(&quot;script&quot;);
                    s.src = srcMatch[2];
                    typeMatch = attrs.match(typeRe);
-                   if(typeMatch && typeMatch[2]){
+                   if (typeMatch &amp;&amp; typeMatch[2]) {
                        s.type = typeMatch[2];
                    }
                    hd.appendChild(s);
-                }else if(match[2] && match[2].length > 0){
-                    if(window.execScript) {
+                } else if (match[2] &amp;&amp; match[2].length &gt; 0) {
+                    if (window.execScript) {
                        window.execScript(match[2]);
                     } else {
                        window.eval(match[2]);
                     }
                 }
             }
+            
             el = DOC.getElementById(id);
-            if(el){Ext.removeNode(el);}
-            if(Ext.isFunction(callback)){
-                callback();
+            if (el) {
+                Ext.removeNode(el);
             }
-        });
-        dom.innerHTML = html.replace(/(?:<script.*?>)((\n|\r|.)*?)(?:<\/script>)/ig, "");
-        return this;
+            Ext.callback(callback, me);
+        }, 20);
+        dom.innerHTML = html.replace(/(?:&lt;script.*?&gt;)((\n|\r|.)*?)(?:&lt;\/script&gt;)/ig, '');
+        return me;
     },
 
     // inherit docs, overridden so we can add removeAnchor
-    removeAllListeners : function(){
+    removeAllListeners : function() {
         this.removeAnchor();
         Ext.EventManager.removeAll(this.dom);
         return this;
     },
 
-    <div id="method-Ext.Element-createProxy"></div>/**
-     * Creates a proxy element of this element
+<span id='Ext-core-Element-method-createProxy'>    /**
+</span>     * Creates a proxy element of this element
      * @param {String/Object} config The class name of the proxy element or a DomHelper config object
      * @param {String/HTMLElement} renderTo (optional) The element or element id to render the proxy to (defaults to document.body)
      * @param {Boolean} matchBox (optional) True to align and size the proxy to this element now (defaults to false)
-     * @return {Ext.Element} The new proxy element
+     * @return {Ext.core.Element} The new proxy element
      */
-    createProxy : function(config, renderTo, matchBox){
-        config = Ext.isObject(config) ? config : {tag : "div", cls: config};
+    createProxy : function(config, renderTo, matchBox) {
+        config = (typeof config == 'object') ? config : {tag : &quot;div&quot;, cls: config};
 
         var me = this,
-            proxy = renderTo ? Ext.DomHelper.append(renderTo, config, true) :
-                               Ext.DomHelper.insertBefore(me.dom, config, true);
+            proxy = renderTo ? Ext.core.DomHelper.append(renderTo, config, true) :
+                               Ext.core.DomHelper.insertBefore(me.dom, config, true);
 
-        if(matchBox && me.setBox && me.getBox){ // check to make sure Element.position.js is loaded
+        proxy.setVisibilityMode(Ext.core.Element.DISPLAY);
+        proxy.hide();
+        if (matchBox &amp;&amp; me.setBox &amp;&amp; me.getBox) { // check to make sure Element.position.js is loaded
            proxy.setBox(me.getBox());
         }
         return proxy;
     }
 });
-
-Ext.Element.prototype.getUpdateManager = Ext.Element.prototype.getUpdater;
-</pre>    
+Ext.core.Element.prototype.clearListeners = Ext.core.Element.prototype.removeAllListeners;
+</pre>
 </body>
-</html>
\ No newline at end of file
+</html>