UWA Class: UWA.Dispatcher

new UWA.Dispatcher()

Dispatcher API for inspired by AS3-Signals (e.g Could be use to implement event or messaging systems).

Examples:

Setup code (required for all examples)

   //store local reference for brevity
   var Dispatcher = UWA.Dispatcher;

   //custom object that dispatch dispatchers
   var myObject = {
     started: new Dispatcher(), //past tense is the recommended dispatcher naming convention
     stopped: new Dispatcher()
   };

Basic Examples

Single Listener

   function onStarted(param1, param2){
     alert(param1 + param2);
   }
   myObject.started.add(onStarted); //add listener
   myObject.started.dispatch(['foo', 'bar']); //dispatch dispatcher passing custom parameters
   myObject.started.remove(onStarted); //remove a single listener

Multiple Listeners

   function onStopped(){
     alert('stopped');
   }
   function onStopped2(){
     alert('stopped listener 2');
   }
   myObject.stopped.add(onStopped);
   myObject.stopped.add(onStopped2);
   myObject.stopped.dispatch();
   myObject.stopped.removeAll(); //remove all listeners of the `stopped` dispatcher

Multiple Dispatchs

   var i = 0;
   myObject.started.add(function(){
     i += 1;
     alert(i);
   });
   myObject.started.dispatch(); //will alert 1
   myObject.started.dispatch(); //will alert 2

Multiple Dispatchs + addOnce()

   var i = 0;
   myObject.started.addOnce(function(){
     i += 1;
     alert(i);
   });
   myObject.started.dispatch(); //will alert 1
   myObject.started.dispatch(); //nothing happens

Enable/Disable Dispatcher

   var i = 0;
   myObject.started.add(function(){
     i += 1;
     alert(i);
   });
   myObject.started.dispatch(); //will alert 1
   myObject.started.active = `false`;
   myObject.started.dispatch(); //nothing happens
   myObject.started.active = `true`;
   myObject.started.dispatch(); //will alert 2

Stop/Halt Propagation (method 1)

   myObject.started.add(function(){
     myObject.started.halt(); //prevent next listeners on the queue from being executed
   });
   myObject.started.add(function(){
     alert('second listener'); //won't be called since first listener stops propagation
   });
   myObject.started.dispatch();

Stop/Halt Propagation (method 2)

   myObject.started.add(function(){
     return `false`; //if handler returns ``false`` will also stop propagation
   });
   myObject.started.add(function(){
     alert('second listener'); //won't be called since first listener stops propagation
   });
   myObject.started.dispatch();

Set execution context of the listener handler

   var foo = 'bar';
   var obj = {
     foo : 10
   };

   function handler1(){
     alert(this.foo);
   }
   function handler2(){
     alert(this.foo);
   }
   //note that you cannot add the same handler twice to the same dispatcher without removing it first
   myObject.started.add(handler1); //default execution context
   myObject.started.add(handler2, obj); //set a different execution context
   myObject.started.dispatch(); //first handler will alert "bar", second will alert "10".

Advanced Examples:

Set listener priority/order

   var handler1 = function(){
     alert('foo');
   };
   var handler2 = function(){
     alert('bar');
   };
   myObject.started.add(handler1); //default priority is 0
   myObject.started.add(handler2, null, 2); //setting priority to 2 will make `handler2` execute before `handler1`
   myObject.started.dispatch(); //will alert "bar" than "foo"

Enable/Disable a single DisPatcher.Binding

   var handler1 = function(){
     alert('foo bar');
   };
   var handler2 = function(){
     alert('lorem ipsum');
   };
   var binding1 = myObject.started.add(handler1); //methods `add()` and `addOnce()` returns a DisPatcher.Binding object
   myObject.started.add(handler2);
   myObject.started.dispatch(); //will alert "foo bar" than "lorem ipsum"
   binding1.active = `false`; //disable a single binding
   myObject.started.dispatch(); //will alert "lorem ipsum"
   binding1.active = `true`;
   myObject.started.dispatch(); //will alert "foo bar" than "lorem ipsum"

Manually execute a dispatcher handler

   var handler = function(){
     alert('foo bar');
   };
   var binding = myObject.started.add(handler); //methods `add()` and `addOnce()` returns a DisPatcher.Binding object
   binding.execute(); //will alert "foo bar"

Retrieve anonymous listener

   var binding = myObject.started.add(function(){
     alert('foo bar');
   });
   var handler = binding.getListener(); //reference to the anonymous function

Remove / Detach anonymous listener

   var binding = myObject.started.add(function(){
     alert('foo bar');
   });
   myObject.started.dispatch(); //will alert "foo bar"
   binding.detach();
   myObject.started.dispatch(); //nothing happens

Check if binding will execute only once

   var binding1 = myObject.started.add(function(){
     alert('foo bar');
   });
   var binding2 = myObject.started.addOnce(function(){
     alert('foo bar');
   });
   alert(binding1.isOnce); //alert "`false`"
   alert(binding2.isOnce); //alert "`true`"

