343 lines
11 KiB
JavaScript
343 lines
11 KiB
JavaScript
/*
|
|
Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved.
|
|
For licensing, see LICENSE.html or http://ckeditor.com/license
|
|
*/
|
|
|
|
/**
|
|
* @fileOverview Defines the {@link CKEDITOR.event} class, which serves as the
|
|
* base for classes and objects that require event handling features.
|
|
*/
|
|
|
|
if ( !CKEDITOR.event )
|
|
{
|
|
/**
|
|
* Creates an event class instance. This constructor is rearely used, being
|
|
* the {@link #.implementOn} function used in class prototypes directly
|
|
* instead.
|
|
* @class This is a base class for classes and objects that require event
|
|
* handling features.<br />
|
|
* <br />
|
|
* Do not confuse this class with {@link CKEDITOR.dom.event} which is
|
|
* instead used for DOM events. The CKEDITOR.event class implements the
|
|
* internal event system used by the CKEditor to fire API related events.
|
|
* @example
|
|
*/
|
|
CKEDITOR.event = function()
|
|
{};
|
|
|
|
/**
|
|
* Implements the {@link CKEDITOR.event} features in an object.
|
|
* @param {Object} targetObject The object into which implement the features.
|
|
* @example
|
|
* var myObject = { message : 'Example' };
|
|
* <b>CKEDITOR.event.implementOn( myObject }</b>;
|
|
* myObject.on( 'testEvent', function()
|
|
* {
|
|
* alert( this.message ); // "Example"
|
|
* });
|
|
* myObject.fire( 'testEvent' );
|
|
*/
|
|
CKEDITOR.event.implementOn = function( targetObject )
|
|
{
|
|
var eventProto = CKEDITOR.event.prototype;
|
|
|
|
for ( var prop in eventProto )
|
|
{
|
|
if ( targetObject[ prop ] == undefined )
|
|
targetObject[ prop ] = eventProto[ prop ];
|
|
}
|
|
};
|
|
|
|
CKEDITOR.event.prototype = (function()
|
|
{
|
|
// Returns the private events object for a given object.
|
|
var getPrivate = function( obj )
|
|
{
|
|
var _ = ( obj.getPrivate && obj.getPrivate() ) || obj._ || ( obj._ = {} );
|
|
return _.events || ( _.events = {} );
|
|
};
|
|
|
|
var eventEntry = function( eventName )
|
|
{
|
|
this.name = eventName;
|
|
this.listeners = [];
|
|
};
|
|
|
|
eventEntry.prototype =
|
|
{
|
|
// Get the listener index for a specified function.
|
|
// Returns -1 if not found.
|
|
getListenerIndex : function( listenerFunction )
|
|
{
|
|
for ( var i = 0, listeners = this.listeners ; i < listeners.length ; i++ )
|
|
{
|
|
if ( listeners[i].fn == listenerFunction )
|
|
return i;
|
|
}
|
|
return -1;
|
|
}
|
|
};
|
|
|
|
return /** @lends CKEDITOR.event.prototype */ {
|
|
/**
|
|
* Registers a listener to a specific event in the current object.
|
|
* @param {String} eventName The event name to which listen.
|
|
* @param {Function} listenerFunction The function listening to the
|
|
* event. A single {@link CKEDITOR.eventInfo} object instanced
|
|
* is passed to this function containing all the event data.
|
|
* @param {Object} [scopeObj] The object used to scope the listener
|
|
* call (the this object. If omitted, the current object is used.
|
|
* @param {Object} [listenerData] Data to be sent as the
|
|
* {@link CKEDITOR.eventInfo#listenerData} when calling the
|
|
* listener.
|
|
* @param {Number} [priority] The listener priority. Lower priority
|
|
* listeners are called first. Listeners with the same priority
|
|
* value are called in registration order. Defaults to 10.
|
|
* @example
|
|
* someObject.on( 'someEvent', function()
|
|
* {
|
|
* alert( this == someObject ); // "true"
|
|
* });
|
|
* @example
|
|
* someObject.on( 'someEvent', function()
|
|
* {
|
|
* alert( this == anotherObject ); // "true"
|
|
* }
|
|
* , anotherObject );
|
|
* @example
|
|
* someObject.on( 'someEvent', function( event )
|
|
* {
|
|
* alert( event.listenerData ); // "Example"
|
|
* }
|
|
* , null, 'Example' );
|
|
* @example
|
|
* someObject.on( 'someEvent', function() { ... } ); // 2nd called
|
|
* someObject.on( 'someEvent', function() { ... }, null, null, 100 ); // 3rd called
|
|
* someObject.on( 'someEvent', function() { ... }, null, null, 1 ); // 1st called
|
|
*/
|
|
on : function( eventName, listenerFunction, scopeObj, listenerData, priority )
|
|
{
|
|
// Get the event entry (create it if needed).
|
|
var events = getPrivate( this ),
|
|
event = events[ eventName ] || ( events[ eventName ] = new eventEntry( eventName ) );
|
|
|
|
if ( event.getListenerIndex( listenerFunction ) < 0 )
|
|
{
|
|
// Get the listeners.
|
|
var listeners = event.listeners;
|
|
|
|
// Fill the scope.
|
|
if ( !scopeObj )
|
|
scopeObj = this;
|
|
|
|
// Default the priority, if needed.
|
|
if ( isNaN( priority ) )
|
|
priority = 10;
|
|
|
|
var me = this;
|
|
|
|
// Create the function to be fired for this listener.
|
|
var listenerFirer = function( editor, publisherData, stopFn, cancelFn )
|
|
{
|
|
var ev =
|
|
{
|
|
name : eventName,
|
|
sender : this,
|
|
editor : editor,
|
|
data : publisherData,
|
|
listenerData : listenerData,
|
|
stop : stopFn,
|
|
cancel : cancelFn,
|
|
removeListener : function()
|
|
{
|
|
me.removeListener( eventName, listenerFunction );
|
|
}
|
|
};
|
|
|
|
listenerFunction.call( scopeObj, ev );
|
|
|
|
return ev.data;
|
|
};
|
|
listenerFirer.fn = listenerFunction;
|
|
listenerFirer.priority = priority;
|
|
|
|
// Search for the right position for this new listener, based on its
|
|
// priority.
|
|
for ( var i = listeners.length - 1 ; i >= 0 ; i-- )
|
|
{
|
|
// Find the item which should be before the new one.
|
|
if ( listeners[ i ].priority <= priority )
|
|
{
|
|
// Insert the listener in the array.
|
|
listeners.splice( i + 1, 0, listenerFirer );
|
|
return;
|
|
}
|
|
}
|
|
|
|
// If no position has been found (or zero length), put it in
|
|
// the front of list.
|
|
listeners.unshift( listenerFirer );
|
|
}
|
|
},
|
|
|
|
/**
|
|
* Fires an specific event in the object. All registered listeners are
|
|
* called at this point.
|
|
* @function
|
|
* @param {String} eventName The event name to fire.
|
|
* @param {Object} [data] Data to be sent as the
|
|
* {@link CKEDITOR.eventInfo#data} when calling the
|
|
* listeners.
|
|
* @param {CKEDITOR.editor} [editor] The editor instance to send as the
|
|
* {@link CKEDITOR.eventInfo#editor} when calling the
|
|
* listener.
|
|
* @returns {Boolean|Object} A booloan indicating that the event is to be
|
|
* canceled, or data returned by one of the listeners.
|
|
* @example
|
|
* someObject.on( 'someEvent', function() { ... } );
|
|
* someObject.on( 'someEvent', function() { ... } );
|
|
* <b>someObject.fire( 'someEvent' )</b>; // both listeners are called
|
|
* @example
|
|
* someObject.on( 'someEvent', function( event )
|
|
* {
|
|
* alert( event.data ); // "Example"
|
|
* });
|
|
* <b>someObject.fire( 'someEvent', 'Example' )</b>;
|
|
*/
|
|
fire : (function()
|
|
{
|
|
// Create the function that marks the event as stopped.
|
|
var stopped = false;
|
|
var stopEvent = function()
|
|
{
|
|
stopped = true;
|
|
};
|
|
|
|
// Create the function that marks the event as canceled.
|
|
var canceled = false;
|
|
var cancelEvent = function()
|
|
{
|
|
canceled = true;
|
|
};
|
|
|
|
return function( eventName, data, editor )
|
|
{
|
|
// Get the event entry.
|
|
var event = getPrivate( this )[ eventName ];
|
|
|
|
// Save the previous stopped and cancelled states. We may
|
|
// be nesting fire() calls.
|
|
var previousStopped = stopped,
|
|
previousCancelled = canceled;
|
|
|
|
// Reset the stopped and canceled flags.
|
|
stopped = canceled = false;
|
|
|
|
if ( event )
|
|
{
|
|
var listeners = event.listeners;
|
|
|
|
if ( listeners.length )
|
|
{
|
|
// As some listeners may remove themselves from the
|
|
// event, the original array length is dinamic. So,
|
|
// let's make a copy of all listeners, so we are
|
|
// sure we'll call all of them.
|
|
listeners = listeners.slice( 0 );
|
|
|
|
// Loop through all listeners.
|
|
for ( var i = 0 ; i < listeners.length ; i++ )
|
|
{
|
|
// Call the listener, passing the event data.
|
|
var retData = listeners[i].call( this, editor, data, stopEvent, cancelEvent );
|
|
|
|
if ( typeof retData != 'undefined' )
|
|
data = retData;
|
|
|
|
// No further calls is stopped or canceled.
|
|
if ( stopped || canceled )
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
|
|
var ret = canceled || ( typeof data == 'undefined' ? false : data );
|
|
|
|
// Restore the previous stopped and canceled states.
|
|
stopped = previousStopped;
|
|
canceled = previousCancelled;
|
|
|
|
return ret;
|
|
};
|
|
})(),
|
|
|
|
/**
|
|
* Fires an specific event in the object, releasing all listeners
|
|
* registered to that event. The same listeners are not called again on
|
|
* successive calls of it or of {@link #fire}.
|
|
* @param {String} eventName The event name to fire.
|
|
* @param {Object} [data] Data to be sent as the
|
|
* {@link CKEDITOR.eventInfo#data} when calling the
|
|
* listeners.
|
|
* @param {CKEDITOR.editor} [editor] The editor instance to send as the
|
|
* {@link CKEDITOR.eventInfo#editor} when calling the
|
|
* listener.
|
|
* @returns {Boolean|Object} A booloan indicating that the event is to be
|
|
* canceled, or data returned by one of the listeners.
|
|
* @example
|
|
* someObject.on( 'someEvent', function() { ... } );
|
|
* someObject.fire( 'someEvent' ); // above listener called
|
|
* <b>someObject.fireOnce( 'someEvent' )</b>; // above listener called
|
|
* someObject.fire( 'someEvent' ); // no listeners called
|
|
*/
|
|
fireOnce : function( eventName, data, editor )
|
|
{
|
|
var ret = this.fire( eventName, data, editor );
|
|
delete getPrivate( this )[ eventName ];
|
|
return ret;
|
|
},
|
|
|
|
/**
|
|
* Unregisters a listener function from being called at the specified
|
|
* event. No errors are thrown if the listener has not been
|
|
* registered previously.
|
|
* @param {String} eventName The event name.
|
|
* @param {Function} listenerFunction The listener function to unregister.
|
|
* @example
|
|
* var myListener = function() { ... };
|
|
* someObject.on( 'someEvent', myListener );
|
|
* someObject.fire( 'someEvent' ); // myListener called
|
|
* <b>someObject.removeListener( 'someEvent', myListener )</b>;
|
|
* someObject.fire( 'someEvent' ); // myListener not called
|
|
*/
|
|
removeListener : function( eventName, listenerFunction )
|
|
{
|
|
// Get the event entry.
|
|
var event = getPrivate( this )[ eventName ];
|
|
|
|
if ( event )
|
|
{
|
|
var index = event.getListenerIndex( listenerFunction );
|
|
if ( index >= 0 )
|
|
event.listeners.splice( index, 1 );
|
|
}
|
|
},
|
|
|
|
/**
|
|
* Checks if there is any listener registered to a given event.
|
|
* @param {String} eventName The event name.
|
|
* @example
|
|
* var myListener = function() { ... };
|
|
* someObject.on( 'someEvent', myListener );
|
|
* alert( someObject.<b>hasListeners( 'someEvent' )</b> ); // "true"
|
|
* alert( someObject.<b>hasListeners( 'noEvent' )</b> ); // "false"
|
|
*/
|
|
hasListeners : function( eventName )
|
|
{
|
|
var event = getPrivate( this )[ eventName ];
|
|
return ( event && event.listeners.length > 0 ) ;
|
|
}
|
|
};
|
|
})();
|
|
}
|