Class: EventDispatcher

EventDispatcher

Class to be extended by classes requiring multiple listeners support. The dispatcher can act in two different ways, either synchronously (all listeners are triggered before the dispatching method exits) or asynchonously (all the listeners are triggered only when the currently running code has been executed).
When extending this class is a good idea to also prepare an empty fake class to act as interface to keep track of the events that will be generated.

new EventDispatcher()

This constructor simply calls the initDispatcher method. This class is supposed to be extended using Inheritance extension. It can be either light extended or fully extended. When light extension is performed the initDispatcher method should be called in the extended class constructor.
Example
//using light extension
define(["Inheritance","EventDispatcher"],function(Inheritance,EventDispatcher) {
  
  var MyClass = function() {
    this.initDispatcher();
    //do stuff
  }
  
  MyClass.prototype = {
    foo: function() {
      //still doing stuff
      
      //send an eventName event to the listeners (their eventName method will be called)
      this.dispatchEvent("eventName",[paramForHandlers,otherParamForHandlers]);
      
      //do more stuff
    }
  };
  
  Inheritance(MyClass,EventDispatcher,true);
  return MyClass;
});

define([],function() {
  
  var MyClassListener = function() {
    //do stuff
  }
  
  MyClassListener = {
    eventName: function(param1,param2) {
      //handle event
    }
  };
  
  return MyClassListener;
});

Method Summary

addListener
Adds a listener and fires the onListenStart event to it sending itself as only parameter.
dispatchEvent
Fires an event on all the listeners.
getListeners
Returns an array containing the currently active listeners.
initDispatcher
Initializes the required internal structures and configures the dispatcher for sending asynchronous events.
removeListener
Removes a listener and fires the onListenEnd event to it sending itself as only parameter.
useSynchEvents
Configures the EventDispatcher to send either synchronous or asynchronous events.

Method Detail

addListener(aListener)

Adds a listener and fires the onListenStart event to it sending itself as only parameter. Note that the onListenStart event is only fired on the involved listener not on previously registered listeners.
Parameters:
Name Type Description
aListener EventDispatcherListener a listener to receive events notifications. The listener does not need to implement all of the possible events: missing events will not be fired on it.

dispatchEvent(evt, params)

Fires an event on all the listeners.
Parameters:
Name Type Argument Description
evt String The name of the event to be fired. A method with this name will be called on the listeners.
params Array <optional>
An array of objects to be used as parameters for the functions handling the event.
See:
  • useSynchEvents

getListeners() → {Array.<EventDispatcherListener>}

Returns an array containing the currently active listeners.
Returns:
an array of listeners.
Type
Array.<EventDispatcherListener>

<protected> initDispatcher()

Initializes the required internal structures and configures the dispatcher for sending asynchronous events.
If called more than once it will reset the status of the instance.
This method MUST be called at least once before event dispatching can be exploited, otherwise most methods will fail either silently or with unexpected exceptions as no init-checks are performed by them.
See:
  • useSynchEvents

removeListener(aListener)

Removes a listener and fires the onListenEnd event to it sending itself as only parameter. Note that the onListenEnd event is only fired on the involved listener not on previously registered listeners.
Parameters:
Name Type Description
aListener EventDispatcherListener the listener to be removed.

useSynchEvents(useSynch)

Configures the EventDispatcher to send either synchronous or asynchronous events.
Synchronous events are fired on listeners before the EventDispatcher#dispatchEvent call of the related event is returned.
Asynchronous events are fired after the current code block is completed and possibly after more code blocks are executed. Can be considered as if the calls are performed inside setTimeout with timeout 0.
Parameters:
Name Type Argument Default Description
useSynch Boolean <optional>
false true to fire events synchronously, any other value to fire them asynchronously.
See:
  • initDispatcher