Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / src / core / src / dom / CompositeElement.js
1 /**
2  * @class Ext.CompositeElement
3  * @extends Ext.CompositeElementLite
4  * <p>This class encapsulates a <i>collection</i> of DOM elements, providing methods to filter
5  * members, or to perform collective actions upon the whole set.</p>
6  * <p>Although they are not listed, this class supports all of the methods of {@link Ext.core.Element} and
7  * {@link Ext.fx.Anim}. The methods from these classes will be performed on all the elements in this collection.</p>
8  * <p>All methods return <i>this</i> and can be chained.</p>
9  * Usage:
10 <pre><code>
11 var els = Ext.select("#some-el div.some-class", true);
12 // or select directly from an existing element
13 var el = Ext.get('some-el');
14 el.select('div.some-class', true);
15
16 els.setWidth(100); // all elements become 100 width
17 els.hide(true); // all elements fade out and hide
18 // or
19 els.setWidth(100).hide(true);
20 </code></pre>
21  */
22 Ext.CompositeElement = Ext.extend(Ext.CompositeElementLite, {
23     
24     constructor : function(els, root){
25         this.elements = [];
26         this.add(els, root);
27     },
28     
29     // private
30     getElement : function(el){
31         // In this case just return it, since we already have a reference to it
32         return el;
33     },
34     
35     // private
36     transformElement : function(el){
37         return Ext.get(el);
38     }
39
40     /**
41     * Adds elements to this composite.
42     * @param {String/Array} els A string CSS selector, an array of elements or an element
43     * @return {CompositeElement} this
44     */
45
46     /**
47      * Returns the Element object at the specified index
48      * @param {Number} index
49      * @return {Ext.core.Element}
50      */
51
52     /**
53      * Iterates each `element` in this `composite` calling the supplied function using {@link Ext#each Ext.each}.
54      * @param {Function} fn 
55
56 The function to be called with each
57 `element`. If the supplied function returns <tt>false</tt>,
58 iteration stops. This function is called with the following arguments:
59
60 - `element` : __Ext.core.Element++
61     The element at the current `index` in the `composite`
62     
63 - `composite` : __Object__ 
64     This composite.
65
66 - `index` : __Number__ 
67     The current index within the `composite`
68
69      * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the specified function is executed.
70      * Defaults to the <code>element</code> at the current <code>index</code>
71      * within the composite.
72      * @return {CompositeElement} this
73      * @markdown
74      */
75 });
76
77 /**
78  * Selects elements based on the passed CSS selector to enable {@link Ext.core.Element Element} methods
79  * to be applied to many related elements in one statement through the returned {@link Ext.CompositeElement CompositeElement} or
80  * {@link Ext.CompositeElementLite CompositeElementLite} object.
81  * @param {String/Array} selector The CSS selector or an array of elements
82  * @param {Boolean} unique (optional) true to create a unique Ext.core.Element for each element (defaults to a shared flyweight object)
83  * @param {HTMLElement/String} root (optional) The root element of the query or id of the root
84  * @return {CompositeElementLite/CompositeElement}
85  * @member Ext.core.Element
86  * @method select
87  */
88 Ext.core.Element.select = function(selector, unique, root){
89     var els;
90     if(typeof selector == "string"){
91         els = Ext.core.Element.selectorFunction(selector, root);
92     }else if(selector.length !== undefined){
93         els = selector;
94     }else{
95         //<debug>
96         Ext.Error.raise({
97             sourceClass: "Ext.core.Element",
98             sourceMethod: "select",
99             selector: selector,
100             unique: unique,
101             root: root,
102             msg: "Invalid selector specified: " + selector
103         });
104         //</debug>
105     }
106     return (unique === true) ? new Ext.CompositeElement(els) : new Ext.CompositeElementLite(els);
107 };
108
109 /**
110  * Selects elements based on the passed CSS selector to enable {@link Ext.core.Element Element} methods
111  * to be applied to many related elements in one statement through the returned {@link Ext.CompositeElement CompositeElement} or
112  * {@link Ext.CompositeElementLite CompositeElementLite} object.
113  * @param {String/Array} selector The CSS selector or an array of elements
114  * @param {Boolean} unique (optional) true to create a unique Ext.core.Element for each element (defaults to a shared flyweight object)
115  * @param {HTMLElement/String} root (optional) The root element of the query or id of the root
116  * @return {CompositeElementLite/CompositeElement}
117  * @member Ext
118  * @method select
119  */
120 Ext.select = Ext.core.Element.select;