ckeditor/ckeditor5-utils

/**
 * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
 * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
 */

/**
 * @module utils/eventinfo
 */

import spy from './spy';

/**
 * The event object passed to event callbacks. It is used to provide information about the event as well as a tool to
 * manipulate it.
 */
export default class EventInfo {
    /**
     * @param {Object} source The emitter.
     * @param {String} name The event name.
     */
    constructor( source, name ) {
        /**
         * The object that fired the event.
         *
         * @readonly
         * @member {Object}
         */
        this.source = source;

        /**
         * The event name.
         *
         * @readonly
         * @member {String}
         */
        this.name = name;

        /**
         * Path this event has followed. See {@link module:utils/emittermixin~EmitterMixin#delegate}.
         *
         * @readonly
         * @member {Array.<Object>}
         */
        this.path = [];

        // The following methods are defined in the constructor because they must be re-created per instance.

        /**
         * Stops the event emitter to call further callbacks for this event interaction.
         *
         * @method #stop
         */
        this.stop = spy();

        /**
         * Removes the current callback from future interactions of this event.
         *
         * @method #off
         */
        this.off = spy();

        /**
         * The value which will be returned by {@link module:utils/emittermixin~EmitterMixin#fire}.
         *
         * It's `undefined` by default and can be changed by an event listener:
         *
         *        dataController.fire( 'getSelectedContent', ( evt ) => {
         *            // This listener will make `dataController.fire( 'getSelectedContent' )`
         *            // always return an empty DocumentFragment.
         *            evt.return = new DocumentFragment();
         *
         *            // Make sure no other listeners are executed.
         *            evt.stop();
         *        } );
         *
         * @member #return
         */
    }
}