X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/c930e9176a5a85509c5b0230e2bff5c22a591432..25ef3491bd9ae007ff1fc2b0d7943e6eaaccf775:/docs/source/MixedCollection.html diff --git a/docs/source/MixedCollection.html b/docs/source/MixedCollection.html index edecd201..613d466e 100644 --- a/docs/source/MixedCollection.html +++ b/docs/source/MixedCollection.html @@ -1,17 +1,24 @@ - - - The source code - - - - - 
/**
+
+
+  The source code
+    
+    
+
+
+    
/*!
+ * Ext JS Library 3.0.3
+ * Copyright(c) 2006-2009 Ext JS, LLC
+ * licensing@extjs.com
+ * http://www.extjs.com/license
+ */
+
/**
  * @class Ext.util.MixedCollection
  * @extends Ext.util.Observable
  * A Collection class that maintains both numeric indexes and keys and exposes events.
  * @constructor
- * @param {Boolean} allowFunctions True if the addAll function should add function references to the
- * collection (defaults to false)
+ * @param {Boolean} allowFunctions Specify true if the {@link #addAll}
+ * function should add function references to the collection. Defaults to
+ * false.
  * @param {Function} keyFn A function that can accept an item of the type(s) stored in this MixedCollection
  * and return the key value for that item.  This is used when available to look up the key on items that
  * were passed without an explicit key parameter to a MixedCollection method.  Passing this parameter is
@@ -27,7 +34,7 @@ Ext.util.MixedCollection = function(allowFunctions, keyFn){
          * @event clear
          * Fires when the collection is cleared.
          */
-        "clear",
+        'clear',
         
/**
          * @event add
          * Fires when an item is added to the collection.
@@ -35,7 +42,7 @@ Ext.util.MixedCollection = function(allowFunctions, keyFn){
          * @param {Object} o The item added.
          * @param {String} key The key associated with the added item.
          */
-        "add",
+        'add',
         
/**
          * @event replace
          * Fires when an item is replaced in the collection.
@@ -43,15 +50,15 @@ Ext.util.MixedCollection = function(allowFunctions, keyFn){
          * @param {Object} old The item being replaced.
          * @param {Object} new The new item.
          */
-        "replace",
+        'replace',
         
/**
          * @event remove
          * Fires when an item is removed from the collection.
          * @param {Object} o The item being removed.
          * @param {String} key (optional) The key associated with the removed item.
          */
