git.roojs.org Git - roojs1/blob - Roo/util/Observable.js

   1 /*
   2  * Based on:
   3  * Ext JS Library 1.1.1
   4  * Copyright(c) 2006-2007, Ext JS, LLC.
   5  *
   6  * Originally Released Under LGPL - original licence link has changed is not relivant.
   7  *
   8  * Fork - LGPL
   9  * <script type="text/javascript">
  10  */
  11
  12 /**
  13  * @class Roo.util.Observable
  14  * Base class that provides a common interface for publishing events. Subclasses are expected to
  15  * to have a property "events" with all the events defined.<br>
  16  * For example:
  17  * <pre><code>
  18  Employee = function(name){
  19     this.name = name;
  20     this.addEvents({
  21         "fired" : true,
  22         "quit" : true
  23     });
  24  }
  25  Roo.extend(Employee, Roo.util.Observable);
  26 </code></pre>
  27  * @param {Object} config properties to use (incuding events / listeners)
  28  */
  29
  30 Roo.util.Observable = function(cfg){
  31
  32     cfg = cfg|| {};
  33     this.addEvents(cfg.events || {});
  34     if (cfg.events) {
  35         delete cfg.events; // make sure
  36     }
  37
  38     Roo.apply(this, cfg);
  39
  40     if(this.listeners){
  41         this.on(this.listeners);
  42         delete this.listeners;
  43     }
  44 };
  45 Roo.util.Observable.prototype = {
  46     /**
  47  * @cfg {Object} listeners  list of events and functions to call for this object,
  48  * For example :
  49  * <pre><code>
  50     listeners :  {
  51        'click' : function(e) {
  52            .....
  53         } ,
  54         ....
  55     }
  56   </code></pre>
  57  */
  58
  59
  60     /**
  61      * Fires the specified event with the passed parameters (minus the event name).
  62      * @param {String} eventName
  63      * @param {Object...} args Variable number of parameters are passed to handlers
  64      * @return {Boolean} returns false if any of the handlers return false otherwise it returns true
  65      */
  66     fireEvent : function(){
  67         var ce = this.events[arguments[0].toLowerCase()];
  68         if(typeof ce == "object"){
  69             return ce.fire.apply(ce, Array.prototype.slice.call(arguments, 1));
  70         }else{
  71             return true;
  72         }
  73     },
  74
  75     // private
  76     filterOptRe : /^(?:scope|delay|buffer|single)$/,
  77
  78     /**
  79      * Appends an event handler to this component
  80      * @param {String}   eventName The type of event to listen for
  81      * @param {Function} handler The method the event invokes
  82      * @param {Object}   scope (optional) The scope in which to execute the handler
  83      * function. The handler function's "this" context.
  84      * @param {Object}   options (optional) An object containing handler configuration
  85      * properties. This may contain any of the following properties:<ul>
  86      * <li>scope {Object} The scope in which to execute the handler function. The handler function's "this" context.</li>
  87      * <li>delay {Number} The number of milliseconds to delay the invocation of the handler after te event fires.</li>
  88      * <li>single {Boolean} True to add a handler to handle just the next firing of the event, and then remove itself.</li>
  89      * <li>buffer {Number} Causes the handler to be scheduled to run in an {@link Roo.util.DelayedTask} delayed
  90      * by the specified number of milliseconds. If the event fires again within that time, the original
  91      * handler is <em>not</em> invoked, but the new handler is scheduled in its place.</li>
  92      * </ul><br>
  93      * <p>
  94      * <b>Combining Options</b><br>
  95      * Using the options argument, it is possible to combine different types of listeners:<br>
  96      * <br>
  97      * A normalized, delayed, one-time listener that auto stops the event and passes a custom argument (forumId)
  98                 <pre><code>
  99                 el.on('click', this.onClick, this, {
 100                         single: true,
 101                 delay: 100,
 102                 forumId: 4
 103                 });
 104                 </code></pre>
 105      * <p>
 106      * <b>Attaching multiple handlers in 1 call</b><br>
 107      * The method also allows for a single argument to be passed which is a config object containing properties
 108      * which specify multiple handlers.
 109      * <pre><code>
 110                 el.on({
 111                         'click': {
 112                         fn: this.onClick,
 113                         scope: this,
 114                         delay: 100
 115                 },
 116                 'mouseover': {
 117                         fn: this.onMouseOver,
 118                         scope: this
 119                 },
 120                 'mouseout': {
 121                         fn: this.onMouseOut,
 122                         scope: this
 123                 }
 124                 });
 125                 </code></pre>
 126      * <p>
 127      * Or a shorthand syntax which passes the same scope object to all handlers:
 128         <pre><code>
 129                 el.on({
 130                         'click': this.onClick,
 131                 'mouseover': this.onMouseOver,
 132                 'mouseout': this.onMouseOut,
 133                 scope: this
 134                 });
 135                 </code></pre>
 136      */
 137     addListener : function(eventName, fn, scope, o){
 138         if(typeof eventName == "object"){
 139             o = eventName;
 140             for(var e in o){
 141                 if(this.filterOptRe.test(e)){
 142                     continue;
 143                 }
 144                 if(typeof o[e] == "function"){
 145                     // shared options
 146                     this.addListener(e, o[e], o.scope,  o);
 147                 }else{
 148                     // individual options
 149                     this.addListener(e, o[e].fn, o[e].scope, o[e]);
 150                 }
 151             }
 152             return;
 153         }
 154         o = (!o || typeof o == "boolean") ? {} : o;
 155         eventName = eventName.toLowerCase();
 156         var ce = this.events[eventName] || true;
 157         if(typeof ce == "boolean"){
 158             ce = new Roo.util.Event(this, eventName);
 159             this.events[eventName] = ce;
 160         }
 161         ce.addListener(fn, scope, o);
 162     },
 163
 164     /**
 165      * Removes a listener
 166      * @param {String}   eventName     The type of event to listen for
 167      * @param {Function} handler        The handler to remove
 168      * @param {Object}   scope  (optional) The scope (this object) for the handler
 169      */
 170     removeListener : function(eventName, fn, scope){
 171         var ce = this.events[eventName.toLowerCase()];
 172         if(typeof ce == "object"){
 173             ce.removeListener(fn, scope);
 174         }
 175     },
 176
 177     /**
 178      * Removes all listeners for this object
 179      */
 180     purgeListeners : function(){
 181         for(var evt in this.events){
 182             if(typeof this.events[evt] == "object"){
 183                  this.events[evt].clearListeners();
 184             }
 185         }
 186     },
 187
 188     relayEvents : function(o, events){
 189         var createHandler = function(ename){
 190             return function(){
 191                 return this.fireEvent.apply(this, Roo.combine(ename, Array.prototype.slice.call(arguments, 0)));
 192             };
 193         };
 194         for(var i = 0, len = events.length; i < len; i++){
 195             var ename = events[i];
 196             if(!this.events[ename]){ this.events[ename] = true; };
 197             o.on(ename, createHandler(ename), this);
 198         }
 199     },
 200
 201     /**
 202      * Used to define events on this Observable
 203      * @param {Object} object The object with the events defined
 204      */
 205     addEvents : function(o){
 206         if(!this.events){
 207             this.events = {};
 208         }
 209         Roo.applyIf(this.events, o);
 210     },
 211
 212     /**
 213      * Checks to see if this object has any listeners for a specified event
 214      * @param {String} eventName The name of the event to check for
 215      * @return {Boolean} True if the event is being listened for, else false
 216      */
 217     hasListener : function(eventName){
 218         var e = this.events[eventName];
 219         return typeof e == "object" && e.listeners.length > 0;
 220     }
 221 };
 222 /**
 223  * Appends an event handler to this element (shorthand for addListener)
 224  * @param {String}   eventName     The type of event to listen for
 225  * @param {Function} handler        The method the event invokes
 226  * @param {Object}   scope (optional) The scope in which to execute the handler
 227  * function. The handler function's "this" context.
 228  * @param {Object}   options  (optional)
 229  * @method
 230  */
 231 Roo.util.Observable.prototype.on = Roo.util.Observable.prototype.addListener;
 232 /**
 233  * Removes a listener (shorthand for removeListener)
 234  * @param {String}   eventName     The type of event to listen for
 235  * @param {Function} handler        The handler to remove
 236  * @param {Object}   scope  (optional) The scope (this object) for the handler
 237  * @method
 238  */
 239 Roo.util.Observable.prototype.un = Roo.util.Observable.prototype.removeListener;
 240
 241 /**
 242  * Starts capture on the specified Observable. All events will be passed
 243  * to the supplied function with the event name + standard signature of the event
 244  * <b>before</b> the event is fired. If the supplied function returns false,
 245  * the event will not fire.
 246  * @param {Observable} o The Observable to capture
 247  * @param {Function} fn The function to call
 248  * @param {Object} scope (optional) The scope (this object) for the fn
 249  * @static
 250  */
 251 Roo.util.Observable.capture = function(o, fn, scope){
 252     o.fireEvent = o.fireEvent.createInterceptor(fn, scope);
 253 };
 254
 255 /**
 256  * Removes <b>all</b> added captures from the Observable.
 257  * @param {Observable} o The Observable to release
 258  * @static
 259  */
 260 Roo.util.Observable.releaseCapture = function(o){
 261     o.fireEvent = Roo.util.Observable.prototype.fireEvent;
 262 };
 263
 264 (function(){
 265
 266     var createBuffered = function(h, o, scope){
 267         var task = new Roo.util.DelayedTask();
 268         return function(){
 269             task.delay(o.buffer, h, scope, Array.prototype.slice.call(arguments, 0));
 270         };
 271     };
 272
 273     var createSingle = function(h, e, fn, scope){
 274         return function(){
 275             e.removeListener(fn, scope);
 276             return h.apply(scope, arguments);
 277         };
 278     };
 279
 280     var createDelayed = function(h, o, scope){
 281         return function(){
 282             var args = Array.prototype.slice.call(arguments, 0);
 283             setTimeout(function(){
 284                 h.apply(scope, args);
 285             }, o.delay || 10);
 286         };
 287     };
 288
 289     Roo.util.Event = function(obj, name){
 290         this.name = name;
 291         this.obj = obj;
 292         this.listeners = [];
 293     };
 294
 295     Roo.util.Event.prototype = {
 296         addListener : function(fn, scope, options){
 297             var o = options || {};
 298             scope = scope || this.obj;
 299             if(!this.isListening(fn, scope)){
 300                 var l = {fn: fn, scope: scope, options: o};
 301                 var h = fn;
 302                 if(o.delay){
 303                     h = createDelayed(h, o, scope);
 304                 }
 305                 if(o.single){
 306                     h = createSingle(h, this, fn, scope);
 307                 }
 308                 if(o.buffer){
 309                     h = createBuffered(h, o, scope);
 310                 }
 311                 l.fireFn = h;
 312                 if(!this.firing){ // if we are currently firing this event, don't disturb the listener loop
 313                     this.listeners.push(l);
 314                 }else{
 315                     this.listeners = this.listeners.slice(0);
 316                     this.listeners.push(l);
 317                 }
 318             }
 319         },
 320
 321         findListener : function(fn, scope){
 322             scope = scope || this.obj;
 323             var ls = this.listeners;
 324             for(var i = 0, len = ls.length; i < len; i++){
 325                 var l = ls[i];
 326                 if(l.fn == fn && l.scope == scope){
 327                     return i;
 328                 }
 329             }
 330             return -1;
 331         },
 332
 333         isListening : function(fn, scope){
 334             return this.findListener(fn, scope) != -1;
 335         },
 336
 337         removeListener : function(fn, scope){
 338             var index;
 339             if((index = this.findListener(fn, scope)) != -1){
 340                 if(!this.firing){
 341                     this.listeners.splice(index, 1);
 342                 }else{
 343                     this.listeners = this.listeners.slice(0);
 344                     this.listeners.splice(index, 1);
 345                 }
 346                 return true;
 347             }
 348             return false;
 349         },
 350
 351         clearListeners : function(){
 352             this.listeners = [];
 353         },
 354
 355         fire : function(){
 356             var ls = this.listeners, scope, len = ls.length;
 357             if(len > 0){
 358                 this.firing = true;
 359                 var args = Array.prototype.slice.call(arguments, 0);
 360                 for(var i = 0; i < len; i++){
 361                     var l = ls[i];
 362                     if(l.fireFn.apply(l.scope||this.obj||window, arguments) === false){
 363                         this.firing = false;
 364                         return false;
 365                     }
 366                 }
 367                 this.firing = false;
 368             }
 369             return true;
 370         }
 371     };
 372 })();