Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / ComponentQuery.html
index a37854c..2b4af6c 100644 (file)
@@ -1,78 +1,87 @@
-<!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-ComponentQuery'>/**
-</span> * @class Ext.ComponentQuery
- * @extends Object
- *
- * Provides searching of Components within Ext.ComponentManager (globally) or a specific
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
+</head>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-ComponentQuery'>/**
+</span> * Provides searching of Components within Ext.ComponentManager (globally) or a specific
  * Ext.container.Container on the document with a similar syntax to a CSS selector.
  *
  * Components can be retrieved by using their {@link Ext.Component xtype} with an optional . prefix
-&lt;ul&gt;
-    &lt;li&gt;component or .component&lt;/li&gt;
-    &lt;li&gt;gridpanel or .gridpanel&lt;/li&gt;
-&lt;/ul&gt;
+ *
+ * - `component` or `.component`
+ * - `gridpanel` or `.gridpanel`
  *
  * An itemId or id must be prefixed with a #
-&lt;ul&gt;
-    &lt;li&gt;#myContainer&lt;/li&gt;
-&lt;/ul&gt;
  *
+ * - `#myContainer`
  *
  * Attributes must be wrapped in brackets
-&lt;ul&gt;
-    &lt;li&gt;component[autoScroll]&lt;/li&gt;
-    &lt;li&gt;panel[title=&quot;Test&quot;]&lt;/li&gt;
-&lt;/ul&gt;
  *
- * Member expressions from candidate Components may be tested. If the expression returns a &lt;i&gt;truthy&lt;/i&gt; value,
- * the candidate Component will be included in the query:&lt;pre&gt;&lt;code&gt;
-var disabledFields = myFormPanel.query(&quot;{isDisabled()}&quot;);
-&lt;/code&gt;&lt;/pre&gt;
+ * - `component[autoScroll]`
+ * - `panel[title=&quot;Test&quot;]`
+ *
+ * Member expressions from candidate Components may be tested. If the expression returns a *truthy* value,
+ * the candidate Component will be included in the query:
+ *
+ *     var disabledFields = myFormPanel.query(&quot;{isDisabled()}&quot;);
+ *
+ * Pseudo classes may be used to filter results in the same way as in {@link Ext.DomQuery DomQuery}:
+ *
+ *     // Function receives array and returns a filtered array.
+ *     Ext.ComponentQuery.pseudos.invalid = function(items) {
+ *         var i = 0, l = items.length, c, result = [];
+ *         for (; i &lt; l; i++) {
+ *             if (!(c = items[i]).isValid()) {
+ *                 result.push(c);
+ *             }
+ *         }
+ *         return result;
+ *     };
+ *      
+ *     var invalidFields = myFormPanel.query('field:invalid');
+ *     if (invalidFields.length) {
+ *         invalidFields[0].getEl().scrollIntoView(myFormPanel.body);
+ *         for (var i = 0, l = invalidFields.length; i &lt; l; i++) {
+ *             invalidFields[i].getEl().frame(&quot;red&quot;);
+ *         }
+ *     }
+ *
+ * Default pseudos include:
  *
- * Pseudo classes may be used to filter results in the same way as in {@link Ext.DomQuery DomQuery}:&lt;code&gt;&lt;pre&gt;
-// Function receives array and returns a filtered array.
-Ext.ComponentQuery.pseudos.invalid = function(items) {
-    var i = 0, l = items.length, c, result = [];
-    for (; i &lt; l; i++) {
-        if (!(c = items[i]).isValid()) {
-            result.push(c);
-        }
-    }
-    return result;
-};
-
-var invalidFields = myFormPanel.query('field:invalid');
-if (invalidFields.length) {
-    invalidFields[0].getEl().scrollIntoView(myFormPanel.body);
-    for (var i = 0, l = invalidFields.length; i &lt; l; i++) {
-        invalidFields[i].getEl().frame(&quot;red&quot;);
-    }
-}
-&lt;/pre&gt;&lt;/code&gt;
- * &lt;p&gt;
- * Default pseudos include:&lt;br /&gt;
  * - not
- * &lt;/p&gt;
+ * - last
  *
  * Queries return an array of components.
  * Here are some example queries.
