|
|
@@ -3,6 +3,10 @@
|
|
|
* For licensing, see LICENSE.md.
|
|
|
*/
|
|
|
|
|
|
+/**
|
|
|
+ * @module utils/emittermixin
|
|
|
+ */
|
|
|
+
|
|
|
import EventInfo from './eventinfo.js';
|
|
|
import uid from './uid.js';
|
|
|
import priorities from './priorities.js';
|
|
|
@@ -10,8 +14,8 @@ import priorities from './priorities.js';
|
|
|
/**
|
|
|
* Mixin that injects the events API into its host.
|
|
|
*
|
|
|
- * @mixin utils.EmitterMixin
|
|
|
- * @implements utils.Emitter
|
|
|
+ * @mixin EmitterMixin
|
|
|
+ * @implements module:utils/emittermixin~Emitter
|
|
|
*/
|
|
|
const EmitterMixin = {
|
|
|
/**
|
|
|
@@ -24,14 +28,14 @@ const EmitterMixin = {
|
|
|
* myEmitter.fire( 'myGroup:myEvent' ); // both genericCallback and specificCallback are fired.
|
|
|
* myEmitter.fire( 'myGroup:foo' ); // genericCallback is fired even though there are no callbacks for "foo".
|
|
|
*
|
|
|
+ * @method #on
|
|
|
* @param {String} event The name of the event.
|
|
|
* @param {Function} callback The function to be called on event.
|
|
|
* @param {Object} [options={}] Additional options.
|
|
|
- * @param {utils.PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
|
|
|
+ * @param {module:utils/priorities~PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
|
|
|
* the priority value the sooner the callback will be fired. Events having the same priority are called in the
|
|
|
* order they were added.
|
|
|
* @param {Object} [options.context] The object that represents `this` in the callback. Defaults to the object firing the event.
|
|
|
- * @method utils.EmitterMixin#on
|
|
|
*/
|
|
|
on( event, callback, options = {} ) {
|
|
|
createEventNamespace( this, event );
|
|
|
@@ -69,14 +73,14 @@ const EmitterMixin = {
|
|
|
* Registers a callback function to be executed on the next time the event is fired only. This is similar to
|
|
|
* calling {@link #on} followed by {@link #off} in the callback.
|
|
|
*
|
|
|
+ * @method #once
|
|
|
* @param {String} event The name of the event.
|
|
|
* @param {Function} callback The function to be called on event.
|
|
|
* @param {Object} [options={}] Additional options.
|
|
|
- * @param {utils.PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
|
|
|
+ * @param {module:utils/priorities~PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
|
|
|
* the priority value the sooner the callback will be fired. Events having the same priority are called in the
|
|
|
* order they were added.
|
|
|
* @param {Object} [options.context] The object that represents `this` in the callback. Defaults to the object firing the event.
|
|
|
- * @method utils.EmitterMixin#once
|
|
|
*/
|
|
|
once( event, callback, options ) {
|
|
|
const onceCallback = function( event ) {
|
|
|
@@ -94,11 +98,11 @@ const EmitterMixin = {
|
|
|
/**
|
|
|
* Stops executing the callback on the given event.
|
|
|
*
|
|
|
+ * @method #off
|
|
|
* @param {String} event The name of the event.
|
|
|
* @param {Function} callback The function to stop being called.
|
|
|
* @param {Object} [context] The context object to be removed, pared with the given callback. To handle cases where
|
|
|
* the same callback is used several times with different contexts.
|
|
|
- * @method utils.EmitterMixin#off
|
|
|
*/
|
|
|
off( event, callback, context ) {
|
|
|
const lists = getCallbacksListsForNamespace( this, event );
|
|
|
@@ -119,15 +123,15 @@ const EmitterMixin = {
|
|
|
/**
|
|
|
* Registers a callback function to be executed when an event is fired in a specific (emitter) object.
|
|
|
*
|
|
|
- * @param {utils.Emitter} emitter The object that fires the event.
|
|
|
+ * @method #listenTo
|
|
|
+ * @param {module:utils/emittermixin~Emitter} emitter The object that fires the event.
|
|
|
* @param {String} event The name of the event.
|
|
|
* @param {Function} callback The function to be called on event.
|
|
|
* @param {Object} [options={}] Additional options.
|
|
|
- * @param {utils.PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
|
|
|
+ * @param {module:utils/priorities~PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
|
|
|
* the priority value the sooner the callback will be fired. Events having the same priority are called in the
|
|
|
* order they were added.
|
|
|
* @param {Object} [options.context] The object that represents `this` in the callback. Defaults to the object firing the event.
|
|
|
- * @method utils.EmitterMixin#listenTo
|
|
|
*/
|
|
|
listenTo( emitter, event, callback, options ) {
|
|
|
let emitters, emitterId, emitterInfo, eventCallbacks;
|
|
|
@@ -179,12 +183,12 @@ const EmitterMixin = {
|
|
|
* * To stop listening to all events fired by a specific object.
|
|
|
* * To stop listening to all events fired by all object.
|
|
|
*
|
|
|
- * @param {utils.Emitter} [emitter] The object to stop listening to. If omitted, stops it for all objects.
|
|
|
+ * @method #stopListening
|
|
|
+ * @param {module:utils/emittermixin~Emitter} [emitter] The object to stop listening to. If omitted, stops it for all objects.
|
|
|
* @param {String} [event] (Requires the `emitter`) The name of the event to stop listening to. If omitted, stops it
|
|
|
* for all events from `emitter`.
|
|
|
* @param {Function} [callback] (Requires the `event`) The function to be removed from the call list for the given
|
|
|
* `event`.
|
|
|
- * @method utils.EmitterMixin#stopListening
|
|
|
*/
|
|
|
stopListening( emitter, event, callback ) {
|
|
|
let emitters = this._listeningTo;
|
|
|
@@ -227,12 +231,12 @@ const EmitterMixin = {
|
|
|
/**
|
|
|
* Fires an event, executing all callbacks registered for it.
|
|
|
*
|
|
|
- * The first parameter passed to callbacks is an {@link EventInfo} object, followed by the optional `args` provided in
|
|
|
- * the `fire()` method call.
|
|
|
+ * The first parameter passed to callbacks is an {@link module:utils/eventinfo~EventInfo} object,
|
|
|
+ * followed by the optional `args` provided in the `fire()` method call.
|
|
|
*
|
|
|
- * @param {String|utils.EventInfo} eventOrInfo The name of the event or `EventInfo` object if event is delegated.
|
|
|
+ * @method #fire
|
|
|
+ * @param {String|module:utils/eventinfo~EventInfo} eventOrInfo The name of the event or `EventInfo` object if event is delegated.
|
|
|
* @param {...*} [args] Additional arguments to be passed to the callbacks.
|
|
|
- * @method utils.EmitterMixin#fire
|
|
|
*/
|
|
|
fire( eventOrInfo, ...args ) {
|
|
|
const eventInfo = eventOrInfo instanceof EventInfo ? eventOrInfo : new EventInfo( this, eventOrInfo );
|
|
|
@@ -288,7 +292,7 @@ const EmitterMixin = {
|
|
|
},
|
|
|
|
|
|
/**
|
|
|
- * Delegates selected events to another {@link utils.Emitter}. For instance:
|
|
|
+ * Delegates selected events to another {@link module:utils/emittermixin~Emitter}. For instance:
|
|
|
*
|
|
|
* emitterA.delegate( 'eventX' ).to( emitterB );
|
|
|
* emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
|
|
|
@@ -301,19 +305,12 @@ const EmitterMixin = {
|
|
|
*
|
|
|
* emitterA.fire( 'eventY', data );
|
|
|
*
|
|
|
- * @method utils.EmitterMixin#delegate
|
|
|
+ * @method #delegate
|
|
|
* @param {...String} events Event names that will be delegated to another emitter.
|
|
|
- * @returns {utils.EmitterMixin.delegate#to}
|
|
|
+ * @returns {module:utils/emittermixin~EmitterMixinDelegateChain}
|
|
|
*/
|
|
|
delegate( ...events ) {
|
|
|
return {
|
|
|
- /**
|
|
|
- * Selects destination for {@link utils.EmitterMixin#delegate} events.
|
|
|
- *
|
|
|
- * @method utils.EmitterMixin.delegate#to
|
|
|
- * @param {utils.Emitter} emitter An `EmitterMixin` instance which is the destination for delegated events.
|
|
|
- * @param {String|Function} nameOrFunction A custom event name or function which converts the original name string.
|
|
|
- */
|
|
|
to: ( emitter, nameOrFunction ) => {
|
|
|
if ( !this._delegations ) {
|
|
|
this._delegations = new Map();
|
|
|
@@ -339,10 +336,10 @@ const EmitterMixin = {
|
|
|
* * To stop delegating a specific event to all emitters.
|
|
|
* * To stop delegating a specific event to a specific emitter.
|
|
|
*
|
|
|
+ * @method #stopDelegating
|
|
|
* @param {String} [event] The name of the event to stop delegating. If omitted, stops it all delegations.
|
|
|
- * @param {utils.Emitter} [emitter] (requires `event`) The object to stop delegating a particular event to. If omitted,
|
|
|
- * stops delegation of `event` to all emitters.
|
|
|
- * @method utils.EmitterMixin#stopDelegating
|
|
|
+ * @param {module:utils/emittermixin~Emitter} [emitter] (requires `event`) The object to stop delegating a particular event to.
|
|
|
+ * If omitted, stops delegation of `event` to all emitters.
|
|
|
*/
|
|
|
stopDelegating( event, emitter ) {
|
|
|
if ( !this._delegations ) {
|
|
|
@@ -519,7 +516,21 @@ function fireDelegatedEvents( destinations, eventInfo, fireArgs ) {
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * Interface representing classes which mix in {@link utils.EmitterMixin}.
|
|
|
+ * Interface representing classes which mix in {@link module:utils/emittermixin~EmitterMixin}.
|
|
|
+ *
|
|
|
+ * @interface Emitter
|
|
|
+ */
|
|
|
+
|
|
|
+/**
|
|
|
+ * The return value of {@link ~EmitterMixin#delegate}.
|
|
|
+ *
|
|
|
+ * @interface module:utils/emittermixin~EmitterMixinDelegateChain
|
|
|
+ */
|
|
|
+
|
|
|
+/**
|
|
|
+ * Selects destination for {@link module:utils/emittermixin~EmitterMixin#delegate} events.
|
|
|
*
|
|
|
- * @interface utils.Emitter
|
|
|
+ * @method #to
|
|
|
+ * @param {module:utils/emittermixin~Emitter} emitter An `EmitterMixin` instance which is the destination for delegated events.
|
|
|
+ * @param {String|Function} nameOrFunction A custom event name or function which converts the original name string.
|
|
|
*/
|