_source/core/event.js

   1 /*
   2 Copyright (c) 2003-2011, CKSource - Frederico Knabben. All rights reserved.
   3 For licensing, see LICENSE.html or http://ckeditor.com/license
   4 */
   5
   6 /**
   7  * @fileOverview Defines the {@link CKEDITOR.event} class, which serves as the
   8  *              base for classes and objects that require event handling features.
   9  */
  10
  11 if ( !CKEDITOR.event )
  12 {
  13         /**
  14          * Creates an event class instance. This constructor is rearely used, being
  15          * the {@link #.implementOn} function used in class prototypes directly
  16          * instead.
  17          * @class This is a base class for classes and objects that require event
  18          * handling features.<br />
  19          * <br />
  20          * Do not confuse this class with {@link CKEDITOR.dom.event} which is
  21          * instead used for DOM events. The CKEDITOR.event class implements the
  22          * internal event system used by the CKEditor to fire API related events.
  23          * @example
  24          */
  25         CKEDITOR.event = function()
  26         {};
  27
  28         /**
  29          * Implements the {@link CKEDITOR.event} features in an object.
  30          * @param {Object} targetObject The object into which implement the features.
  31          * @example
  32          * var myObject = { message : 'Example' };
  33          * <b>CKEDITOR.event.implementOn( myObject }</b>;
  34          * myObject.on( 'testEvent', function()
  35          *     {
  36          *         alert( this.message );  // "Example"
  37          *     });
  38          * myObject.fire( 'testEvent' );
  39          */
  40         CKEDITOR.event.implementOn = function( targetObject )
  41         {
  42                 var eventProto = CKEDITOR.event.prototype;
  43
  44                 for ( var prop in eventProto )
  45                 {
  46                         if ( targetObject[ prop ] == undefined )
  47                                 targetObject[ prop ] = eventProto[ prop ];
  48                 }
  49         };
  50
  51         CKEDITOR.event.prototype = (function()
  52         {
  53                 // Returns the private events object for a given object.
  54                 var getPrivate = function( obj )
  55                 {
  56                         var _ = ( obj.getPrivate && obj.getPrivate() ) || obj._ || ( obj._ = {} );
  57                         return _.events || ( _.events = {} );
  58                 };
  59
  60                 var eventEntry = function( eventName )
  61                 {
  62                         this.name = eventName;
  63                         this.listeners = [];
  64                 };
  65
  66                 eventEntry.prototype =
  67                 {
  68                         // Get the listener index for a specified function.
  69                         // Returns -1 if not found.
  70                         getListenerIndex : function( listenerFunction )
  71                         {
  72                                 for ( var i = 0, listeners = this.listeners ; i < listeners.length ; i++ )
  73                                 {
  74                                         if ( listeners[i].fn == listenerFunction )
  75                                                 return i;
  76                                 }
  77                                 return -1;
  78                         }
  79                 };
  80
  81                 return /** @lends CKEDITOR.event.prototype */ {
  82                         /**
  83                          * Registers a listener to a specific event in the current object.
  84                          * @param {String} eventName The event name to which listen.
  85                          * @param {Function} listenerFunction The function listening to the
  86                          *              event. A single {@link CKEDITOR.eventInfo} object instanced
  87                          *              is passed to this function containing all the event data.
  88                          * @param {Object} [scopeObj] The object used to scope the listener
  89                          *              call (the this object. If omitted, the current object is used.
  90                          * @param {Object} [listenerData] Data to be sent as the
  91                          *              {@link CKEDITOR.eventInfo#listenerData} when calling the
  92                          *              listener.
  93                          * @param {Number} [priority] The listener priority. Lower priority
  94                          *              listeners are called first. Listeners with the same priority
  95                          *              value are called in registration order. Defaults to 10.
  96                          * @example
  97                          * someObject.on( 'someEvent', function()
  98                          *     {
  99                          *         alert( this == someObject );  // "true"
 100                          *     });
 101                          * @example
 102                          * someObject.on( 'someEvent', function()
 103                          *     {
 104                          *         alert( this == anotherObject );  // "true"
 105                          *     }
 106                          *     , anotherObject );
 107                          * @example
 108                          * someObject.on( 'someEvent', function( event )
 109                          *     {
 110                          *         alert( event.listenerData );  // "Example"
 111                          *     }
 112                          *     , null, 'Example' );
 113                          * @example
 114                          * someObject.on( 'someEvent', function() { ... } );                   // 2nd called
 115                          * someObject.on( 'someEvent', function() { ... }, null, null, 100 );  // 3rd called
 116                          * someObject.on( 'someEvent', function() { ... }, null, null, 1 );    // 1st called
 117                          */
 118                         on : function( eventName, listenerFunction, scopeObj, listenerData, priority )
 119                         {
 120                                 // Get the event entry (create it if needed).
 121                                 var events = getPrivate( this ),
 122                                         event = events[ eventName ] || ( events[ eventName ] = new eventEntry( eventName ) );
 123
 124                                 if ( event.getListenerIndex( listenerFunction ) < 0 )
 125                                 {
 126                                         // Get the listeners.
 127                                         var listeners = event.listeners;
 128
 129                                         // Fill the scope.
 130                                         if ( !scopeObj )
 131                                                 scopeObj = this;
 132
 133                                         // Default the priority, if needed.
 134                                         if ( isNaN( priority ) )
 135                                                 priority = 10;
 136
 137                                         var me = this;
 138
 139                                         // Create the function to be fired for this listener.
 140                                         var listenerFirer = function( editor, publisherData, stopFn, cancelFn )
 141                                         {
 142                                                 var ev =
 143                                                 {
 144                                                         name : eventName,
 145                                                         sender : this,
 146                                                         editor : editor,
 147                                                         data : publisherData,
 148                                                         listenerData : listenerData,
 149                                                         stop : stopFn,
 150                                                         cancel : cancelFn,
 151                                                         removeListener : function()
 152                                                         {
 153                                                                 me.removeListener( eventName, listenerFunction );
 154                                                         }
 155                                                 };
 156
 157                                                 listenerFunction.call( scopeObj, ev );
 158
 159                                                 return ev.data;
 160                                         };
 161                                         listenerFirer.fn = listenerFunction;
 162                                         listenerFirer.priority = priority;
 163
 164                                         // Search for the right position for this new listener, based on its
 165                                         // priority.
 166                                         for ( var i = listeners.length - 1 ; i >= 0 ; i-- )
 167                                         {
 168                                                 // Find the item which should be before the new one.
 169                                                 if ( listeners[ i ].priority <= priority )
 170                                                 {
 171                                                         // Insert the listener in the array.
 172                                                         listeners.splice( i + 1, 0, listenerFirer );
 173                                                         return;
 174                                                 }
 175                                         }
 176
 177                                         // If no position has been found (or zero length), put it in
 178                                         // the front of list.
 179                                         listeners.unshift( listenerFirer );
 180                                 }
 181                         },
 182
 183                         /**
 184                          * Fires an specific event in the object. All registered listeners are
 185                          * called at this point.
 186                          * @function
 187                          * @param {String} eventName The event name to fire.
 188                          * @param {Object} [data] Data to be sent as the
 189                          *              {@link CKEDITOR.eventInfo#data} when calling the
 190                          *              listeners.
 191                          * @param {CKEDITOR.editor} [editor] The editor instance to send as the
 192                          *              {@link CKEDITOR.eventInfo#editor} when calling the
 193                          *              listener.
 194                          * @returns {Boolean|Object} A booloan indicating that the event is to be
 195                          *              canceled, or data returned by one of the listeners.
 196                          * @example
 197                          * someObject.on( 'someEvent', function() { ... } );
 198                          * someObject.on( 'someEvent', function() { ... } );
 199                          * <b>someObject.fire( 'someEvent' )</b>;  // both listeners are called
 200                          * @example
 201                          * someObject.on( 'someEvent', function( event )
 202                          *     {
 203                          *         alert( event.data );  // "Example"
 204                          *     });
 205                          * <b>someObject.fire( 'someEvent', 'Example' )</b>;
 206                          */
 207                         fire : (function()
 208                         {
 209                                 // Create the function that marks the event as stopped.
 210                                 var stopped = false;
 211                                 var stopEvent = function()
 212                                 {
 213                                         stopped = true;
 214                                 };
 215
 216                                 // Create the function that marks the event as canceled.
 217                                 var canceled = false;
 218                                 var cancelEvent = function()
 219                                 {
 220                                         canceled = true;
 221                                 };
 222
 223                                 return function( eventName, data, editor )
 224                                 {
 225                                         // Get the event entry.
 226                                         var event = getPrivate( this )[ eventName ];
 227
 228                                         // Save the previous stopped and cancelled states. We may
 229                                         // be nesting fire() calls.
 230                                         var previousStopped = stopped,
 231                                                 previousCancelled = canceled;
 232
 233                                         // Reset the stopped and canceled flags.
 234                                         stopped = canceled = false;
 235
 236                                         if ( event )
 237                                         {
 238                                                 var listeners = event.listeners;
 239
 240                                                 if ( listeners.length )
 241                                                 {
 242                                                         // As some listeners may remove themselves from the
 243                                                         // event, the original array length is dinamic. So,
 244                                                         // let's make a copy of all listeners, so we are
 245                                                         // sure we'll call all of them.
 246                                                         listeners = listeners.slice( 0 );
 247
 248                                                         // Loop through all listeners.
 249                                                         for ( var i = 0 ; i < listeners.length ; i++ )
 250                                                         {
 251                                                                 // Call the listener, passing the event data.
 252                                                                 var retData = listeners[i].call( this, editor, data, stopEvent, cancelEvent );
 253
 254                                                                 if ( typeof retData != 'undefined' )
 255                                                                         data = retData;
 256
 257                                                                 // No further calls is stopped or canceled.
 258                                                                 if ( stopped || canceled )
 259                                                                         break;
 260                                                         }
 261                                                 }
 262                                         }
 263
 264                                         var ret = canceled || ( typeof data == 'undefined' ? false : data );
 265
 266                                         // Restore the previous stopped and canceled states.
 267                                         stopped = previousStopped;
 268                                         canceled = previousCancelled;
 269
 270                                         return ret;
 271                                 };
 272                         })(),
 273
 274                         /**
 275                          * Fires an specific event in the object, releasing all listeners
 276                          * registered to that event. The same listeners are not called again on
 277                          * successive calls of it or of {@link #fire}.
 278                          * @param {String} eventName The event name to fire.
 279                          * @param {Object} [data] Data to be sent as the
 280                          *              {@link CKEDITOR.eventInfo#data} when calling the
 281                          *              listeners.
 282                          * @param {CKEDITOR.editor} [editor] The editor instance to send as the
 283                          *              {@link CKEDITOR.eventInfo#editor} when calling the
 284                          *              listener.
 285                          * @returns {Boolean|Object} A booloan indicating that the event is to be
 286                          *              canceled, or data returned by one of the listeners.
 287                          * @example
 288                          * someObject.on( 'someEvent', function() { ... } );
 289                          * someObject.fire( 'someEvent' );  // above listener called
 290                          * <b>someObject.fireOnce( 'someEvent' )</b>;  // above listener called
 291                          * someObject.fire( 'someEvent' );  // no listeners called
 292                          */
 293                         fireOnce : function( eventName, data, editor )
 294                         {
 295                                 var ret = this.fire( eventName, data, editor );
 296                                 delete getPrivate( this )[ eventName ];
 297                                 return ret;
 298                         },
 299
 300                         /**
 301                          * Unregisters a listener function from being called at the specified
 302                          *              event. No errors are thrown if the listener has not been
 303                          *              registered previously.
 304                          * @param {String} eventName The event name.
 305                          * @param {Function} listenerFunction The listener function to unregister.
 306                          * @example
 307                          * var myListener = function() { ... };
 308                          * someObject.on( 'someEvent', myListener );
 309                          * someObject.fire( 'someEvent' );  // myListener called
 310                          * <b>someObject.removeListener( 'someEvent', myListener )</b>;
 311                          * someObject.fire( 'someEvent' );  // myListener not called
 312                          */
 313                         removeListener : function( eventName, listenerFunction )
 314                         {
 315                                 // Get the event entry.
 316                                 var event = getPrivate( this )[ eventName ];
 317
 318                                 if ( event )
 319                                 {
 320                                         var index = event.getListenerIndex( listenerFunction );
 321                                         if ( index >= 0 )
 322                                                 event.listeners.splice( index, 1 );
 323                                 }
 324                         },
 325
 326                         /**
 327                          * Checks if there is any listener registered to a given event.
 328                          * @param {String} eventName The event name.
 329                          * @example
 330                          * var myListener = function() { ... };
 331                          * someObject.on( 'someEvent', myListener );
 332                          * alert( someObject.<b>hasListeners( 'someEvent' )</b> );  // "true"
 333                          * alert( someObject.<b>hasListeners( 'noEvent' )</b> );    // "false"
 334                          */
 335                         hasListeners : function( eventName )
 336                         {
 337                                 var event = getPrivate( this )[ eventName ];
 338                                 return ( event && event.listeners.length > 0 ) ;
 339                         }
 340                 };
 341         })();
 342 }