mirror of
https://github.com/the-djmaze/snappymail.git
synced 2025-01-06 23:07:56 +08:00
305 lines
11 KiB
JavaScript
305 lines
11 KiB
JavaScript
/** @license
|
|
* JS Signals <http://millermedeiros.github.com/js-signals/>
|
|
* Released under the MIT license
|
|
* Author: Miller Medeiros
|
|
* Version: 1.0.0 - Build: 268 (2012/11/29 05:48 PM)
|
|
*/
|
|
|
|
(global=>{
|
|
|
|
// SignalBinding -------------------------------------------------
|
|
//================================================================
|
|
|
|
class SignalBinding {
|
|
|
|
/**
|
|
* Object that represents a binding between a Signal and a listener function.
|
|
* <br />- <strong>This is an internal constructor and shouldn't be called by regular users.</strong>
|
|
* <br />- inspired by Joa Ebert AS3 SignalBinding and Robert Penner's Slot classes.
|
|
* @author Miller Medeiros
|
|
* @constructor
|
|
* @internal
|
|
* @name SignalBinding
|
|
* @param {Signal} signal Reference to Signal object that listener is currently bound to.
|
|
* @param {Function} listener Handler function bound to the signal.
|
|
* @param {boolean} isOnce If binding should be executed just once.
|
|
* @param {Object} [listenerContext] Context on which listener will be executed (object that should represent the `this` variable inside listener function).
|
|
* @param {Number} [priority] The priority level of the event listener. (default = 0).
|
|
*/
|
|
constructor (signal, listener, isOnce, listenerContext, priority) {
|
|
|
|
/**
|
|
* If binding is active and should be executed.
|
|
* @type boolean
|
|
*/
|
|
this.active = true;
|
|
|
|
/**
|
|
* Default parameters passed to listener during `Signal.dispatch` and `SignalBinding.execute`. (curried parameters)
|
|
* @type Array|null
|
|
*/
|
|
this.params = null;
|
|
|
|
/**
|
|
* Handler function bound to the signal.
|
|
* @type Function
|
|
* @private
|
|
*/
|
|
this._listener = listener;
|
|
|
|
/**
|
|
* If binding should be executed just once.
|
|
* @type boolean
|
|
* @private
|
|
*/
|
|
this._isOnce = isOnce;
|
|
|
|
/**
|
|
* Context on which listener will be executed (object that should represent the `this` variable inside listener function).
|
|
* @memberOf SignalBinding.prototype
|
|
* @name context
|
|
* @type Object|undefined|null
|
|
*/
|
|
this.context = listenerContext;
|
|
|
|
/**
|
|
* Reference to Signal object that listener is currently bound to.
|
|
* @type Signal
|
|
* @private
|
|
*/
|
|
this._signal = signal;
|
|
|
|
/**
|
|
* Listener priority
|
|
* @type Number
|
|
* @private
|
|
*/
|
|
this._priority = priority || 0;
|
|
}
|
|
|
|
/**
|
|
* Call listener passing arbitrary parameters.
|
|
* <p>If binding was added using `Signal.addOnce()` it will be automatically removed from signal dispatch queue, this method is used internally for the signal dispatch.</p>
|
|
* @param {Array} [paramsArr] Array of parameters that should be passed to the listener
|
|
* @return {*} Value returned by the listener.
|
|
*/
|
|
execute (paramsArr) {
|
|
var handlerReturn, params;
|
|
if (this.active && !!this._listener) {
|
|
params = this.params? this.params.concat(paramsArr) : paramsArr;
|
|
handlerReturn = this._listener.apply(this.context, params);
|
|
if (this._isOnce) {
|
|
this.detach();
|
|
}
|
|
}
|
|
return handlerReturn;
|
|
}
|
|
|
|
/**
|
|
* Detach binding from signal.
|
|
* - alias to: mySignal.remove(myBinding.getListener());
|
|
* @return {Function|null} Handler function bound to the signal or `null` if binding was previously detached.
|
|
*/
|
|
detach () {
|
|
return (this._signal && this._listener) ? this._signal.remove(this._listener, this.context) : null;
|
|
}
|
|
|
|
/**
|
|
* @return {boolean} If SignalBinding will only be executed once.
|
|
*/
|
|
isOnce () {
|
|
return this._isOnce;
|
|
}
|
|
|
|
/**
|
|
* Delete instance properties
|
|
* @private
|
|
*/
|
|
_destroy () {
|
|
delete this._signal;
|
|
delete this._listener;
|
|
delete this.context;
|
|
}
|
|
}
|
|
|
|
|
|
// Signal --------------------------------------------------------
|
|
//================================================================
|
|
|
|
function validateListener(listener, fnName) {
|
|
if (typeof listener !== 'function') {
|
|
throw new Error( 'listener is a required param of {fn}() and should be a Function.'.replace('{fn}', fnName) );
|
|
}
|
|
}
|
|
|
|
class Signal {
|
|
|
|
/**
|
|
* Custom event broadcaster
|
|
* <br />- inspired by Robert Penner's AS3 Signals.
|
|
* @name Signal
|
|
* @author Miller Medeiros
|
|
* @constructor
|
|
*/
|
|
constructor () {
|
|
/**
|
|
* If Signal should keep record of previously dispatched parameters and
|
|
* automatically execute listener during `add()`/`addOnce()` if Signal was
|
|
* already dispatched before.
|
|
* @type boolean
|
|
*/
|
|
this.memorize = false;
|
|
|
|
/**
|
|
* If Signal is active and should broadcast events.
|
|
* <p><strong>IMPORTANT:</strong> Setting this property during a dispatch will only affect the next dispatch, if you want to stop the propagation of a signal use `halt()` instead.</p>
|
|
* @type boolean
|
|
*/
|
|
this.active = true;
|
|
|
|
/**
|
|
* @type Array.<SignalBinding>
|
|
* @private
|
|
*/
|
|
this._bindings = [];
|
|
this._prevParams = null;
|
|
|
|
// enforce dispatch to aways work on same context (#47)
|
|
var self = this;
|
|
this.dispatch = (...args) => Signal.prototype.dispatch.apply(self, args);
|
|
}
|
|
|
|
/**
|
|
* @param {Function} listener
|
|
* @return {number}
|
|
* @private
|
|
*/
|
|
_indexOfListener (listener, context) {
|
|
var n = this._bindings.length,
|
|
cur;
|
|
while (n--) {
|
|
cur = this._bindings[n];
|
|
if (cur._listener === listener && cur.context === context) {
|
|
return n;
|
|
}
|
|
}
|
|
return -1;
|
|
}
|
|
|
|
/**
|
|
* Add a listener to the signal.
|
|
* @param {Function} listener Signal handler function.
|
|
* @param {Object} [listenerContext] Context on which listener will be executed (object that should represent the `this` variable inside listener function).
|
|
* @param {Number} [priority] The priority level of the event listener. 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. (default = 0)
|
|
* @return {SignalBinding} An Object representing the binding between the Signal and listener.
|
|
*/
|
|
add (listener, listenerContext, priority) {
|
|
validateListener(listener, 'add');
|
|
|
|
var prevIndex = this._indexOfListener(listener, listenerContext),
|
|
binding;
|
|
|
|
if (prevIndex !== -1) {
|
|
binding = this._bindings[prevIndex];
|
|
if (binding.isOnce() !== false) {
|
|
throw new Error('You cannot addOnce() then add() the same listener without removing the relationship first.');
|
|
}
|
|
} else {
|
|
binding = new SignalBinding(this, listener, false, listenerContext, priority);
|
|
//simplified insertion sort
|
|
var n = this._bindings.length;
|
|
do { --n; } while (this._bindings[n] && binding._priority <= this._bindings[n]._priority);
|
|
this._bindings.splice(n + 1, 0, binding);
|
|
}
|
|
|
|
if(this.memorize && this._prevParams){
|
|
binding.execute(this._prevParams);
|
|
}
|
|
|
|
return binding;
|
|
}
|
|
|
|
/**
|
|
* Remove a single listener from the dispatch queue.
|
|
* @param {Function} listener Handler function that should be removed.
|
|
* @param {Object} [context] Execution context (since you can add the same handler multiple times if executing in a different context).
|
|
* @return {Function} Listener handler function.
|
|
*/
|
|
remove (listener, context) {
|
|
validateListener(listener, 'remove');
|
|
|
|
var i = this._indexOfListener(listener, context);
|
|
if (i !== -1) {
|
|
this._bindings[i]._destroy(); //no reason to a SignalBinding exist if it isn't attached to a signal
|
|
this._bindings.splice(i, 1);
|
|
}
|
|
return listener;
|
|
}
|
|
|
|
/**
|
|
* Remove all listeners from the Signal.
|
|
*/
|
|
removeAll () {
|
|
var n = this._bindings.length;
|
|
while (n--) {
|
|
this._bindings[n]._destroy();
|
|
}
|
|
this._bindings.length = 0;
|
|
}
|
|
|
|
/**
|
|
* Dispatch/Broadcast Signal to all listeners added to the queue.
|
|
* @param {...*} [params] Parameters that should be passed to each handler.
|
|
*/
|
|
dispatch (...paramsArr) {
|
|
if (! this.active) {
|
|
return;
|
|
}
|
|
|
|
var n = this._bindings.length,
|
|
bindings;
|
|
|
|
if (this.memorize) {
|
|
this._prevParams = paramsArr;
|
|
}
|
|
|
|
if (! n) {
|
|
//should come after memorize
|
|
return;
|
|
}
|
|
|
|
bindings = this._bindings.slice(); //clone array in case add/remove items during dispatch
|
|
|
|
//execute all callbacks until end of the list or until a callback returns `false` or stops propagation
|
|
//reverse loop since listeners with higher priority will be added at the end of the list
|
|
do { n--; } while (bindings[n] && bindings[n].execute(paramsArr) !== false);
|
|
}
|
|
|
|
/**
|
|
* Remove all bindings from signal and destroy any reference to external objects (destroy Signal object).
|
|
* <p><strong>IMPORTANT:</strong> calling any method on the signal instance after calling dispose will throw errors.</p>
|
|
*/
|
|
dispose () {
|
|
this.removeAll();
|
|
delete this._bindings;
|
|
delete this._prevParams;
|
|
}
|
|
|
|
}
|
|
|
|
|
|
// Namespace -----------------------------------------------------
|
|
//================================================================
|
|
|
|
var signals = Signal;
|
|
|
|
/**
|
|
* Custom event broadcaster
|
|
* @see Signal
|
|
*/
|
|
// alias for backwards compatibility (see #gh-44)
|
|
signals.Signal = Signal;
|
|
|
|
global.signals = signals;
|
|
|
|
})(this);
|