-&lt;pre&gt;&lt;code&gt;
-    // retrieve all Ext.Panels in the document by xtype
-    var panelsArray = Ext.ComponentQuery.query('panel');
-
-    // retrieve all Ext.Panels within the container with an id myCt
-    var panelsWithinmyCt = Ext.ComponentQuery.query('#myCt panel');
-
-    // retrieve all direct children which are Ext.Panels within myCt
-    var directChildPanel = Ext.ComponentQuery.query('#myCt &gt; panel');
-
-    // retrieve all gridpanels and listviews
-    var gridsAndLists = Ext.ComponentQuery.query('gridpanel, listview');
-&lt;/code&gt;&lt;/pre&gt;
-
-For easy access to queries based from a particular Container see the {@link Ext.container.Container#query},
-{@link Ext.container.Container#down} and {@link Ext.container.Container#child} methods. Also see
-{@link Ext.Component#up}.
- * @singleton
+ *
+ *     // retrieve all Ext.Panels in the document by xtype
+ *     var panelsArray = Ext.ComponentQuery.query('panel');
+ *
+ *     // retrieve all Ext.Panels within the container with an id myCt
+ *     var panelsWithinmyCt = Ext.ComponentQuery.query('#myCt panel');
+ *
+ *     // retrieve all direct children which are Ext.Panels within myCt
+ *     var directChildPanel = Ext.ComponentQuery.query('#myCt &gt; panel');
+ *
+ *     // retrieve all grids and trees
+ *     var gridsAndTrees = Ext.ComponentQuery.query('gridpanel, treepanel');
+ *
+ * For easy access to queries based from a particular Container see the {@link Ext.container.Container#query},
+ * {@link Ext.container.Container#down} and {@link Ext.container.Container#child} methods. Also see
+ * {@link Ext.Component#up}.
  */
 Ext.define('Ext.ComponentQuery', {
     singleton: true,
@@ -235,28 +244,22 @@ Ext.define('Ext.ComponentQuery', {
             method: filterFnPattern
         }];
 
-<span id='Ext-ComponentQuery.Query'>    /**
-</span>     * @class Ext.ComponentQuery.Query
-     * @extends Object
-     * @private
-     */
+    // @class Ext.ComponentQuery.Query
+    // This internal class is completely hidden in documentation.
     cq.Query = Ext.extend(Object, {
         constructor: function(cfg) {
             cfg = cfg || {};
             Ext.apply(this, cfg);
         },
 
-<span id='Ext-ComponentQuery.Query-method-execute'>        /**
-</span>         * @private
-         * Executes this Query upon the selected root.
-         * The root provides the initial source of candidate Component matches which are progressively
-         * filtered by iterating through this Query's operations cache.
-         * If no root is provided, all registered Components are searched via the ComponentManager.
-         * root may be a Container who's descendant Components are filtered
-         * root may be a Component with an implementation of getRefItems which provides some nested Components such as the
-         * docked items within a Panel.
-         * root may be an array of candidate Components to filter using this Query.
-         */
+        // Executes this Query upon the selected root.
+        // The root provides the initial source of candidate Component matches which are progressively
+        // filtered by iterating through this Query's operations cache.
+        // If no root is provided, all registered Components are searched via the ComponentManager.
+        // root may be a Container who's descendant Components are filtered
+        // root may be a Component with an implementation of getRefItems which provides some nested Components such as the
+        // docked items within a Panel.
+        // root may be an array of candidate Components to filter using this Query.
         execute : function(root) {
             var operations = this.operations,
                 i = 0,
@@ -347,21 +350,28 @@ Ext.define('Ext.ComponentQuery', {
                     }
                 }
                 return results;
+            },
+            last: function(components) {
+                return components[components.length - 1];
             }
         },
 
 <span id='Ext-ComponentQuery-method-query'>        /**
-</span>         * &lt;p&gt;Returns an array of matched Components from within the passed root object.&lt;/p&gt;
-         * &lt;p&gt;This method filters returned Components in a similar way to how CSS selector based DOM
-         * queries work using a textual selector string.&lt;/p&gt;
-         * &lt;p&gt;See class summary for details.&lt;/p&gt;
-         * @param selector The selector string to filter returned Components
-         * @param root &lt;p&gt;The Container within which to perform the query. If omitted, all Components
-         * within the document are included in the search.&lt;/p&gt;
-         * &lt;p&gt;This parameter may also be an array of Components to filter according to the selector.&lt;/p&gt;
-         * @returns {Array} The matched Components.
+</span>         * Returns an array of matched Components from within the passed root object.
+         *
+         * This method filters returned Components in a similar way to how CSS selector based DOM
+         * queries work using a textual selector string.
+         *
+         * See class summary for details.
+         *
+         * @param {String} selector The selector string to filter returned Components
+         * @param {Ext.container.Container} root The Container within which to perform the query.
+         * If omitted, all Components within the document are included in the search.
+         * 
+         * This parameter may also be an array of Components to filter according to the selector.&lt;/p&gt;
+         * @returns {Ext.Component[]} The matched Components.
+         * 
          * @member Ext.ComponentQuery
-         * @method query
          */
         query: function(selector, root) {
             var selectors = selector.split(','),
@@ -397,13 +407,12 @@ Ext.define('Ext.ComponentQuery', {
             return results;
         },
 
-<span id='Ext-ComponentQuery-method-query'>        /**
+<span id='Ext-ComponentQuery-method-is'>        /**
 </span>         * Tests whether the passed Component matches the selector string.
-         * @param component The Component to test
-         * @param selector The selector string to test against.
+         * @param {Ext.Component} component The Component to test
+         * @param {String} selector The selector string to test against.
          * @return {Boolean} True if the Component matches the selector.
          * @member Ext.ComponentQuery
-         * @method query
          */
         is: function(component, selector) {
             if (!selector) {
@@ -521,4 +530,6 @@ Ext.define('Ext.ComponentQuery', {
             });
         }
     });
-});</pre></pre></body></html>
\ No newline at end of file
+});</pre>
+</body>
+</html>