Module: UWA/Class/Listener

 TODO

Index

Methods

listenTo(observable, name, callback, priority) → {this}

Listen to a particular event emitted by an object implementing UWA.Class.Events.

This is indeed the inversion-of-control version of UWA.Class.Events.addEvent. The advantage of using this form, instead of observable.addEvent(name, listener, this), is that listenTo allows this listening object to keep track of the listened events, and they can be removed all at once later on.

Note that the listener callback function passed as input argument will always be called with this caller Listener object as context.

listenTo has two different signatures, as illustrated in the example below : either with the observed emitter object, the name of the event, the callback function and an optional priority or with the observed emitter object and an hash of { eventName: callback } pairs. Note that with the later form, no priority can be specified.

listenTo is meant to be used in your code in conjunction with stopListening.

Example

var myObserver, myObservable;

myObserver = new UWA.Class.Listener();
myObservable = new UWA.Class.Events();

myObserver.listenTo(myObservable, 'someEvent', function () {
    UWA.log('Some event occurred!');
});
myObserver.listenTo(myObservable, {
    someOtherEvent: function () {
        UWA.log('Some other event occurred!');
    },
    andSomethingElse: function () {
        UWA.log('Something else to take care of...');
    }
});
myObserver.stopListening();

Parameters

Name	Type	Argument	Default	Description
observable	Object			the observed emitter object, must implement UWA.Class.Events
name	String | Object			the name (string) of the listened event or a hash of {event: callback} pairs
callback	Function	<optional>		the listener callback, if name argument is a string.
priority	Number	<optional>	0	the priority level of the listener, if name argument is a string. 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.

Returns

Type

this

listenToOnce(observable, name, callback, priority) → {this}

Just like listenTo, but causes the bound callback to only fire once before being removed.

This is indeed the inversion-of-control version of <UWA.Class.Events.addEventOnce>.

Note that the listener callback function will always be called with this caller Listener object as context.

There are two ways to call listenToOnce, as illustrated in the example below : either with the observed emitter object, the name of the event, the callback function and the optional priority or with the observed emitter object and an hash of { eventName: callback } pairs. Note that with the later form, no priority can be specified.

Example

var myObserver, myObservable;

myObserver = new UWA.Class.Listener();
myObservable = new UWA.Class.Events();

myObserver.listenToOnce(myObservable, 'someEvent', function () {
    UWA.log('Some event occurred!');
});
myObserver.listenToOnce(myObservable, {
    someOtherEvent: function () {
        UWA.log('Some other event occurred!');
    },
    andSomethingElse: function () {
        UWA.log('Something else to take care of...');
    }
});

Parameters

Name	Type	Argument	Default	Description
observable	Object			the observed emitter object, must implement UWA.Class.Events
name	Mixed			the name (string) of the listened event or a hash of {event: callback} pairs
callback	Function	<optional>		the listener callback, if name argument is a string.
priority	Number	<optional>	0	the priority level of the listener, if name argument is a string. 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.

Returns

Type

this

stopListening(observable, name, callback) → {this}

Tell this object to stop listening to events.

stopListening is meant to be used in conjunction with listenTo.

Either call stopListening with no arguments to have the object remove all of its registered callbacks. Or be more precise by telling it to remove just the events it's listening to on a specific object, or a specific event name, or just a specific callback.

There are two ways to call stopListening, as illustrated in the example below : either with the (optional, can be null) observed emitter object, the (optional, can be null) name of the event and the (optional, can be null) callback function or with the observed emitter object and an hash of { eventName: callback } pairs.

Example

var observer, observable, fn;

observer = new UWA.Class.Listener();
observable = new UWA.Class.Events();
fn = function () { UWA.log('Caught!'); };

// these are all valid calls to stopListening :
observer.listenTo(observable, 'someEvent', fn).stopListening();
observer.listenTo(observable, 'someEvent', fn).stopListening(observable);
observer.listenTo(observable, 'someEvent', fn).stopListening(null, 'someEvent');
observer.listenTo(observable, 'someEvent', fn).stopListening(null, null, fn);
observer.listenTo(observable, 'someEvent', fn).stopListening(observable, 'someEvent', fn);
observer.listenTo(observable, 'someEvent', fn).stopListening(observable, 'someEvent');
observer.listenTo(observable, 'someEvent', fn).stopListening(observable, null, fn);
observer.listenTo(observable, 'someEvent', fn).stopListening(null, 'someEvent', fn);
observer.listenTo(observable, {
    someEvent: fn,
    someOtherEvent: fn,
    andAThirdEvent: fn
}).stopListening(observable, {
    someEvent: fn,
    someOtherEvent: fn
}).stopListening();

Parameters

Name	Type	Argument	Description
observable	Object	<optional>	the observer emitter to stop listening to
name	Mixed	<optional>	the name (string) of the listened event or a hash of {event: callback} pairs
callback	Function	<optional>	the listener callback, if name argument is not a hash

Returns

Type

this