Upgrade to ExtJS 3.3.0 - Released 10/06/2010
[extjs.git] / 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.0
11  * Copyright(c) 2006-2010 Ext JS, Inc.
12  * licensing@extjs.com
13  * http://www.extjs.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>