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

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