docs/source/Element.html

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