src/core/src/dom/CompositeElement.js

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