GlobalCube
/
analytics


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344
							<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>JSDoc: Source: Evented.js</title>

    <script src="scripts/prettify/prettify.js"> </script>
    <script src="scripts/prettify/lang-css.js"> </script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>

<body>

<div id="main">

    <h1 class="page-title">Source: Evented.js</h1>

    
    <section>
        <article>
            <pre class="prettyprint source linenums"><code>// Licensed Materials - Property of IBM
//
// IBM Watson Analytics
//
// (C) Copyright IBM Corp. 2015
//
// US Government Users Restricted Rights - Use, duplication or
// disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

module.exports = ( function(
        Error,
        ObjectPolyfill,
        decl,
        Destroyable,
        EventArgs,
        WeakMap
    )
{
"use strict";

/*global console*/

var DEFAULT_ARGS = decl.freeze( new EventArgs() );
// listenersRef is used by Evented to register and unregister itself.
var g_listenersRef = new WeakMap();
// Using a WeakMap prevents circular references and hides the listeners from the object.
var g_eventHandles = new WeakMap();

var ensureCallable = ObjectPolyfill.ensureCallable;

/**
 * Create a new EventedHandle.
 * @class module:barejs.Evented~EventedHandle
 * @classdesc EventedHandle is the handle returned by {@link module:barejs.Evented#on Evented::on} and  {@link module:barejs.Evented#once Evented::once}.
 */
function EventedHandle( _listeners, _eventName, _listener )
{
    Destroyable.call( this );

    g_listenersRef.set( this, _listeners );
    decl.defineProperties( this,
    {
        eventName: { enumerable: true, value: _eventName },
        listener: { configurable: true, enumerable: true, value: _listener },
        _attached: { writable: true, value: false }
    } );

    this.attach();
}

decl.declareClass( EventedHandle, Destroyable,
/** @lends module:barejs.Evented~EventedHandle# */
{
    eventName: null,
    listener: null,
    _attached: null,

    /**
     * Destroy the handle.
     */
    destroy: function destroy()
    {
        this.remove();

        delete this.listener;
        g_listenersRef["delete"]( this );

        Destroyable.prototype.destroy.call( this );
    },

    /**
     * Remove the handle. A removed handle can be re-attached using {@link module:barejs.Evented~EventedHandle#attach attach}.
     * @returns {boolean} True if the handle got detached.
     */
    remove: function remove()
    {
        var listeners;
        if ( this._attached &amp;&amp; this.listener &amp;&amp; ( listeners = g_listenersRef.get( this ) ) )
        {
            // Look up event listeners backwards, since destroy iterates backwards
            var idx = listeners.lastIndexOf( this );

            // If the last listener is removed, use pop, since it doesn't return an Array.
            if ( idx >= ( listeners.length - 1 ) )
                listeners.pop();
            /*istanbul ignore else: this is purely a sanity check, else path should never occur*/
            else if ( idx >= 0 )
                listeners.splice( idx, 1 );


            this._attached = false;
            return true;
        }

        return false;
    },

    /**
     * Attach the handle. A handle is attached by default, this method should only be used after the handle has been detached
     * using {@link module:barejs.Evented~EventedHandle#remove remove}.
     * @returns {boolean} True if the handle is attached.
     */
    attach: function attach()
    {
        var listeners;
        if ( !this._attached &amp;&amp; this.listener &amp;&amp; ( listeners = g_listenersRef.get( this ) ) )
        {
            listeners.push( this );
            this._attached = true;
        }

        return this._attached;
    },

    /**
     * Check if the handle is attached.
     * @returns {boolean} True if the handle is attached.
     */
    isAttached: function isAttached()
    {
        return this._attached;
    }
} );

/**
 * The evented constructor will invoke the Destroyable constructor to ensure the object is initialized correctly.
 * @class module:barejs.Evented
 * @extends module:barejs.Destroyable
 * @classdesc Evented is a base class that adds Eventing to JavaScript Objects.
 * Extends Destroyable to automatically remove listeners if the object is destroyed.
 * If handles given to the listener are {@link module:barejs.Destroyable#own own}ed (or manually destroyed at the appropiate time),
 * the event link between Evented and its listener will be removed as soon as either party is destroyed.
 */
function Evented()
{
    Destroyable.call( this );
}

decl.preventCast( Evented );

return decl.declareClass( Evented, Destroyable,
/** @lends module:barejs.Evented# */
{
    /**
     * Destroy the Evented object. This will clean up the object, removing any links to listeners.
     */
    destroy: function destroy()
    {
        var handles = g_eventHandles.get( this ) || null;

        if ( handles )
        {
            g_eventHandles["delete"]( this );

            // Note: handles remove themselves from the array, so iterate backwards.
            // Do NOT use Destroyable.destroyAll for this!
            for ( var i = handles.length - 1; i >= 0; --i )
                handles[i].destroy();
        }

        Destroyable.prototype.destroy.call( this );
    },

    /**
     * Listen to an event. To stop listening, call destroy the returned handle. Listeners should {@link module:barejs.Destroyable#own own}
     * the handle returned by this method, so it is automatically disconnected when the listener is destroyed.
     * @param {string} _eventName The event to listen to.
     * @param {module:barejs.Evented~EventListener} _listener The callback to call if the event occurs.
     * @returns {module:barejs.Evented~EventedHandle}
     */
    on: function on( _eventName, _listener )
    {
        var handlers;

        // Note: inline check to see _listener is callable is performed first.
        if ( Destroyable.isDestroyed( ensureCallable( _listener, this )) )
            throw new Error( "The target object has been destroyed, cannot attach an event listener to it" );

        if ( !( ( "on" + _eventName ) in this ) )
            throw new Error( "The target object does not have a(n) " + _eventName + " event" );

        if ( !( handlers = g_eventHandles.get( this ) ) )
            g_eventHandles.set( this, handlers = [] );

        // No need to own the handle; handles are automatically destroyed
        return new EventedHandle( handlers, _eventName, _listener );
    },

    /**
     * Listen for an event, automatically detaching after one invocation of the listener.
     * @param {string} _eventName The event to listen to.
     * @param {module:barejs.Evented~EventListener} _listener The callback to call (once) if the event occurs.
     * @returns {module:barejs.Evented~EventedHandle}
     */
    once: function once( _eventName, _listener )
    {
        // Inline validation of _listener
        var handle = ensureCallable( _listener, null );

        return ( handle = this.on( _eventName, function()
        {
            /*istanbul ignore else: this is purely a sanity check, else path should never occur*/
            if ( handle )
            {
                handle.destroy();
                handle = null;
            }

            // Forward call
            return _listener.apply( this, arguments );
        } ) );
    },

    /**
     * Emit the event with _eventName.
     * @param {string} _eventName The name of the event to emit.
     * @param {module:barejs.EventArgs} _eventArgs the event args to emit.
     * @returns {module:barejs.EventArgs} _eventArgs (or null if not specified).
     */
    emit: function emit( _eventName, _eventArgs )
    {
        if ( Destroyable.isDestroyed( this ) )
            throw new Error( "The target object has been destroyed, cannot emit an event from it" );

        var args = _eventArgs || DEFAULT_ARGS,
            evtDef = "on" + _eventName,
            handles;

        if ( !( evtDef in this ) )
            throw new Error( "The " + _eventName + " event being emitted is not defined. Is this class missing an " + evtDef + " event definition?" );
        if ( !__RELEASE__ &amp;&amp; !( args instanceof EventArgs ) &amp;&amp; ( typeof console !== "undefined" ) )
            console.warn( ( this.constructor.name || "Evented" ) + " is emitting the \"" + _eventName + "\" event with arguments that are not EventArgs" );

        // First, call the local method (event definition)
        this[evtDef]( args, this );

        // If there are no handles, there are no listeners, so bail out
        if ( ( handles = g_eventHandles.get( this ) ) &amp;&amp; ( handles.length > 0 ) )
        {
            // Get the listeners for this event; using filter gives us a temporary array which is protected
            // from the handles array being modified as a side effect of handler execution.
            var listeners = handles.filter( function( _handle )
            {
                return _handle.eventName === _eventName;
            } );

            // Invoke the event handlers
            for ( var idx = 0, len = listeners.length, handle; idx &lt; len; idx++ )
            {
                // It is possible a handle got removed as a side effect of a previous handler; if so, ignore it.
                if ( ( handle = listeners[idx] )._attached &amp;&amp; handle.listener )
                    handle.listener( args, this );
            }
        }

        return _eventArgs || null;
    },

    /**
     * Check if there is at least one listener for _eventName. It is highly recommended to just
     * emit an event instead of checking if there are listeners. This method is provided for edge
     * cases where building the event metadata is an expensive process, which should be avoided if
     * there are no listeners.
     * @param {string} _eventName The name of the event to check.
     * @returns {Boolean} True if there is at least one listener, false otherwise.
     */
    hasListener: function( _eventName )
    {
        var handles = g_eventHandles.get( this );

        return ( !!handles ) &amp;&amp; handles.some( function( _handle )
        {
            return _handle.eventName === _eventName;
        } );
    }
} );

/**
 * Event listeners are called with two arguments; the EventArgs and the sender.
 * @callback module:barejs.Evented~EventListener
 * @param {module:barejs.EventArgs} _eventArgs The EventArgs to the event.
 * @param {module:barejs.Evented} _sender The Evented object that emitted the event.
 */

// End of module
}(
    Error,
    require( "./polyfill/Object" ),
    require( "./decl" ),
    require( "./Destroyable" ),
    require( "./EventArgs" ),
    require( "./WeakMap" )
) );
</code></pre>
        </article>
    </section>