-        "remove",
-        "sort"
+        'remove',
+        'sort'
     );
     this.allowFunctions = allowFunctions === true;
     if(keyFn){
@@ -61,19 +68,25 @@ Ext.util.MixedCollection = function(allowFunctions, keyFn){
 };
 
 Ext.extend(Ext.util.MixedCollection, Ext.util.Observable, {
+
+    
/**
+     * @cfg {Boolean} allowFunctions Specify true if the {@link #addAll}
+     * function should add function references to the collection. Defaults to
+     * false.
+     */
     allowFunctions : false,
 
-
/**
- * Adds an item to the collection. Fires the {@link #add} event when complete.
- * @param {String} key 
The key to associate with the item, or the new item.

- * 
If you supplied a {@link #getKey} implementation for this MixedCollection, or if the key
- * of your stored items is in a property called id, then the MixedCollection
- * will be able to derive the key for the new item. In this case just pass the new item in
- * this parameter.

- * @param {Object} o The item to add.
- * @return {Object} The item added.
- */
-    add: function(key, o){
+    
/**
+     * Adds an item to the collection. Fires the {@link #add} event when complete.
+     * @param {String} key 
The key to associate with the item, or the new item.

+     * 
If a {@link #getKey} implementation was specified for this MixedCollection,
+     * or if the key of the stored items is in a property called id,
+     * the MixedCollection will be able to derive the key for the new item.
+     * In this case just pass the new item in this parameter.

+     * @param {Object} o The item to add.
+     * @return {Object} The item added.
+     */
+    add : function(key, o){
         if(arguments.length == 1){
             o = arguments[0];
             key = this.getKey(o);
@@ -92,11 +105,10 @@ Ext.extend(Ext.util.MixedCollection, Ext.util.Observable, {
         return o;
     },
 
-
/**
-  * MixedCollection has a generic way to fetch keys if you implement getKey.  The default implementation
-  * simply returns item.id but you can provide your own implementation
-  * to return a different value as in the following examples:
-

+    
/**
+      * MixedCollection has a generic way to fetch keys if you implement getKey.  The default implementation
+      * simply returns item.id but you can provide your own implementation
+      * to return a different value as in the following examples:

 // normal way
 var mc = new Ext.util.MixedCollection();
 mc.add(someEl.dom.id, someEl);
@@ -117,46 +129,48 @@ var mc = new Ext.util.MixedCollection(false, function(el){
 });
 mc.add(someEl);
 mc.add(otherEl);
-

- * @param {Object} item The item for which to find the key.
- * @return {Object} The key for the passed item.
- */
+     * 

+     * @param {Object} item The item for which to find the key.
+     * @return {Object} The key for the passed item.
+     */
     getKey : function(o){
          return o.id;
     },
 
-
/**
- * Replaces an item in the collection. Fires the {@link #replace} event when complete.
- * @param {String} key 
The key associated with the item to replace, or the replacement item.

- * 
If you supplied a {@link #getKey} implementation for this MixedCollection, or if the key
- * of your stored items is in a property called id, then the MixedCollection
- * will be able to derive the key of the replacement item. If you want to replace an item
- * with one having the same key value, then just pass the replacement item in this parameter.

- * @param o {Object} o (optional) If the first parameter passed was a key, the item to associate
- * with that key.
- * @return {Object}  The new item.
- */
+    
/**
+     * Replaces an item in the collection. Fires the {@link #replace} event when complete.
+     * @param {String} key 
The key associated with the item to replace, or the replacement item.

+     * 
If you supplied a {@link #getKey} implementation for this MixedCollection, or if the key
+     * of your stored items is in a property called id, then the MixedCollection
+     * will be able to derive the key of the replacement item. If you want to replace an item
+     * with one having the same key value, then just pass the replacement item in this parameter.

+     * @param o {Object} o (optional) If the first parameter passed was a key, the item to associate
+     * with that key.
+     * @return {Object}  The new item.
+     */
     replace : function(key, o){
         if(arguments.length == 1){
             o = arguments[0];
             key = this.getKey(o);
         }
         var old = this.map[key];
-        if(typeof key == "undefined" || key === null || typeof old == "undefined"){
+        if(typeof key == 'undefined' || key === null || typeof old == 'undefined'){
              return this.add(key, o);
         }
         var index = this.indexOfKey(key);
         this.items[index] = o;
         this.map[key] = o;
-        this.fireEvent("replace", key, old, o);
+        this.fireEvent('replace', key, old, o);
         return o;
     },
 
-
/**
- * Adds all elements of an Array or an Object to the collection.
- * @param {Object/Array} objs An Object containing properties which will be added to the collection, or
- * an Array of values, each of which are added to the collection.
- */
+    
/**
+     * Adds all elements of an Array or an Object to the collection.
+     * @param {Object/Array} objs An Object containing properties which will be added
+     * to the collection, or an Array of values, each of which are added to the collection.
+     * Functions references will be added to the collection if {@link #allowFunctions}
+     * has been set to true.
+     */
     addAll : function(objs){
         if(arguments.length > 1 || Ext.isArray(objs)){
             var args = arguments.length > 1 ? arguments : objs;
@@ -165,24 +179,24 @@ mc.add(otherEl);
             }
         }else{
             for(var key in objs){
-                if(this.allowFunctions || typeof objs[key] != "function"){
+                if(this.allowFunctions || typeof objs[key] != 'function'){
                     this.add(key, objs[key]);
                 }
             }
         }
     },
 
-
/**
- * Executes the specified function once for every item in the collection, passing the following arguments:
- * 
    
- * 
  • item : Mixed
    The collection item
    • 
- * 
  • index : Number
    The item's index
    • 
- * 
  • length : Number
    The total number of items in the collection
    • 
- * 

- * The function should return a boolean value. Returning false from the function will stop the iteration.
- * @param {Function} fn The function to execute for each item.
- * @param {Object} scope (optional) The scope in which to execute the function.
- */
+    
/**
+     * Executes the specified function once for every item in the collection, passing the following arguments:
+     * 
    
+     * 
  • item : Mixed
    The collection item
    • 
+     * 
  • index : Number
    The item's index
    • 
+     * 
  • length : Number
    The total number of items in the collection
    • 
+     * 

+     * The function should return a boolean value. Returning false from the function will stop the iteration.
+     * @param {Function} fn The function to execute for each item.
+     * @param {Object} scope (optional) The scope in which to execute the function.
+     */
     each : function(fn, scope){
         var items = [].concat(this.items); // each safe for removal
         for(var i = 0, len = items.length; i < len; i++){
@@ -192,12 +206,12 @@ mc.add(otherEl);
         }
     },
 
-
/**
- * Executes the specified function once for every key in the collection, passing each
- * key, and its associated item as the first two parameters.
- * @param {Function} fn The function to execute for each item.
- * @param {Object} scope (optional) The scope in which to execute the function.
- */
+    
/**
+     * Executes the specified function once for every key in the collection, passing each
+     * key, and its associated item as the first two parameters.
+     * @param {Function} fn The function to execute for each item.
+     * @param {Object} scope (optional) The scope in which to execute the function.
+     */
     eachKey : function(fn, scope){
         for(var i = 0, len = this.keys.length; i < len; i++){
             fn.call(scope || window, this.keys[i], this.items[i], i, len);
@@ -220,13 +234,13 @@ mc.add(otherEl);
         return null;
     },
 
-
/**
- * Inserts an item at the specified index in the collection. Fires the {@link #add} event when complete.
- * @param {Number} index The index to insert the item at.
- * @param {String} key The key to associate with the new item, or the item itself.
- * @param {Object} o (optional) If the second parameter was a key, the new item.
- * @return {Object} The item inserted.
- */
+    
/**
+     * Inserts an item at the specified index in the collection. Fires the {@link #add} event when complete.
+     * @param {Number} index The index to insert the item at.
+     * @param {String} key The key to associate with the new item, or the item itself.
+     * @param {Object} o (optional) If the second parameter was a key, the new item.
+     * @return {Object} The item inserted.
+     */
     insert : function(index, key, o){
         if(arguments.length == 2){
             o = arguments[1];
@@ -242,160 +256,167 @@ mc.add(otherEl);
         }
         this.length++;
         this.items.splice(index, 0, o);
-        if(typeof key != "undefined" && key !== null){
+        if(typeof key != 'undefined' && key !== null){
             this.map[key] = o;
         }
         this.keys.splice(index, 0, key);
-        this.fireEvent("add", index, o, key);
+        this.fireEvent('add', index, o, key);
         return o;
     },
 
-
/**
- * Remove an item from the collection.
- * @param {Object} o The item to remove.
- * @return {Object} The item removed or false if no item was removed.
- */
+    
/**
+     * Remove an item from the collection.
+     * @param {Object} o The item to remove.
+     * @return {Object} The item removed or false if no item was removed.
+     */
     remove : function(o){
         return this.removeAt(this.indexOf(o));
     },
 
-
/**
- * Remove an item from a specified index in the collection. Fires the {@link #remove} event when complete.
- * @param {Number} index The index within the collection of the item to remove.
- * @return {Object} The item removed or false if no item was removed.
- */
+    
/**
+     * Remove an item from a specified index in the collection. Fires the {@link #remove} event when complete.
+     * @param {Number} index The index within the collection of the item to remove.
+     * @return {Object} The item removed or false if no item was removed.
+     */
     removeAt : function(index){
         if(index < this.length && index >= 0){
             this.length--;
             var o = this.items[index];
             this.items.splice(index, 1);
             var key = this.keys[index];
-            if(typeof key != "undefined"){
+            if(typeof key != 'undefined'){
                 delete this.map[key];
             }
             this.keys.splice(index, 1);
-            this.fireEvent("remove", o, key);
+            this.fireEvent('remove', o, key);
             return o;
         }
         return false;
     },
 
-
/**
- * Removed an item associated with the passed key fom the collection.
- * @param {String} key The key of the item to remove.
- * @return {Object} The item removed or false if no item was removed.
- */
+    
/**
+     * Removed an item associated with the passed key fom the collection.
+     * @param {String} key The key of the item to remove.
+     * @return {Object} The item removed or false if no item was removed.
+     */
     removeKey : function(key){
         return this.removeAt(this.indexOfKey(key));
     },
 
-
/**
- * Returns the number of items in the collection.
- * @return {Number} the number of items in the collection.
- */
+    
/**
+     * Returns the number of items in the collection.
+     * @return {Number} the number of items in the collection.
+     */
     getCount : function(){
         return this.length;
     },
-
-
/**
- * Returns index within the collection of the passed Object.
- * @param {Object} o The item to find the index of.
- * @return {Number} index of the item. Returns -1 if not found.
- */
+    
+    
/**
+     * Returns index within the collection of the passed Object.
+     * @param {Object} o The item to find the index of.
+     * @return {Number} index of the item. Returns -1 if not found.
+     */
     indexOf : function(o){
         return this.items.indexOf(o);
     },
 
-
/**
- * Returns index within the collection of the passed key.
- * @param {String} key The key to find the index of.
- * @return {Number} index of the key.
- */
+    
/**
+     * Returns index within the collection of the passed key.
+     * @param {String} key The key to find the index of.
+     * @return {Number} index of the key.
+     */
     indexOfKey : function(key){
         return this.keys.indexOf(key);
     },
 
-
/**
- * Returns the item associated with the passed key OR index. Key has priority over index.  This is the equivalent
- * of calling {@link #key} first, then if nothing matched calling {@link #itemAt}.
- * @param {String/Number} key The key or index of the item.
- * @return {Object} If the item is found, returns the item.  If the item was not found, returns undefined.
- * If an item was found, but is a Class, returns null.
- */
+    
/**
+     * Returns the item associated with the passed key OR index.
+     * Key has priority over index.  This is the equivalent
+     * of calling {@link #key} first, then if nothing matched calling {@link #itemAt}.
+     * @param {String/Number} key The key or index of the item.
+     * @return {Object} If the item is found, returns the item.  If the item was not found, returns undefined.
+     * If an item was found, but is a Class, returns null.
+     */
     item : function(key){
         var mk = this.map[key],
             item = mk !== undefined ? mk : (typeof key == 'number') ? this.items[key] : undefined;
         return !Ext.isFunction(item) || this.allowFunctions ? item : null; // for prototype!
     },
 
-
/**
- * Returns the item at the specified index.
- * @param {Number} index The index of the item.
- * @return {Object} The item at the specified index.
- */
+    
/**
+     * Returns the item at the specified index.
+     * @param {Number} index The index of the item.
+     * @return {Object} The item at the specified index.
+     */
     itemAt : function(index){
         return this.items[index];
     },
 
-
/**
- * Returns the item associated with the passed key.
- * @param {String/Number} key The key of the item.
- * @return {Object} The item associated with the passed key.
- */
+    
/**
+     * Returns the item associated with the passed key.
+     * @param {String/Number} key The key of the item.
+     * @return {Object} The item associated with the passed key.
+     */
     key : function(key){
         return this.map[key];
     },
 
-
/**
- * Returns true if the collection contains the passed Object as an item.
- * @param {Object} o  The Object to look for in the collection.
- * @return {Boolean} True if the collection contains the Object as an item.
- */
+    
/**
+     * Returns true if the collection contains the passed Object as an item.
+     * @param {Object} o  The Object to look for in the collection.
+     * @return {Boolean} True if the collection contains the Object as an item.
+     */
     contains : function(o){
         return this.indexOf(o) != -1;
     },
 
-
/**
- * Returns true if the collection contains the passed Object as a key.
- * @param {String} key The key to look for in the collection.
- * @return {Boolean} True if the collection contains the Object as a key.
- */
+    
/**
+     * Returns true if the collection contains the passed Object as a key.
+     * @param {String} key The key to look for in the collection.
+     * @return {Boolean} True if the collection contains the Object as a key.
+     */
     containsKey : function(key){
-        return typeof this.map[key] != "undefined";
+        return typeof this.map[key] != 'undefined';
     },
 
-
/**
- * Removes all items from the collection.  Fires the {@link #clear} event when complete.
- */
+    
/**
+     * Removes all items from the collection.  Fires the {@link #clear} event when complete.
+     */
     clear : function(){
         this.length = 0;
         this.items = [];
         this.keys = [];
         this.map = {};
-        this.fireEvent("clear");
+        this.fireEvent('clear');
     },
 
-
/**
- * Returns the first item in the collection.
- * @return {Object} the first item in the collection..
- */
+    
/**
+     * Returns the first item in the collection.
+     * @return {Object} the first item in the collection..
+     */
     first : function(){
         return this.items[0];
     },
 
-
/**
- * Returns the last item in the collection.
- * @return {Object} the last item in the collection..
- */
+    
/**
+     * Returns the last item in the collection.
+     * @return {Object} the last item in the collection..
+     */
     last : function(){
         return this.items[this.length-1];
     },
 
-    // private
+    /**
+     * @private
+     * @param {String} property Property to sort by ('key', 'value', or 'index')
+     * @param {String} dir (optional) Direction to sort 'ASC' or 'DESC'. Defaults to 'ASC'.
+     * @param {Function} fn (optional) Comparison function that defines the sort order.
+     * Defaults to sorting by numeric value.  
+     */
     _sort : function(property, dir, fn){
         var i,
             len,
-            dsc = String(dir).toUpperCase() == "DESC" ? -1 : 1,
+            dsc = String(dir).toUpperCase() == 'DESC' ? -1 : 1,
             c = [], k = this.keys, items = this.items;
             
         fn = fn || function(a, b){
@@ -415,25 +436,27 @@ mc.add(otherEl);
             items[i] = c[i].value;
             k[i] = c[i].key;
         }
-        this.fireEvent("sort", this);
+        this.fireEvent('sort', this);
     },
 
     
/**
-     * Sorts this collection with the passed comparison function
-     * @param {String} direction (optional) "ASC" or "DESC"
-     * @param {Function} fn (optional) comparison function
+     * Sorts this collection by item value with the passed comparison function.
+     * @param {String} direction (optional) 'ASC' or 'DESC'. Defaults to 'ASC'.
+     * @param {Function} fn (optional) Comparison function that defines the sort order.
+     * Defaults to sorting by numeric value.  
      */
     sort : function(dir, fn){
-        this._sort("value", dir, fn);
+        this._sort('value', dir, fn);
     },
 
     
/**
-     * Sorts this collection by keys
-     * @param {String} direction (optional) "ASC" or "DESC"
-     * @param {Function} fn (optional) a comparison function (defaults to case insensitive string)
+     * Sorts this collection by keys.
+     * @param {String} direction (optional) 'ASC' or 'DESC'. Defaults to 'ASC'.
+     * @param {Function} fn (optional) Comparison function that defines the sort order.
+     * Defaults to sorting by case insensitive string.  
      */
     keySort : function(dir, fn){
-        this._sort("key", dir, fn || function(a, b){
+        this._sort('key', dir, fn || function(a, b){
             var v1 = String(a).toUpperCase(), v2 = String(b).toUpperCase();
             return v1 > v2 ? 1 : (v1 < v2 ? -1 : 0);
         });
@@ -441,8 +464,8 @@ mc.add(otherEl);
 
     
/**
      * Returns a range of items in this collection
-     * @param {Number} startIndex (optional) defaults to 0
-     * @param {Number} endIndex (optional) default to the last item
+     * @param {Number} startIndex (optional) The starting index. Defaults to 0.
+     * @param {Number} endIndex (optional) The ending index. Defaults to the last item.
      * @return {Array} An array of items
      */
     getRange : function(start, end){
@@ -451,7 +474,7 @@ mc.add(otherEl);
             return [];
         }
         start = start || 0;
-        end = Math.min(typeof end == "undefined" ? this.length-1 : end, this.length-1);
+        end = Math.min(typeof end == 'undefined' ? this.length-1 : end, this.length-1);
         var i, r = [];
         if(start <= end){
             for(i = start; i <= end; i++) {
@@ -568,12 +591,14 @@ mc.add(otherEl);
 });
 
/**
  * This method calls {@link #item item()}.
- * Returns the item associated with the passed key OR index. Key has priority over index.  This is the equivalent
- * of calling {@link #key} first, then if nothing matched calling {@link #itemAt}.
+ * Returns the item associated with the passed key OR index. Key has priority
+ * over index.  This is the equivalent of calling {@link #key} first, then if
+ * nothing matched calling {@link #itemAt}.
  * @param {String/Number} key The key or index of the item.
- * @return {Object} If the item is found, returns the item.  If the item was not found, returns undefined.
- * If an item was found, but is a Class, returns null.
+ * @return {Object} If the item is found, returns the item.  If the item was
+ * not found, returns undefined. If an item was found, but is a Class,
+ * returns null.
  */
-Ext.util.MixedCollection.prototype.get = Ext.util.MixedCollection.prototype.item;
    
-
+Ext.util.MixedCollection.prototype.get = Ext.util.MixedCollection.prototype.item;
+ \ No newline at end of file