Config
Table of Contents

Method

Function#on( )

Defines the list of events this method is interested in. Whenever one of these events is triggered on the object to which this method belongs, the method will automatically be called.

Parameters

var_args...String All arguments are treated as the names of events this method should be triggered by.

Returns

Function Returns self.

"use strict";

( function ( NS ) {

var meta = NS.meta,
 slice = Array.prototype.slice,
 eventPrefix = '__event__',
 toString = Object.prototype.toString;

Function.implement({
 on: function () {
   return this.observes.apply( this,
     slice.call( arguments ).map( function ( type ) {
       return eventPrefix + type;
     })
   );
 }
});

Mixin

O.EventTarget

The EventTarget mixin allows you to add custom event support to any other class complete with support for bubbling. Simply add a Mixin: O.EventTarget property to your class. Then you can fire an event at any time by calling this.fire('eventName'). If you add a target to support bubbling, it is recommended you add a prefix to the name of your events, to distinguish them from those of other classes, e.g. the IO class fires io:eventName events.

NS.EventTarget = {

Property

O.EventTarget#nextEventTarget

  • (O.EventTarget|null)

Pointer to the next object in the event bubbling chain.

nextEventTarget: null,

Method

O.EventTarget#on( type, obj, method )

Add a function to be called whenever an event of a particular type is fired.

Parameters

typeString The name of the event to subscribe to.
obj(Function|Object) The function to be called when the event fires, or alternatively supply an object and in the third parameter give the name of the method to be called on it.
methodString Optional The name of the callback method to be called on obj. Ignored if a function is passed for the 2nd parameter.

Returns

O.EventTarget Returns self.

on: function ( type, obj, method ) {
   if ( !( obj instanceof Function ) ) {
     obj = { object: obj, method: method };
   }
   type = eventPrefix + type;

   var observers = meta( this ).observers,
     handlers = observers[ type ];
   if ( !observers.hasOwnProperty( type ) ) {
     handlers = observers[ type ] = handlers ?
       handlers.slice() : [];
   }
   handlers.push( obj );
   return this;
 },

Method

O.EventTarget#once( type, fn )

Add a function to be called the next time an event of a particular type is fired, but not for subsequent firings.

Parameters

typeString The name of the event to subscribe to.
fnFunction The function to be called when the event fires.

Returns

O.EventTarget Returns self.

once: function ( type, fn ) {
   var once = function ( event ) {
     fn.call( this, event );
     this.off( type, once );
   };
   this.on( type, once );
   return this;
 },

Method

O.EventTarget#fire( type, event, defaultFn )

Fires an event, causing all subscribed functions to be called with an event object as the single parameter and the scope bound to the object on which they subscribed to the event. In the case of subscribed object/method name pairs, the scope will remain the object on which the method is called.

The event object contains the properties supplied in the details parameter and also a type attribute, with the type of the event, a target attribute, referencing the object on which the event was actually fired, a preventDefault function, which stops the default function firing if supplied, and a stopPropagation function, which prevents the event bubbling any further.

Parameters

typeString The name of the event being fired.
eventObject Optional An event object or object of values to be added to the event object.
defaultFnFunction Optional This function is called after all event handlers have completed, providing none of them called the preventDefault method on the event object.

Returns

Boolean Was propagation stopped?

fire: function ( type, event, defaultFn ) {
   var canBubble = true,
     preventDefault = false,
     target = this,
     typeKey = eventPrefix + type,
     handler, handlers, length;

   if ( !( event && ( /Event\]$/.test( toString.call( event ) ) ||
       event.isEvent ) ) ) {
     event = NS.extend({
       type: type,
       target: this,
       preventDefault: function () {
         preventDefault = true;
         return this;
       }
     }, event );
   }

   event.stopPropagation = function () {
     canBubble = false;
     return this;
   };

   while ( target ) {
     handlers = meta( target ).observers[ typeKey ];
     length = handlers ? handlers.length : 0;
     while ( length-- ) {
       try {
         handler = handlers[ length ];
         if ( handler instanceof Function ) {
           handler.call( target, event );
         } else {
           ( handler.object || target )[ handler.method ]( event );
         }
       } catch ( error ) {
         NS.RunLoop.didError( error );
       }
     }
     // Did someone cancel the bubble
     if ( !canBubble ) { break; }
     // If not, move up the hierarchy
     target = target.get ?
       target.get( 'nextEventTarget' ) :
       target.nextEventTarget;
   }
   // When we get to the top, execute default.
   if ( defaultFn && !preventDefault ) {
     defaultFn( event );
   }
   return !canBubble;
 },

Method

O.EventTarget#off( type, obj, method )

Detaches a particular event handler or all handlers for a particular event type. This method has no effect if the function supplied is not subscribed to the event type given, or no function is supplied and the event type given has no handlers subscribed.

Parameters

typeString The name of the event to detach handlers from.
obj(Function|Object) Optional The function to detach or the obj whose method will be detached. If this argument is not supplied, all handlers for the given type will be removed.
methodString Optional The name of the callback method to be detached. Ignored if a function is passed for the 2nd parameter.

Returns

O.EventTarget Returns self.

off: function ( type, obj, method ) {
   type = eventPrefix + type;

   var observers = meta( this ).observers,
     handlers = observers[ type ];
   if ( handlers ) {
     if ( !observers.hasOwnProperty( type ) ) {
       handlers = observers[ type ] = handlers.slice();
     }
     if ( obj ) {
       if ( !( obj instanceof Function ) ) {
         var l = handlers.length;
         while ( l-- ) {
           var handler = handlers[l];
           if ( handler.object === obj &&
               handler.method === method ) {
             handlers.splice( l, 1 );
           }
         }
       } else {
         handlers.erase( obj );
       }
     } else {
       handlers.length = 0;
     }
   }
   return this;
 }
};

}( O ) );
Animation
Application
Core
DataStore
DOM
DragDrop
Foundation
IO
Localisation
Selection
Parser
TimeZones
Storage
Touch
CollectionViews
UA
ContainerViews
ControlViews
PanelViews
View