Change listener execution context on-the-fly

   var foo = 'bar';
   var obj = {
     foo : "it's over 9000!"
   };
   var binding = myObject.started.add(function(){
     alert(this.foo);
   });
   myObject.started.dispatch(); //will alert "bar"
   binding.context = obj;
   myObject.started.dispatch(); //will alert "it's over 9000!"

See:

Index

Methods

registerListener
addBinding
indexOfListener
add
addOnce
remove
removeAll
getNumListeners
getListeners
halt
dispatch
dispose
toString

Members

Binding :Class

Class to use for bindings. It should extend Dispatcher.Binding (defaults to Dispatcher.Binding)

Type

Class

bindings :Array

Array of UWA.Dispatcher.Binding instances attached to the current dispatcher instance.

Type

Array

shouldPropagate :Boolean

Define if dispatcher should dispatch to next listeners on the queue.

Type

Boolean

active :Boolean

If Dispatcher is active and should broadcast events.

Note: Setting this property during a dispatch will only affect the next dispatch, if you want to stop the propagation of a dispatcher use halt() instead.

Type

Boolean

dispatching :Number

If Dispatcher is dispatching and should prevent bindings alteration.

Type

Number

Methods

registerListener(listener, isOnce, context, priority) → {Object}

Listeners with higher priority will be executed before listeners with lower priority. Listeners with same priority level will be executed at the same order as they were added.

Parameters

Name	Type	Argument	Default	Description
`listener`	Object			Dispatcher handler function or object implementing the EventListener interface
`isOnce`	Boolean			If should be removed after first execution (default = `false`)
`context`	Object			Context on which listener will be executed (override EventListener context if defined)
`priority`	Number	<optional>	0	The priority level of the event listener

Returns

An Object representing the binding between the Dispatcher and listener.

Type: Object

addBinding(binding)

Add listener to the bindings array and sort bindings by priority.

Parameters

Name	Type	Description
`binding`	Function	Instance of UWA.Dispatcher.Binding has to be added to the Dispatcher current instance.

indexOfListener(listener, context) → {Number}

Get listener index position.

Parameters

Name	Type	Description
`listener`	Function	Handler function that should match index.
`context`	Void	Object that should match binding associated to listener context if provided.

Returns

Listener index position.

Type: Number

add(listener, context, priority) → {Object}

Add a listener to the dispatcher.

Listeners with same priority level will be executed at the same order as they were added. Listeners with higher priority will be executed before listeners with lower priority. Scope is object that should represent the this variable inside listener function.

Parameters

Name	Type	Argument	Default	Description
`listener`	Function			Dispatcher handler function
`context`	Object			Context on which listener will be executed
`priority`	Number	<optional>	0	The priority level of the event listener

Returns

An Object representing the binding between the Dispatcher and listener.

Type: Object

addOnce(listener, context, priority) → {Object}

Add listener to the dispatcher that should be removed after first execution.

Listeners with same priority level will be executed at the same order as they were added. Listeners with higher priority will be executed before listeners with lower priority.

Parameters

Name	Type	Argument	Default	Description
`listener`	Function			Dispatcher handler function
`context`	Object			Context on which listener will be executed (object that should represent the `this` variable inside listener function)
`priority`	Number	<optional>	0	The priority level of the event listener

Returns

An Object representing the binding between the Dispatcher and listener.

Type: Object

remove(listener, context) → {Function}

Remove a single listener from the dispatch queue.

Parameters

Name	Type	Description
`listener`	Function	Handler function that should be removed.
`context`	Void	Object that should match binding associated to listener context if provided.

Returns

Listener handler function.

Type: Function

removeAll(context)

Remove all listeners from the Dispatcher.

Parameters

Name	Type	Description
`context`	Void	Object that should match binding associated to listener context if provided.

getNumListeners() → {Number}

Number of listeners attached to the Dispatcher.

Returns

Number of listeners attached to the Dispatcher.

Type: Number

getListeners() → {Array}

Get the list of listeners attached to the Dispatcher.

Returns

Listeners attached to the Dispatcher.

Type: Array

halt()

Stop propagation of the event, blocking the dispatch to next listeners on the queue.

Should be called only during dispatcher dispatch, calling it before/after dispatch won't affect dispatcher broadcast see shouldPropagate property.

dispatch(params, context)

Dispatch/Broadcast Dispatcher to all listeners added to the queue.

Parameters

Name	Type	Description
`params`	Array	Array of parameters that should be passed to each handler
`context`	Object	Context that should be used by each handler

dispose()

Remove all bindings from dispatcher and destroy any reference to external objects.

Calling any method on the dispatcher instance after calling dispose will throw errors.

toString() → {String}

Get String representation of the object.

Returns

String representation of the object.

Internal or advanced use only.

Type: String