[Summary view] [Print] [Text view]

   1  /*

   2  Copyright (c) 2003-2010, 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       * This is a base class for classes and objects that require event handling

  15       * features.

  16       * @constructor

  17       * @example

  18       */
  19      CKEDITOR.event = function()
  20      {};
  21  
  22      /**

  23       * Implements the {@link CKEDITOR.event} features in an object.

  24       * @param {Object} targetObject The object in which implement the features.

  25       * @example

  26       * var myObject = { message : 'Example' };

  27       * <b>CKEDITOR.event.implementOn( myObject }</b>;

  28       * myObject.on( 'testEvent', function()

  29       *     {

  30       *         alert( this.message );  // "Example"

  31       *     });

  32       * myObject.fire( 'testEvent' );

  33       */
  34      CKEDITOR.event.implementOn = function( targetObject, isTargetPrototype )
  35      {
  36          var eventProto = CKEDITOR.event.prototype;
  37  
  38          for ( var prop in eventProto )
  39          {
  40              if ( targetObject[ prop ] == undefined )
  41                  targetObject[ prop ] = eventProto[ prop ];
  42          }
  43      };
  44  
  45      CKEDITOR.event.prototype = (function()
  46      {
  47          // Returns the private events object for a given object.

  48          var getPrivate = function( obj )
  49          {
  50              var _ = ( obj.getPrivate && obj.getPrivate() ) || obj._ || ( obj._ = {} );
  51              return _.events || ( _.events = {} );
  52          };
  53  
  54          var eventEntry = function( eventName )
  55          {
  56              this.name = eventName;
  57              this.listeners = [];
  58          };
  59  
  60          eventEntry.prototype =
  61          {
  62              // Get the listener index for a specified function.

  63              // Returns -1 if not found.

  64              getListenerIndex : function( listenerFunction )
  65              {
  66                  for ( var i = 0, listeners = this.listeners ; i < listeners.length ; i++ )
  67                  {
  68                      if ( listeners[i].fn == listenerFunction )
  69                          return i;
  70                  }
  71                  return -1;
  72              }
  73          };
  74  
  75          return /** @lends CKEDITOR.event.prototype */ {
  76              /**

  77               * Registers a listener to a specific event in the current object.

  78               * @param {String} eventName The event name to which listen.

  79               * @param {Function} listenerFunction The function listening to the

  80               *        event. A single {@link CKEDITOR.eventInfo} object instanced

  81               *        is passed to this function containing all the event data.

  82               * @param {Object} [scopeObj] The object used to scope the listener

  83               *        call (the this object. If omitted, the current object is used.

  84               * @param {Object} [listenerData] Data to be sent as the

  85               *        {@link CKEDITOR.eventInfo#listenerData} when calling the

  86               *        listener.

  87               * @param {Number} [priority] The listener priority. Lower priority

  88               *        listeners are called first. Listeners with the same priority

  89               *        value are called in registration order. Defaults to 10.

  90               * @example

  91               * someObject.on( 'someEvent', function()

  92               *     {

  93               *         alert( this == someObject );  // "true"

  94               *     });

  95               * @example

  96               * someObject.on( 'someEvent', function()

  97               *     {

  98               *         alert( this == anotherObject );  // "true"

  99               *     }

 100               *     , anotherObject );

 101               * @example

 102               * someObject.on( 'someEvent', function( event )

 103               *     {

 104               *         alert( event.listenerData );  // "Example"

 105               *     }

 106               *     , null, 'Example' );

 107               * @example

 108               * someObject.on( 'someEvent', function() { ... } );                   // 2nd called

 109               * someObject.on( 'someEvent', function() { ... }, null, null, 100 );  // 3rd called

 110               * someObject.on( 'someEvent', function() { ... }, null, null, 1 );    // 1st called

 111               */
 112              on : function( eventName, listenerFunction, scopeObj, listenerData, priority )
 113              {
 114                  // Get the event entry (create it if needed).

 115                  var events = getPrivate( this ),
 116                      event = events[ eventName ] || ( events[ eventName ] = new eventEntry( eventName ) );
 117  
 118                  if ( event.getListenerIndex( listenerFunction ) < 0 )
 119                  {
 120                      // Get the listeners.

 121                      var listeners = event.listeners;
 122  
 123                      // Fill the scope.

 124                      if ( !scopeObj )
 125                          scopeObj = this;
 126  
 127                      // Default the priority, if needed.

 128                      if ( isNaN( priority ) )
 129                          priority = 10;
 130  
 131                      var me = this;
 132  
 133                      // Create the function to be fired for this listener.

 134                      var listenerFirer = function( editor, publisherData, stopFn, cancelFn )
 135                      {
 136                          var ev =
 137                          {
 138                              name : eventName,
 139                              sender : this,
 140                              editor : editor,
 141                              data : publisherData,
 142                              listenerData : listenerData,
 143                              stop : stopFn,
 144                              cancel : cancelFn,
 145                              removeListener : function()
 146                              {
 147                                  me.removeListener( eventName, listenerFunction );
 148                              }
 149                          };
 150  
 151                          listenerFunction.call( scopeObj, ev );
 152  
 153                          return ev.data;
 154                      };
 155                      listenerFirer.fn = listenerFunction;
 156                      listenerFirer.priority = priority;
 157  
 158                      // Search for the right position for this new listener, based on its

 159                      // priority.

 160                      for ( var i = listeners.length - 1 ; i >= 0 ; i-- )
 161                      {
 162                          // Find the item which should be before the new one.

 163                          if ( listeners[ i ].priority <= priority )
 164                          {
 165                              // Insert the listener in the array.

 166                              listeners.splice( i + 1, 0, listenerFirer );
 167                              return;
 168                          }
 169                      }
 170  
 171                      // If no position has been found (or zero length), put it in

 172                      // the front of list.

 173                      listeners.unshift( listenerFirer );
 174                  }
 175              },
 176  
 177              /**

 178               * Fires an specific event in the object. All registered listeners are

 179               * called at this point.

 180               * @function

 181               * @param {String} eventName The event name to fire.

 182               * @param {Object} [data] Data to be sent as the

 183               *        {@link CKEDITOR.eventInfo#data} when calling the

 184               *        listeners.

 185               * @param {CKEDITOR.editor} [editor] The editor instance to send as the

 186               *        {@link CKEDITOR.eventInfo#editor} when calling the

 187               *        listener.

 188               * @returns {Boolean|Object} A booloan indicating that the event is to be

 189               *        canceled, or data returned by one of the listeners.

 190               * @example

 191               * someObject.on( 'someEvent', function() { ... } );

 192               * someObject.on( 'someEvent', function() { ... } );

 193               * <b>someObject.fire( 'someEvent' )</b>;  // both listeners are called

 194               * @example

 195               * someObject.on( 'someEvent', function( event )

 196               *     {

 197               *         alert( event.data );  // "Example"

 198               *     });

 199               * <b>someObject.fire( 'someEvent', 'Example' )</b>;

 200               */
 201              fire : (function()
 202              {
 203                  // Create the function that marks the event as stopped.

 204                  var stopped = false;
 205                  var stopEvent = function()
 206                  {
 207                      stopped = true;
 208                  };
 209  
 210                  // Create the function that marks the event as canceled.

 211                  var canceled = false;
 212                  var cancelEvent = function()
 213                  {
 214                      canceled = true;
 215                  };
 216  
 217                  return function( eventName, data, editor )
 218                  {
 219                      // Get the event entry.

 220                      var event = getPrivate( this )[ eventName ];
 221  
 222                      // Save the previous stopped and cancelled states. We may

 223                      // be nesting fire() calls.

 224                      var previousStopped = stopped,
 225                          previousCancelled = canceled;
 226  
 227                      // Reset the stopped and canceled flags.

 228                      stopped = canceled = false;
 229  
 230                      if ( event )
 231                      {
 232                          var listeners = event.listeners;
 233  
 234                          if ( listeners.length )
 235                          {
 236                              // As some listeners may remove themselves from the

 237                              // event, the original array length is dinamic. So,

 238                              // let's make a copy of all listeners, so we are

 239                              // sure we'll call all of them.

 240                              listeners = listeners.slice( 0 );
 241  
 242                              // Loop through all listeners.

 243                              for ( var i = 0 ; i < listeners.length ; i++ )
 244                              {
 245                                  // Call the listener, passing the event data.

 246                                  var retData = listeners[i].call( this, editor, data, stopEvent, cancelEvent );
 247  
 248                                  if ( typeof retData != 'undefined' )
 249                                      data = retData;
 250  
 251                                  // No further calls is stopped or canceled.

 252                                  if ( stopped || canceled )
 253                                      break;
 254                              }
 255                          }
 256                      }
 257  
 258                      var ret = canceled || ( typeof data == 'undefined' ? false : data );
 259  
 260                      // Restore the previous stopped and canceled states.

 261                      stopped = previousStopped;
 262                      canceled = previousCancelled;
 263  
 264                      return ret;
 265                  };
 266              })(),
 267  
 268              /**

 269               * Fires an specific event in the object, releasing all listeners

 270               * registered to that event. The same listeners are not called again on

 271               * successive calls of it or of {@link #fire}.

 272               * @param {String} eventName The event name to fire.

 273               * @param {Object} [data] Data to be sent as the

 274               *        {@link CKEDITOR.eventInfo#data} when calling the

 275               *        listeners.

 276               * @param {CKEDITOR.editor} [editor] The editor instance to send as the

 277               *        {@link CKEDITOR.eventInfo#editor} when calling the

 278               *        listener.

 279               * @returns {Boolean|Object} A booloan indicating that the event is to be

 280               *        canceled, or data returned by one of the listeners.

 281               * @example

 282               * someObject.on( 'someEvent', function() { ... } );

 283               * someObject.fire( 'someEvent' );  // above listener called

 284               * <b>someObject.fireOnce( 'someEvent' )</b>;  // above listener called

 285               * someObject.fire( 'someEvent' );  // no listeners called

 286               */
 287              fireOnce : function( eventName, data, editor )
 288              {
 289                  var ret = this.fire( eventName, data, editor );
 290                  delete getPrivate( this )[ eventName ];
 291                  return ret;
 292              },
 293  
 294              /**

 295               * Unregisters a listener function from being called at the specified

 296               *        event. No errors are thrown if the listener has not been

 297               *        registered previously.

 298               * @param {String} eventName The event name.

 299               * @param {Function} listenerFunction The listener function to unregister.

 300               * @example

 301               * var myListener = function() { ... };

 302               * someObject.on( 'someEvent', myListener );

 303               * someObject.fire( 'someEvent' );  // myListener called

 304               * <b>someObject.removeListener( 'someEvent', myListener )</b>;

 305               * someObject.fire( 'someEvent' );  // myListener not called

 306               */
 307              removeListener : function( eventName, listenerFunction )
 308              {
 309                  // Get the event entry.

 310                  var event = getPrivate( this )[ eventName ];
 311  
 312                  if ( event )
 313                  {
 314                      var index = event.getListenerIndex( listenerFunction );
 315                      if ( index >= 0 )
 316                          event.listeners.splice( index, 1 );
 317                  }
 318              },
 319  
 320              /**

 321               * Checks if there is any listener registered to a given event.

 322               * @param {String} eventName The event name.

 323               * @example

 324               * var myListener = function() { ... };

 325               * someObject.on( 'someEvent', myListener );

 326               * alert( someObject.<b>hasListeners( 'someEvent' )</b> );  // "true"

 327               * alert( someObject.<b>hasListeners( 'noEvent' )</b> );    // "false"

 328               */
 329              hasListeners : function( eventName )
 330              {
 331                  var event = getPrivate( this )[ eventName ];
 332                  return ( event && event.listeners.length > 0 ) ;
 333              }
 334          };
 335      })();
 336  }