include/javascript/tiny_mce/classes/util/Dispatcher.js

   1 /**
   2  * Dispatcher.js
   3  *
   4  * Copyright 2009, Moxiecode Systems AB
   5  * Released under LGPL License.
   6  *
   7  * License: http://tinymce.moxiecode.com/license
   8  * Contributing: http://tinymce.moxiecode.com/contributing
   9  */
  10
  11 /**
  12  * This class is used to dispatch event to observers/listeners.
  13  * All internal events inside TinyMCE uses this class.
  14  *
  15  * @class tinymce.util.Dispatcher
  16  * @example
  17  * // Creates a custom event
  18  * this.onSomething = new tinymce.util.Dispatcher(this);
  19  *
  20  * // Dispatch/fire the event
  21  * this.onSomething.dispatch('some string');
  22  */
  23 tinymce.create('tinymce.util.Dispatcher', {
  24         scope : null,
  25         listeners : null,
  26
  27         /**
  28          * Constructs a new event dispatcher object.
  29          *
  30          * @constructor
  31          * @method Dispatcher
  32          * @param {Object} s Optional default execution scope for all observer functions.
  33          */
  34         Dispatcher : function(s) {
  35                 this.scope = s || this;
  36                 this.listeners = [];
  37         },
  38
  39         /**
  40          * Add an observer function to be executed when a dispatch call is done.
  41          *
  42          * @method add
  43          * @param {function} cb Callback function to execute when a dispatch event occurs.
  44          * @param {Object} s Optional execution scope, defaults to the one specified in the class constructor.
  45          * @return {function} Returns the same function as the one passed on.
  46          */
  47         add : function(cb, s) {
  48                 this.listeners.push({cb : cb, scope : s || this.scope});
  49
  50                 return cb;
  51         },
  52
  53         /**
  54          * Add an observer function to be executed to the top of the list of observers.
  55          *
  56          * @method addToTop
  57          * @param {function} cb Callback function to execute when a dispatch event occurs.
  58          * @param {Object} s Optional execution scope, defaults to the one specified in the class constructor.
  59          * @return {function} Returns the same function as the one passed on.
  60          */
  61         addToTop : function(cb, s) {
  62                 this.listeners.unshift({cb : cb, scope : s || this.scope});
  63
  64                 return cb;
  65         },
  66
  67         /**
  68          * Removes an observer function.
  69          *
  70          * @method remove
  71          * @param {function} cb Observer function to remove.
  72          * @return {function} The same function that got passed in or null if it wasn't found.
  73          */
  74         remove : function(cb) {
  75                 var l = this.listeners, o = null;
  76
  77                 tinymce.each(l, function(c, i) {
  78                         if (cb == c.cb) {
  79                                 o = cb;
  80                                 l.splice(i, 1);
  81                                 return false;
  82                         }
  83                 });
  84
  85                 return o;
  86         },
  87
  88         /**
  89          * Dispatches an event to all observers/listeners.
  90          *
  91          * @method dispatch
  92          * @param {Object} .. Any number of arguments to dispatch.
  93          * @return {Object} Last observer functions return value.
  94          */
  95         dispatch : function() {
  96                 var s, a = arguments, i, li = this.listeners, c;
  97
  98                 // Needs to be a real loop since the listener count might change while looping
  99                 // And this is also more efficient
 100                 for (i = 0; i<li.length; i++) {
 101                         c = li[i];
 102                         s = c.cb.apply(c.scope, a);
 103
 104                         if (s === false)
 105                                 break;
 106                 }
 107
 108                 return s;
 109         }
 110
 111         /**#@-*/
 112 });