X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/c930e9176a5a85509c5b0230e2bff5c22a591432..25ef3491bd9ae007ff1fc2b0d7943e6eaaccf775:/src/util/MixedCollection.js
diff --git a/src/util/MixedCollection.js b/src/util/MixedCollection.js
index 0847d50a..8a90c21e 100644
--- a/src/util/MixedCollection.js
+++ b/src/util/MixedCollection.js
@@ -1,5 +1,5 @@
/*!
- * Ext JS Library 3.0.0
+ * Ext JS Library 3.0.3
* Copyright(c) 2006-2009 Ext JS, LLC
* licensing@extjs.com
* http://www.extjs.com/license
@@ -9,8 +9,9 @@
* @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
@@ -26,7 +27,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.
@@ -34,7 +35,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.
@@ -42,15 +43,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){
@@ -60,19 +61,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);
@@ -91,11 +98,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);
@@ -116,46 +122,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;
@@ -164,24 +172,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:
- *
- * 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:
+ *
+ * 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++){
@@ -191,12 +199,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);
@@ -219,13 +227,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];
@@ -241,160 +249,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){
@@ -414,25 +429,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);
});
@@ -440,8 +457,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){
@@ -450,7 +467,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++) {
@@ -567,10 +584,12 @@ 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;
\ No newline at end of file