src/ext-core/src/core/Element.js

   1 /*!
   2  * Ext JS Library 3.2.1
   3  * Copyright(c) 2006-2010 Ext JS, Inc.
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**
   8  * @class Ext.Element
   9  * <p>Encapsulates a DOM element, adding simple DOM manipulation facilities, normalizing for browser differences.</p>
  10  * <p>All instances of this class inherit the methods of {@link Ext.Fx} making visual effects easily available to all DOM elements.</p>
  11  * <p>Note that the events documented in this class are not Ext events, they encapsulate browser events. To
  12  * access the underlying browser event, see {@link Ext.EventObject#browserEvent}. Some older
  13  * browsers may not support the full range of events. Which events are supported is beyond the control of ExtJs.</p>
  14  * Usage:<br>
  15 <pre><code>
  16 // by id
  17 var el = Ext.get("my-div");
  18
  19 // by DOM element reference
  20 var el = Ext.get(myDivElement);
  21 </code></pre>
  22  * <b>Animations</b><br />
  23  * <p>When an element is manipulated, by default there is no animation.</p>
  24  * <pre><code>
  25 var el = Ext.get("my-div");
  26
  27 // no animation
  28 el.setWidth(100);
  29  * </code></pre>
  30  * <p>Many of the functions for manipulating an element have an optional "animate" parameter.  This
  31  * parameter can be specified as boolean (<tt>true</tt>) for default animation effects.</p>
  32  * <pre><code>
  33 // default animation
  34 el.setWidth(100, true);
  35  * </code></pre>
  36  *
  37  * <p>To configure the effects, an object literal with animation options to use as the Element animation
  38  * configuration object can also be specified. Note that the supported Element animation configuration
  39  * options are a subset of the {@link Ext.Fx} animation options specific to Fx effects.  The supported
  40  * Element animation configuration options are:</p>
  41 <pre>
  42 Option    Default   Description
  43 --------- --------  ---------------------------------------------
  44 {@link Ext.Fx#duration duration}  .35       The duration of the animation in seconds
  45 {@link Ext.Fx#easing easing}    easeOut   The easing method
  46 {@link Ext.Fx#callback callback}  none      A function to execute when the anim completes
  47 {@link Ext.Fx#scope scope}     this      The scope (this) of the callback function
  48 </pre>
  49  *
  50  * <pre><code>
  51 // Element animation options object
  52 var opt = {
  53     {@link Ext.Fx#duration duration}: 1,
  54     {@link Ext.Fx#easing easing}: 'elasticIn',
  55     {@link Ext.Fx#callback callback}: this.foo,
  56     {@link Ext.Fx#scope scope}: this
  57 };
  58 // animation with some options set
  59 el.setWidth(100, opt);
  60  * </code></pre>
  61  * <p>The Element animation object being used for the animation will be set on the options
  62  * object as "anim", which allows you to stop or manipulate the animation. Here is an example:</p>
  63  * <pre><code>
  64 // using the "anim" property to get the Anim object
  65 if(opt.anim.isAnimated()){
  66     opt.anim.stop();
  67 }
  68  * </code></pre>
  69  * <p>Also see the <tt>{@link #animate}</tt> method for another animation technique.</p>
  70  * <p><b> Composite (Collections of) Elements</b></p>
  71  * <p>For working with collections of Elements, see {@link Ext.CompositeElement}</p>
  72  * @constructor Create a new Element directly.
  73  * @param {String/HTMLElement} element
  74  * @param {Boolean} forceNew (optional) By default the constructor checks to see if there is already an instance of this element in the cache and if there is it returns the same instance. This will skip that check (useful for extending this class).
  75  */
  76 (function(){
  77 var DOC = document;
  78
  79 Ext.Element = function(element, forceNew){
  80     var dom = typeof element == "string" ?
  81               DOC.getElementById(element) : element,
  82         id;
  83
  84     if(!dom) return null;
  85
  86     id = dom.id;
  87
  88     if(!forceNew && id && Ext.elCache[id]){ // element object already exists
  89         return Ext.elCache[id].el;
  90     }
  91
  92     /**
  93      * The DOM element
  94      * @type HTMLElement
  95      */
  96     this.dom = dom;
  97
  98     /**
  99      * The DOM element ID
 100      * @type String
 101      */
 102     this.id = id || Ext.id(dom);
 103 };
 104
 105 var D = Ext.lib.Dom,
 106     DH = Ext.DomHelper,
 107     E = Ext.lib.Event,
 108     A = Ext.lib.Anim,
 109     El = Ext.Element,
 110     EC = Ext.elCache;
 111
 112 El.prototype = {
 113     /**
 114      * Sets the passed attributes as attributes of this element (a style attribute can be a string, object or function)
 115      * @param {Object} o The object with the attributes
 116      * @param {Boolean} useSet (optional) false to override the default setAttribute to use expandos.
 117      * @return {Ext.Element} this
 118      */
 119     set : function(o, useSet){
 120         var el = this.dom,
 121             attr,
 122             val,
 123             useSet = (useSet !== false) && !!el.setAttribute;
 124
 125         for(attr in o){
 126             if (o.hasOwnProperty(attr)) {
 127                 val = o[attr];
 128                 if (attr == 'style') {
 129                     DH.applyStyles(el, val);
 130                 } else if (attr == 'cls') {
 131                     el.className = val;
 132                 } else if (useSet) {
 133                     el.setAttribute(attr, val);
 134                 } else {
 135                     el[attr] = val;
 136                 }
 137             }
 138         }
 139         return this;
 140     },
 141
 142 //  Mouse events
 143     /**
 144      * @event click
 145      * Fires when a mouse click is detected within the element.
 146      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 147      * @param {HtmlElement} t The target of the event.
 148      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 149      */
 150     /**
 151      * @event contextmenu
 152      * Fires when a right click is detected within the element.
 153      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 154      * @param {HtmlElement} t The target of the event.
 155      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 156      */
 157     /**
 158      * @event dblclick
 159      * Fires when a mouse double click is detected within the element.
 160      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 161      * @param {HtmlElement} t The target of the event.
 162      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 163      */
 164     /**
 165      * @event mousedown
 166      * Fires when a mousedown is detected within the element.
 167      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 168      * @param {HtmlElement} t The target of the event.
 169      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 170      */
 171     /**
 172      * @event mouseup
 173      * Fires when a mouseup is detected within the element.
 174      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 175      * @param {HtmlElement} t The target of the event.
 176      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 177      */
 178     /**
 179      * @event mouseover
 180      * Fires when a mouseover is detected within the element.
 181      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 182      * @param {HtmlElement} t The target of the event.
 183      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 184      */
 185     /**
 186      * @event mousemove
 187      * Fires when a mousemove is detected with the element.
 188      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 189      * @param {HtmlElement} t The target of the event.
 190      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 191      */
 192     /**
 193      * @event mouseout
 194      * Fires when a mouseout is detected with the element.
 195      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 196      * @param {HtmlElement} t The target of the event.
 197      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 198      */
 199     /**
 200      * @event mouseenter
 201      * Fires when the mouse enters the element.
 202      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 203      * @param {HtmlElement} t The target of the event.
 204      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 205      */
 206     /**
 207      * @event mouseleave
 208      * Fires when the mouse leaves the element.
 209      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 210      * @param {HtmlElement} t The target of the event.
 211      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 212      */
 213
 214 //  Keyboard events
 215     /**
 216      * @event keypress
 217      * Fires when a keypress is detected within the element.
 218      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 219      * @param {HtmlElement} t The target of the event.
 220      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 221      */
 222     /**
 223      * @event keydown
 224      * Fires when a keydown is detected within the element.
 225      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 226      * @param {HtmlElement} t The target of the event.
 227      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 228      */
 229     /**
 230      * @event keyup
 231      * Fires when a keyup is detected within the element.
 232      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 233      * @param {HtmlElement} t The target of the event.
 234      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 235      */
 236
 237
 238 //  HTML frame/object events
 239     /**
 240      * @event load
 241      * Fires when the user agent finishes loading all content within the element. Only supported by window, frames, objects and images.
 242      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 243      * @param {HtmlElement} t The target of the event.
 244      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 245      */
 246     /**
 247      * @event unload
 248      * Fires when the user agent removes all content from a window or frame. For elements, it fires when the target element or any of its content has been removed.
 249      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 250      * @param {HtmlElement} t The target of the event.
 251      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 252      */
 253     /**
 254      * @event abort
 255      * Fires when an object/image is stopped from loading before completely loaded.
 256      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 257      * @param {HtmlElement} t The target of the event.
 258      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 259      */
 260     /**
 261      * @event error
 262      * Fires when an object/image/frame cannot be loaded properly.
 263      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 264      * @param {HtmlElement} t The target of the event.
 265      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 266      */
 267     /**
 268      * @event resize
 269      * Fires when a document view is resized.
 270      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 271      * @param {HtmlElement} t The target of the event.
 272      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 273      */
 274     /**
 275      * @event scroll
 276      * Fires when a document view is scrolled.
 277      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 278      * @param {HtmlElement} t The target of the event.
 279      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 280      */
 281
 282 //  Form events
 283     /**
 284      * @event select
 285      * Fires when a user selects some text in a text field, including input and textarea.
 286      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 287      * @param {HtmlElement} t The target of the event.
 288      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 289      */
 290     /**
 291      * @event change
 292      * Fires when a control loses the input focus and its value has been modified since gaining focus.
 293      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 294      * @param {HtmlElement} t The target of the event.
 295      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 296      */
 297     /**
 298      * @event submit
 299      * Fires when a form is submitted.
 300      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 301      * @param {HtmlElement} t The target of the event.
 302      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 303      */
 304     /**
 305      * @event reset
 306      * Fires when a form is reset.
 307      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 308      * @param {HtmlElement} t The target of the event.
 309      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 310      */
 311     /**
 312      * @event focus
 313      * Fires when an element receives focus either via the pointing device or by tab navigation.
 314      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 315      * @param {HtmlElement} t The target of the event.
 316      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 317      */
 318     /**
 319      * @event blur
 320      * Fires when an element loses focus either via the pointing device or by tabbing navigation.
 321      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 322      * @param {HtmlElement} t The target of the event.
 323      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 324      */
 325
 326 //  User Interface events
 327     /**
 328      * @event DOMFocusIn
 329      * Where supported. Similar to HTML focus event, but can be applied to any focusable element.
 330      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 331      * @param {HtmlElement} t The target of the event.
 332      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 333      */
 334     /**
 335      * @event DOMFocusOut
 336      * Where supported. Similar to HTML blur event, but can be applied to any focusable element.
 337      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 338      * @param {HtmlElement} t The target of the event.
 339      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 340      */
 341     /**
 342      * @event DOMActivate
 343      * Where supported. Fires when an element is activated, for instance, through a mouse click or a keypress.
 344      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 345      * @param {HtmlElement} t The target of the event.
 346      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 347      */
 348
 349 //  DOM Mutation events
 350     /**
 351      * @event DOMSubtreeModified
 352      * Where supported. Fires when the subtree is modified.
 353      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 354      * @param {HtmlElement} t The target of the event.
 355      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 356      */
 357     /**
 358      * @event DOMNodeInserted
 359      * Where supported. Fires when a node has been added as a child of another node.
 360      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 361      * @param {HtmlElement} t The target of the event.
 362      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 363      */
 364     /**
 365      * @event DOMNodeRemoved
 366      * Where supported. Fires when a descendant node of the element is removed.
 367      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 368      * @param {HtmlElement} t The target of the event.
 369      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 370      */
 371     /**
 372      * @event DOMNodeRemovedFromDocument
 373      * Where supported. Fires when a node is being removed from a document.
 374      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 375      * @param {HtmlElement} t The target of the event.
 376      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 377      */
 378     /**
 379      * @event DOMNodeInsertedIntoDocument
 380      * Where supported. Fires when a node is being inserted into a document.
 381      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 382      * @param {HtmlElement} t The target of the event.
 383      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 384      */
 385     /**
 386      * @event DOMAttrModified
 387      * Where supported. Fires when an attribute has been modified.
 388      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 389      * @param {HtmlElement} t The target of the event.
 390      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 391      */
 392     /**
 393      * @event DOMCharacterDataModified
 394      * Where supported. Fires when the character data has been modified.
 395      * @param {Ext.EventObject} e The {@link Ext.EventObject} encapsulating the DOM event.
 396      * @param {HtmlElement} t The target of the event.
 397      * @param {Object} o The options configuration passed to the {@link #addListener} call.
 398      */
 399
 400     /**
 401      * The default unit to append to CSS values where a unit isn't provided (defaults to px).
 402      * @type String
 403      */
 404     defaultUnit : "px",
 405
 406     /**
 407      * Returns true if this element matches the passed simple selector (e.g. div.some-class or span:first-child)
 408      * @param {String} selector The simple selector to test
 409      * @return {Boolean} True if this element matches the selector, else false
 410      */
 411     is : function(simpleSelector){
 412         return Ext.DomQuery.is(this.dom, simpleSelector);
 413     },
 414
 415     /**
 416      * Tries to focus the element. Any exceptions are caught and ignored.
 417      * @param {Number} defer (optional) Milliseconds to defer the focus
 418      * @return {Ext.Element} this
 419      */
 420     focus : function(defer, /* private */ dom) {
 421         var me = this,
 422             dom = dom || me.dom;
 423         try{
 424             if(Number(defer)){
 425                 me.focus.defer(defer, null, [null, dom]);
 426             }else{
 427                 dom.focus();
 428             }
 429         }catch(e){}
 430         return me;
 431     },
 432
 433     /**
 434      * Tries to blur the element. Any exceptions are caught and ignored.
 435      * @return {Ext.Element} this
 436      */
 437     blur : function() {
 438         try{
 439             this.dom.blur();
 440         }catch(e){}
 441         return this;
 442     },
 443
 444     /**
 445      * Returns the value of the "value" attribute
 446      * @param {Boolean} asNumber true to parse the value as a number
 447      * @return {String/Number}
 448      */
 449     getValue : function(asNumber){
 450         var val = this.dom.value;
 451         return asNumber ? parseInt(val, 10) : val;
 452     },
 453
 454     /**
 455      * Appends an event handler to this element.  The shorthand version {@link #on} is equivalent.
 456      * @param {String} eventName The name of event to handle.
 457      * @param {Function} fn The handler function the event invokes. This function is passed
 458      * the following parameters:<ul>
 459      * <li><b>evt</b> : EventObject<div class="sub-desc">The {@link Ext.EventObject EventObject} describing the event.</div></li>
 460      * <li><b>el</b> : HtmlElement<div class="sub-desc">The DOM element which was the target of the event.
 461      * Note that this may be filtered by using the <tt>delegate</tt> option.</div></li>
 462      * <li><b>o</b> : Object<div class="sub-desc">The options object from the addListener call.</div></li>
 463      * </ul>
 464      * @param {Object} scope (optional) The scope (<code><b>this</b></code> reference) in which the handler function is executed.
 465      * <b>If omitted, defaults to this Element.</b>.
 466      * @param {Object} options (optional) An object containing handler configuration properties.
 467      * This may contain any of the following properties:<ul>
 468      * <li><b>scope</b> Object : <div class="sub-desc">The scope (<code><b>this</b></code> reference) in which the handler function is executed.
 469      * <b>If omitted, defaults to this Element.</b></div></li>
 470      * <li><b>delegate</b> String: <div class="sub-desc">A simple selector to filter the target or look for a descendant of the target. See below for additional details.</div></li>
 471      * <li><b>stopEvent</b> Boolean: <div class="sub-desc">True to stop the event. That is stop propagation, and prevent the default action.</div></li>
 472      * <li><b>preventDefault</b> Boolean: <div class="sub-desc">True to prevent the default action</div></li>
 473      * <li><b>stopPropagation</b> Boolean: <div class="sub-desc">True to prevent event propagation</div></li>
 474      * <li><b>normalized</b> Boolean: <div class="sub-desc">False to pass a browser event to the handler function instead of an Ext.EventObject</div></li>
 475      * <li><b>target</b> Ext.Element: <div class="sub-desc">Only call the handler if the event was fired on the target Element, <i>not</i> if the event was bubbled up from a child node.</div></li>
 476      * <li><b>delay</b> Number: <div class="sub-desc">The number of milliseconds to delay the invocation of the handler after the event fires.</div></li>
 477      * <li><b>single</b> Boolean: <div class="sub-desc">True to add a handler to handle just the next firing of the event, and then remove itself.</div></li>
 478      * <li><b>buffer</b> Number: <div class="sub-desc">Causes the handler to be scheduled to run in an {@link Ext.util.DelayedTask} delayed
 479      * by the specified number of milliseconds. If the event fires again within that time, the original
 480      * handler is <em>not</em> invoked, but the new handler is scheduled in its place.</div></li>
 481      * </ul><br>
 482      * <p>
 483      * <b>Combining Options</b><br>
 484      * In the following examples, the shorthand form {@link #on} is used rather than the more verbose
 485      * addListener.  The two are equivalent.  Using the options argument, it is possible to combine different
 486      * types of listeners:<br>
 487      * <br>
 488      * A delayed, one-time listener that auto stops the event and adds a custom argument (forumId) to the
 489      * options object. The options object is available as the third parameter in the handler function.<div style="margin: 5px 20px 20px;">
 490      * Code:<pre><code>
 491 el.on('click', this.onClick, this, {
 492     single: true,
 493     delay: 100,
 494     stopEvent : true,
 495     forumId: 4
 496 });</code></pre></p>
 497      * <p>
 498      * <b>Attaching multiple handlers in 1 call</b><br>
 499      * The method also allows for a single argument to be passed which is a config object containing properties
 500      * which specify multiple handlers.</p>
 501      * <p>
 502      * Code:<pre><code>
 503 el.on({
 504     'click' : {
 505         fn: this.onClick,
 506         scope: this,
 507         delay: 100
 508     },
 509     'mouseover' : {
 510         fn: this.onMouseOver,
 511         scope: this
 512     },
 513     'mouseout' : {
 514         fn: this.onMouseOut,
 515         scope: this
 516     }
 517 });</code></pre>
 518      * <p>
 519      * Or a shorthand syntax:<br>
 520      * Code:<pre><code></p>
 521 el.on({
 522     'click' : this.onClick,
 523     'mouseover' : this.onMouseOver,
 524     'mouseout' : this.onMouseOut,
 525     scope: this
 526 });
 527      * </code></pre></p>
 528      * <p><b>delegate</b></p>
 529      * <p>This is a configuration option that you can pass along when registering a handler for
 530      * an event to assist with event delegation. Event delegation is a technique that is used to
 531      * reduce memory consumption and prevent exposure to memory-leaks. By registering an event
 532      * for a container element as opposed to each element within a container. By setting this
 533      * configuration option to a simple selector, the target element will be filtered to look for
 534      * a descendant of the target.
 535      * For example:<pre><code>
 536 // using this markup:
 537 &lt;div id='elId'>
 538     &lt;p id='p1'>paragraph one&lt;/p>
 539     &lt;p id='p2' class='clickable'>paragraph two&lt;/p>
 540     &lt;p id='p3'>paragraph three&lt;/p>
 541 &lt;/div>
 542 // utilize event delegation to registering just one handler on the container element:
 543 el = Ext.get('elId');
 544 el.on(
 545     'click',
 546     function(e,t) {
 547         // handle click
 548         console.info(t.id); // 'p2'
 549     },
 550     this,
 551     {
 552         // filter the target element to be a descendant with the class 'clickable'
 553         delegate: '.clickable'
 554     }
 555 );
 556      * </code></pre></p>
 557      * @return {Ext.Element} this
 558      */
 559     addListener : function(eventName, fn, scope, options){
 560         Ext.EventManager.on(this.dom,  eventName, fn, scope || this, options);
 561         return this;
 562     },
 563
 564     /**
 565      * Removes an event handler from this element.  The shorthand version {@link #un} is equivalent.
 566      * <b>Note</b>: if a <i>scope</i> was explicitly specified when {@link #addListener adding} the
 567      * listener, the same scope must be specified here.
 568      * Example:
 569      * <pre><code>
 570 el.removeListener('click', this.handlerFn);
 571 // or
 572 el.un('click', this.handlerFn);
 573 </code></pre>
 574      * @param {String} eventName The name of the event from which to remove the handler.
 575      * @param {Function} fn The handler function to remove. <b>This must be a reference to the function passed into the {@link #addListener} call.</b>
 576      * @param {Object} scope If a scope (<b><code>this</code></b> reference) was specified when the listener was added,
 577      * then this must refer to the same object.
 578      * @return {Ext.Element} this
 579      */
 580     removeListener : function(eventName, fn, scope){
 581         Ext.EventManager.removeListener(this.dom,  eventName, fn, scope || this);
 582         return this;
 583     },
 584
 585     /**
 586      * Removes all previous added listeners from this element
 587      * @return {Ext.Element} this
 588      */
 589     removeAllListeners : function(){
 590         Ext.EventManager.removeAll(this.dom);
 591         return this;
 592     },
 593
 594     /**
 595      * Recursively removes all previous added listeners from this element and its children
 596      * @return {Ext.Element} this
 597      */
 598     purgeAllListeners : function() {
 599         Ext.EventManager.purgeElement(this, true);
 600         return this;
 601     },
 602     /**
 603      * @private Test if size has a unit, otherwise appends the default
 604      */
 605     addUnits : function(size){
 606         if(size === "" || size == "auto" || size === undefined){
 607             size = size || '';
 608         } else if(!isNaN(size) || !unitPattern.test(size)){
 609             size = size + (this.defaultUnit || 'px');
 610         }
 611         return size;
 612     },
 613
 614     /**
 615      * <p>Updates the <a href="http://developer.mozilla.org/en/DOM/element.innerHTML">innerHTML</a> of this Element
 616      * from a specified URL. Note that this is subject to the <a href="http://en.wikipedia.org/wiki/Same_origin_policy">Same Origin Policy</a></p>
 617      * <p>Updating innerHTML of an element will <b>not</b> execute embedded <tt>&lt;script></tt> elements. This is a browser restriction.</p>
 618      * @param {Mixed} options. Either a sring containing the URL from which to load the HTML, or an {@link Ext.Ajax#request} options object specifying
 619      * exactly how to request the HTML.
 620      * @return {Ext.Element} this
 621      */
 622     load : function(url, params, cb){
 623         Ext.Ajax.request(Ext.apply({
 624             params: params,
 625             url: url.url || url,
 626             callback: cb,
 627             el: this.dom,
 628             indicatorText: url.indicatorText || ''
 629         }, Ext.isObject(url) ? url : {}));
 630         return this;
 631     },
 632
 633     /**
 634      * Tests various css rules/browsers to determine if this element uses a border box
 635      * @return {Boolean}
 636      */
 637     isBorderBox : function(){
 638         return noBoxAdjust[(this.dom.tagName || "").toLowerCase()] || Ext.isBorderBox;
 639     },
 640
 641     /**
 642      * <p>Removes this element's dom reference.  Note that event and cache removal is handled at {@link Ext#removeNode}</p>
 643      */
 644     remove : function(){
 645         var me = this,
 646             dom = me.dom;
 647
 648         if (dom) {
 649             delete me.dom;
 650             Ext.removeNode(dom);
 651         }
 652     },
 653
 654     /**
 655      * Sets up event handlers to call the passed functions when the mouse is moved into and out of the Element.
 656      * @param {Function} overFn The function to call when the mouse enters the Element.
 657      * @param {Function} outFn The function to call when the mouse leaves the Element.
 658      * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the functions are executed. Defaults to the Element's DOM element.
 659      * @param {Object} options (optional) Options for the listener. See {@link Ext.util.Observable#addListener the <tt>options</tt> parameter}.
 660      * @return {Ext.Element} this
 661      */
 662     hover : function(overFn, outFn, scope, options){
 663         var me = this;
 664         me.on('mouseenter', overFn, scope || me.dom, options);
 665         me.on('mouseleave', outFn, scope || me.dom, options);
 666         return me;
 667     },
 668
 669     /**
 670      * Returns true if this element is an ancestor of the passed element
 671      * @param {HTMLElement/String} el The element to check
 672      * @return {Boolean} True if this element is an ancestor of el, else false
 673      */
 674     contains : function(el){
 675         return !el ? false : Ext.lib.Dom.isAncestor(this.dom, el.dom ? el.dom : el);
 676     },
 677
 678     /**
 679      * Returns the value of a namespaced attribute from the element's underlying DOM node.
 680      * @param {String} namespace The namespace in which to look for the attribute
 681      * @param {String} name The attribute name
 682      * @return {String} The attribute value
 683      * @deprecated
 684      */
 685     getAttributeNS : function(ns, name){
 686         return this.getAttribute(name, ns);
 687     },
 688
 689     /**
 690      * Returns the value of an attribute from the element's underlying DOM node.
 691      * @param {String} name The attribute name
 692      * @param {String} namespace (optional) The namespace in which to look for the attribute
 693      * @return {String} The attribute value
 694      */
 695     getAttribute : Ext.isIE ? function(name, ns){
 696         var d = this.dom,
 697             type = typeof d[ns + ":" + name];
 698
 699         if(['undefined', 'unknown'].indexOf(type) == -1){
 700             return d[ns + ":" + name];
 701         }
 702         return d[name];
 703     } : function(name, ns){
 704         var d = this.dom;
 705         return d.getAttributeNS(ns, name) || d.getAttribute(ns + ":" + name) || d.getAttribute(name) || d[name];
 706     },
 707
 708     /**
 709     * Update the innerHTML of this element
 710     * @param {String} html The new HTML
 711     * @return {Ext.Element} this
 712      */
 713     update : function(html) {
 714         if (this.dom) {
 715             this.dom.innerHTML = html;
 716         }
 717         return this;
 718     }
 719 };
 720
 721 var ep = El.prototype;
 722
 723 El.addMethods = function(o){
 724    Ext.apply(ep, o);
 725 };
 726
 727 /**
 728  * Appends an event handler (shorthand for {@link #addListener}).
 729  * @param {String} eventName The name of event to handle.
 730  * @param {Function} fn The handler function the event invokes.
 731  * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the handler function is executed.
 732  * @param {Object} options (optional) An object containing standard {@link #addListener} options
 733  * @member Ext.Element
 734  * @method on
 735  */
 736 ep.on = ep.addListener;
 737
 738 /**
 739  * Removes an event handler from this element (see {@link #removeListener} for additional notes).
 740  * @param {String} eventName The name of the event from which to remove the handler.
 741  * @param {Function} fn The handler function to remove. <b>This must be a reference to the function passed into the {@link #addListener} call.</b>
 742  * @param {Object} scope If a scope (<b><code>this</code></b> reference) was specified when the listener was added,
 743  * then this must refer to the same object.
 744  * @return {Ext.Element} this
 745  * @member Ext.Element
 746  * @method un
 747  */
 748 ep.un = ep.removeListener;
 749
 750 /**
 751  * true to automatically adjust width and height settings for box-model issues (default to true)
 752  */
 753 ep.autoBoxAdjust = true;
 754
 755 // private
 756 var unitPattern = /\d+(px|em|%|en|ex|pt|in|cm|mm|pc)$/i,
 757     docEl;
 758
 759 /**
 760  * @private
 761  */
 762
 763 /**
 764  * Retrieves Ext.Element objects.
 765  * <p><b>This method does not retrieve {@link Ext.Component Component}s.</b> This method
 766  * retrieves Ext.Element objects which encapsulate DOM elements. To retrieve a Component by
 767  * its ID, use {@link Ext.ComponentMgr#get}.</p>
 768  * <p>Uses simple caching to consistently return the same object. Automatically fixes if an
 769  * object was recreated with the same id via AJAX or DOM.</p>
 770  * @param {Mixed} el The id of the node, a DOM Node or an existing Element.
 771  * @return {Element} The Element object (or null if no matching element was found)
 772  * @static
 773  * @member Ext.Element
 774  * @method get
 775  */
 776 El.get = function(el){
 777     var ex,
 778         elm,
 779         id;
 780     if(!el){ return null; }
 781     if (typeof el == "string") { // element id
 782         if (!(elm = DOC.getElementById(el))) {
 783             return null;
 784         }
 785         if (EC[el] && EC[el].el) {
 786             ex = EC[el].el;
 787             ex.dom = elm;
 788         } else {
 789             ex = El.addToCache(new El(elm));
 790         }
 791         return ex;
 792     } else if (el.tagName) { // dom element
 793         if(!(id = el.id)){
 794             id = Ext.id(el);
 795         }
 796         if (EC[id] && EC[id].el) {
 797             ex = EC[id].el;
 798             ex.dom = el;
 799         } else {
 800             ex = El.addToCache(new El(el));
 801         }
 802         return ex;
 803     } else if (el instanceof El) {
 804         if(el != docEl){
 805             // refresh dom element in case no longer valid,
 806             // catch case where it hasn't been appended
 807
 808             // If an el instance is passed, don't pass to getElementById without some kind of id
 809             if (Ext.isIE && (el.id == undefined || el.id == '')) {
 810                 el.dom = el.dom;
 811             } else {
 812                 el.dom = DOC.getElementById(el.id) || el.dom;
 813             }
 814         }
 815         return el;
 816     } else if(el.isComposite) {
 817         return el;
 818     } else if(Ext.isArray(el)) {
 819         return El.select(el);
 820     } else if(el == DOC) {
 821         // create a bogus element object representing the document object
 822         if(!docEl){
 823             var f = function(){};
 824             f.prototype = El.prototype;
 825             docEl = new f();
 826             docEl.dom = DOC;
 827         }
 828         return docEl;
 829     }
 830     return null;
 831 };
 832
 833 El.addToCache = function(el, id){
 834     id = id || el.id;
 835     EC[id] = {
 836         el:  el,
 837         data: {},
 838         events: {}
 839     };
 840     return el;
 841 };
 842
 843 // private method for getting and setting element data
 844 El.data = function(el, key, value){
 845     el = El.get(el);
 846     if (!el) {
 847         return null;
 848     }
 849     var c = EC[el.id].data;
 850     if(arguments.length == 2){
 851         return c[key];
 852     }else{
 853         return (c[key] = value);
 854     }
 855 };
 856
 857 // private
 858 // Garbage collection - uncache elements/purge listeners on orphaned elements
 859 // so we don't hold a reference and cause the browser to retain them
 860 function garbageCollect(){
 861     if(!Ext.enableGarbageCollector){
 862         clearInterval(El.collectorThreadId);
 863     } else {
 864         var eid,
 865             el,
 866             d,
 867             o;
 868
 869         for(eid in EC){
 870             o = EC[eid];
 871             if(o.skipGC){
 872                 continue;
 873             }
 874             el = o.el;
 875             d = el.dom;
 876             // -------------------------------------------------------
 877             // Determining what is garbage:
 878             // -------------------------------------------------------
 879             // !d
 880             // dom node is null, definitely garbage
 881             // -------------------------------------------------------
 882             // !d.parentNode
 883             // no parentNode == direct orphan, definitely garbage
 884             // -------------------------------------------------------
 885             // !d.offsetParent && !document.getElementById(eid)
 886             // display none elements have no offsetParent so we will
 887             // also try to look it up by it's id. However, check
 888             // offsetParent first so we don't do unneeded lookups.
 889             // This enables collection of elements that are not orphans
 890             // directly, but somewhere up the line they have an orphan
 891             // parent.
 892             // -------------------------------------------------------
 893             if(!d || !d.parentNode || (!d.offsetParent && !DOC.getElementById(eid))){
 894                 if(Ext.enableListenerCollection){
 895                     Ext.EventManager.removeAll(d);
 896                 }
 897                 delete EC[eid];
 898             }
 899         }
 900         // Cleanup IE Object leaks
 901         if (Ext.isIE) {
 902             var t = {};
 903             for (eid in EC) {
 904                 t[eid] = EC[eid];
 905             }
 906             EC = Ext.elCache = t;
 907         }
 908     }
 909 }
 910 El.collectorThreadId = setInterval(garbageCollect, 30000);
 911
 912 var flyFn = function(){};
 913 flyFn.prototype = El.prototype;
 914
 915 // dom is optional
 916 El.Flyweight = function(dom){
 917     this.dom = dom;
 918 };
 919
 920 El.Flyweight.prototype = new flyFn();
 921 El.Flyweight.prototype.isFlyweight = true;
 922 El._flyweights = {};
 923
 924 /**
 925  * <p>Gets the globally shared flyweight Element, with the passed node as the active element. Do not store a reference to this element -
 926  * the dom node can be overwritten by other code. Shorthand of {@link Ext.Element#fly}</p>
 927  * <p>Use this to make one-time references to DOM elements which are not going to be accessed again either by
 928  * application code, or by Ext's classes. If accessing an element which will be processed regularly, then {@link Ext#get}
 929  * will be more appropriate to take advantage of the caching provided by the Ext.Element class.</p>
 930  * @param {String/HTMLElement} el The dom node or id
 931  * @param {String} named (optional) Allows for creation of named reusable flyweights to prevent conflicts
 932  * (e.g. internally Ext uses "_global")
 933  * @return {Element} The shared Element object (or null if no matching element was found)
 934  * @member Ext.Element
 935  * @method fly
 936  */
 937 El.fly = function(el, named){
 938     var ret = null;
 939     named = named || '_global';
 940
 941     if (el = Ext.getDom(el)) {
 942         (El._flyweights[named] = El._flyweights[named] || new El.Flyweight()).dom = el;
 943         ret = El._flyweights[named];
 944     }
 945     return ret;
 946 };
 947
 948 /**
 949  * Retrieves Ext.Element objects.
 950  * <p><b>This method does not retrieve {@link Ext.Component Component}s.</b> This method
 951  * retrieves Ext.Element objects which encapsulate DOM elements. To retrieve a Component by
 952  * its ID, use {@link Ext.ComponentMgr#get}.</p>
 953  * <p>Uses simple caching to consistently return the same object. Automatically fixes if an
 954  * object was recreated with the same id via AJAX or DOM.</p>
 955  * Shorthand of {@link Ext.Element#get}
 956  * @param {Mixed} el The id of the node, a DOM Node or an existing Element.
 957  * @return {Element} The Element object (or null if no matching element was found)
 958  * @member Ext
 959  * @method get
 960  */
 961 Ext.get = El.get;
 962
 963 /**
 964  * <p>Gets the globally shared flyweight Element, with the passed node as the active element. Do not store a reference to this element -
 965  * the dom node can be overwritten by other code. Shorthand of {@link Ext.Element#fly}</p>
 966  * <p>Use this to make one-time references to DOM elements which are not going to be accessed again either by
 967  * application code, or by Ext's classes. If accessing an element which will be processed regularly, then {@link Ext#get}
 968  * will be more appropriate to take advantage of the caching provided by the Ext.Element class.</p>
 969  * @param {String/HTMLElement} el The dom node or id
 970  * @param {String} named (optional) Allows for creation of named reusable flyweights to prevent conflicts
 971  * (e.g. internally Ext uses "_global")
 972  * @return {Element} The shared Element object (or null if no matching element was found)
 973  * @member Ext
 974  * @method fly
 975  */
 976 Ext.fly = El.fly;
 977
 978 // speedy lookup for elements never to box adjust
 979 var noBoxAdjust = Ext.isStrict ? {
 980     select:1
 981 } : {
 982     input:1, select:1, textarea:1
 983 };
 984 if(Ext.isIE || Ext.isGecko){
 985     noBoxAdjust['button'] = 1;
 986 }
 987
 988 })();