lib/dijit/WidgetSet.js.uncompressed.js

   1 define("dijit/WidgetSet", [
   2         "dojo/_base/array", // array.forEach array.map
   3         "dojo/_base/declare", // declare
   4         "dojo/_base/kernel", // kernel.global
   5         "./registry"    // to add functions to dijit.registry
   6 ], function(array, declare, kernel, registry){
   7
   8         // module:
   9         //              dijit/WidgetSet
  10
  11         var WidgetSet = declare("dijit.WidgetSet", null, {
  12                 // summary:
  13                 //              A set of widgets indexed by id.
  14                 //              Deprecated, will be removed in 2.0.
  15                 //
  16                 // example:
  17                 //              Create a small list of widgets:
  18                 //              |       require(["dijit/WidgetSet", "dijit/registry"],
  19                 //              |               function(WidgetSet, registry){
  20                 //              |               var ws = new WidgetSet();
  21                 //              |               ws.add(registry.byId("one"));
  22                 //              |               ws.add(registry.byId("two"));
  23                 //              |               // destroy both:
  24                 //              |               ws.forEach(function(w){ w.destroy(); });
  25                 //              |       });
  26
  27                 constructor: function(){
  28                         this._hash = {};
  29                         this.length = 0;
  30                 },
  31
  32                 add: function(/*dijit/_WidgetBase*/ widget){
  33                         // summary:
  34                         //              Add a widget to this list. If a duplicate ID is detected, a error is thrown.
  35                         //
  36                         // widget: dijit/_WidgetBase
  37                         //              Any dijit/_WidgetBase subclass.
  38                         if(this._hash[widget.id]){
  39                                 throw new Error("Tried to register widget with id==" + widget.id + " but that id is already registered");
  40                         }
  41                         this._hash[widget.id] = widget;
  42                         this.length++;
  43                 },
  44
  45                 remove: function(/*String*/ id){
  46                         // summary:
  47                         //              Remove a widget from this WidgetSet. Does not destroy the widget; simply
  48                         //              removes the reference.
  49                         if(this._hash[id]){
  50                                 delete this._hash[id];
  51                                 this.length--;
  52                         }
  53                 },
  54
  55                 forEach: function(/*Function*/ func, /* Object? */thisObj){
  56                         // summary:
  57                         //              Call specified function for each widget in this set.
  58                         //
  59                         // func:
  60                         //              A callback function to run for each item. Is passed the widget, the index
  61                         //              in the iteration, and the full hash, similar to `array.forEach`.
  62                         //
  63                         // thisObj:
  64                         //              An optional scope parameter
  65                         //
  66                         // example:
  67                         //              Using the default `dijit.registry` instance:
  68                         //              |       require(["dijit/WidgetSet", "dijit/registry"],
  69                         //              |               function(WidgetSet, registry){
  70                         //              |               registry.forEach(function(widget){
  71                         //              |                       console.log(widget.declaredClass);
  72                         //              |               });
  73                         //              |       });
  74                         //
  75                         // returns:
  76                         //              Returns self, in order to allow for further chaining.
  77
  78                         thisObj = thisObj || kernel.global;
  79                         var i = 0, id;
  80                         for(id in this._hash){
  81                                 func.call(thisObj, this._hash[id], i++, this._hash);
  82                         }
  83                         return this;    // dijit/WidgetSet
  84                 },
  85
  86                 filter: function(/*Function*/ filter, /* Object? */thisObj){
  87                         // summary:
  88                         //              Filter down this WidgetSet to a smaller new WidgetSet
  89                         //              Works the same as `array.filter` and `NodeList.filter`
  90                         //
  91                         // filter:
  92                         //              Callback function to test truthiness. Is passed the widget
  93                         //              reference and the pseudo-index in the object.
  94                         //
  95                         // thisObj: Object?
  96                         //              Option scope to use for the filter function.
  97                         //
  98                         // example:
  99                         //              Arbitrary: select the odd widgets in this list
 100                         //              |
 101                         //              |
 102                         //              |
 103                         //              |       require(["dijit/WidgetSet", "dijit/registry"],
 104                         //              |               function(WidgetSet, registry){
 105                         //              |               registry.filter(function(w, i){
 106                         //              |                       return i % 2 == 0;
 107                         //              |               }).forEach(function(w){ /* odd ones */ });
 108                         //              |       });
 109
 110                         thisObj = thisObj || kernel.global;
 111                         var res = new WidgetSet(), i = 0, id;
 112                         for(id in this._hash){
 113                                 var w = this._hash[id];
 114                                 if(filter.call(thisObj, w, i++, this._hash)){
 115                                         res.add(w);
 116                                 }
 117                         }
 118                         return res; // dijit/WidgetSet
 119                 },
 120
 121                 byId: function(/*String*/ id){
 122                         // summary:
 123                         //              Find a widget in this list by it's id.
 124                         // example:
 125                         //              Test if an id is in a particular WidgetSet
 126                         //              |       require(["dijit/WidgetSet", "dijit/registry"],
 127                         //              |               function(WidgetSet, registry){
 128                         //              |               var ws = new WidgetSet();
 129                         //              |               ws.add(registry.byId("bar"));
 130                         //              |               var t = ws.byId("bar") // returns a widget
 131                         //              |               var x = ws.byId("foo"); // returns undefined
 132                         //              |       });
 133
 134                         return this._hash[id];  // dijit/_WidgetBase
 135                 },
 136
 137                 byClass: function(/*String*/ cls){
 138                         // summary:
 139                         //              Reduce this widgetset to a new WidgetSet of a particular `declaredClass`
 140                         //
 141                         // cls: String
 142                         //              The Class to scan for. Full dot-notated string.
 143                         //
 144                         // example:
 145                         //              Find all `dijit.TitlePane`s in a page:
 146                         //              |       require(["dijit/WidgetSet", "dijit/registry"],
 147                         //              |               function(WidgetSet, registry){
 148                         //              |               registry.byClass("dijit.TitlePane").forEach(function(tp){ tp.close(); });
 149                         //              |       });
 150
 151                         var res = new WidgetSet(), id, widget;
 152                         for(id in this._hash){
 153                                 widget = this._hash[id];
 154                                 if(widget.declaredClass == cls){
 155                                         res.add(widget);
 156                                 }
 157                          }
 158                          return res; // dijit/WidgetSet
 159                 },
 160
 161                 toArray: function(){
 162                         // summary:
 163                         //              Convert this WidgetSet into a true Array
 164                         //
 165                         // example:
 166                         //              Work with the widget .domNodes in a real Array
 167                         //              |       require(["dijit/WidgetSet", "dijit/registry"],
 168                         //              |               function(WidgetSet, registry){
 169                         //              |               array.map(registry.toArray(), function(w){ return w.domNode; });
 170                         //              |       });
 171
 172
 173                         var ar = [];
 174                         for(var id in this._hash){
 175                                 ar.push(this._hash[id]);
 176                         }
 177                         return ar;      // dijit/_WidgetBase[]
 178                 },
 179
 180                 map: function(/* Function */func, /* Object? */thisObj){
 181                         // summary:
 182                         //              Create a new Array from this WidgetSet, following the same rules as `array.map`
 183                         // example:
 184                         //              |       require(["dijit/WidgetSet", "dijit/registry"],
 185                         //              |               function(WidgetSet, registry){
 186                         //              |               var nodes = registry.map(function(w){ return w.domNode; });
 187                         //              |       });
 188                         //
 189                         // returns:
 190                         //              A new array of the returned values.
 191                         return array.map(this.toArray(), func, thisObj); // Array
 192                 },
 193
 194                 every: function(func, thisObj){
 195                         // summary:
 196                         //              A synthetic clone of `array.every` acting explicitly on this WidgetSet
 197                         //
 198                         // func: Function
 199                         //              A callback function run for every widget in this list. Exits loop
 200                         //              when the first false return is encountered.
 201                         //
 202                         // thisObj: Object?
 203                         //              Optional scope parameter to use for the callback
 204
 205                         thisObj = thisObj || kernel.global;
 206                         var x = 0, i;
 207                         for(i in this._hash){
 208                                 if(!func.call(thisObj, this._hash[i], x++, this._hash)){
 209                                         return false; // Boolean
 210                                 }
 211                         }
 212                         return true; // Boolean
 213                 },
 214
 215                 some: function(func, thisObj){
 216                         // summary:
 217                         //              A synthetic clone of `array.some` acting explicitly on this WidgetSet
 218                         //
 219                         // func: Function
 220                         //              A callback function run for every widget in this list. Exits loop
 221                         //              when the first true return is encountered.
 222                         //
 223                         // thisObj: Object?
 224                         //              Optional scope parameter to use for the callback
 225
 226                         thisObj = thisObj || kernel.global;
 227                         var x = 0, i;
 228                         for(i in this._hash){
 229                                 if(func.call(thisObj, this._hash[i], x++, this._hash)){
 230                                         return true; // Boolean
 231                                 }
 232                         }
 233                         return false; // Boolean
 234                 }
 235
 236         });
 237
 238         // Add in 1.x compatibility methods to dijit/registry.
 239         // These functions won't show up in the API doc but since they are deprecated anyway,
 240         // that's probably for the best.
 241         array.forEach(["forEach", "filter", "byClass", "map", "every", "some"], function(func){
 242                 registry[func] = WidgetSet.prototype[func];
 243         });
 244
 245
 246         return WidgetSet;
 247 });