</div>

<nav>
    <h2><a href="index.html">Home</a></h2><h3>Modules</h3><ul><li><a href="module-barejs.html">barejs</a></li><li><a href="module-barejs_polyfill.html">barejs/polyfill</a></li><li><a href="module-barejs_polyfill_Intl.html">barejs/polyfill/Intl</a></li></ul><h3>Classes</h3><ul><li><a href="module-barejs.decl.html">decl</a></li><li><a href="module-barejs.decl-Enum.html">Enum</a></li><li><a href="module-barejs.decl-Interface.html">Interface</a></li><li><a href="module-barejs.decl-SpecialType.html">SpecialType</a></li><li><a href="module-barejs.Destroyable.html">Destroyable</a></li><li><a href="module-barejs.EventArgs.html">EventArgs</a></li><li><a href="module-barejs.Evented.html">Evented</a></li><li><a href="module-barejs.Evented-EventedHandle.html">EventedHandle</a></li><li><a href="module-barejs.Exception.html">Exception</a></li><li><a href="module-barejs_polyfill.Array.html">Array</a></li><li><a href="module-barejs_polyfill.Date.html">Date</a></li><li><a href="module-barejs_polyfill.EntryStore.html">EntryStore</a></li><li><a href="module-barejs_polyfill.EntryStore.Iterator.html">Iterator</a></li><li><a href="module-barejs_polyfill.Function.html">Function</a></li><li><a href="module-barejs_polyfill.Map.html">Map</a></li><li><a href="module-barejs_polyfill.Map-MapIterator.html">MapIterator</a></li><li><a href="module-barejs_polyfill.Math.html">Math</a></li><li><a href="module-barejs_polyfill.Number.html">Number</a></li><li><a href="module-barejs_polyfill.Object.html">Object</a></li><li><a href="module-barejs_polyfill.Promise.html">Promise</a></li><li><a href="module-barejs_polyfill.Set.html">Set</a></li><li><a href="module-barejs_polyfill.Set-SetIterator.html">SetIterator</a></li><li><a href="module-barejs_polyfill.String.html">String</a></li><li><a href="module-barejs_polyfill.Symbol.html">Symbol</a></li><li><a href="module-barejs_polyfill.WeakMap.html">WeakMap</a></li><li><a href="module-barejs_polyfill.WeakSet.html">WeakSet</a></li><li><a href="module-barejs_polyfill_Intl.DateTimeFormat.html">DateTimeFormat</a></li><li><a href="module-barejs_polyfill_Intl.DateTimeFormat-DateTimeFormatOptions.html">DateTimeFormatOptions</a></li><li><a href="module-barejs_polyfill_Intl.NumberFormat.html">NumberFormat</a></li><li><a href="module-barejs_polyfill_Intl.NumberFormat-NumberFormatOptions.html">NumberFormatOptions</a></li><li><a href="module-barejs_polyfill_Intl-Format.html">Format</a></li></ul>
</nav>

<br class="clear">

<footer>
    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Wed Oct 03 2018 15:59:33 GMT+0200 (W. Europe Daylight Time)
</footer>

<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>