ckeditor/_source/core/dom/domobject.js

   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.editor} class, which is the base
   8  *              for other classes representing DOM objects.
   9  */
  10
  11 /**
  12  * Represents a DOM object. This class is not intended to be used directly. It
  13  * serves as the base class for other classes representing specific DOM
  14  * objects.
  15  * @constructor
  16  * @param {Object} nativeDomObject A native DOM object.
  17  * @augments CKEDITOR.event
  18  * @example
  19  */
  20 CKEDITOR.dom.domObject = function( nativeDomObject )
  21 {
  22         if ( nativeDomObject )
  23         {
  24                 /**
  25                  * The native DOM object represented by this class instance.
  26                  * @type Object
  27                  * @example
  28                  * var element = new CKEDITOR.dom.element( 'span' );
  29                  * alert( element.$.nodeType );  // "1"
  30                  */
  31                 this.$ = nativeDomObject;
  32         }
  33 };
  34
  35 CKEDITOR.dom.domObject.prototype = (function()
  36 {
  37         // Do not define other local variables here. We want to keep the native
  38         // listener closures as clean as possible.
  39
  40         var getNativeListener = function( domObject, eventName )
  41         {
  42                 return function( domEvent )
  43                 {
  44                         // In FF, when reloading the page with the editor focused, it may
  45                         // throw an error because the CKEDITOR global is not anymore
  46                         // available. So, we check it here first. (#2923)
  47                         if ( typeof CKEDITOR != 'undefined' )
  48                                 domObject.fire( eventName, new CKEDITOR.dom.event( domEvent ) );
  49                 };
  50         };
  51
  52         return /** @lends CKEDITOR.dom.domObject.prototype */ {
  53
  54                 getPrivate : function()
  55                 {
  56                         var priv;
  57
  58                         // Get the main private function from the custom data. Create it if not
  59                         // defined.
  60                         if ( !( priv = this.getCustomData( '_' ) ) )
  61                                 this.setCustomData( '_', ( priv = {} ) );
  62
  63                         return priv;
  64                 },
  65
  66                 /** @ignore */
  67                 on  : function( eventName )
  68                 {
  69                         // We customize the "on" function here. The basic idea is that we'll have
  70                         // only one listener for a native event, which will then call all listeners
  71                         // set to the event.
  72
  73                         // Get the listeners holder object.
  74                         var nativeListeners = this.getCustomData( '_cke_nativeListeners' );
  75
  76                         if ( !nativeListeners )
  77                         {
  78                                 nativeListeners = {};
  79                                 this.setCustomData( '_cke_nativeListeners', nativeListeners );
  80                         }
  81
  82                         // Check if we have a listener for that event.
  83                         if ( !nativeListeners[ eventName ] )
  84                         {
  85                                 var listener = nativeListeners[ eventName ] = getNativeListener( this, eventName );
  86
  87                                 if ( this.$.addEventListener )
  88                                         this.$.addEventListener( eventName, listener, !!CKEDITOR.event.useCapture );
  89                                 else if ( this.$.attachEvent )
  90                                         this.$.attachEvent( 'on' + eventName, listener );
  91                         }
  92
  93                         // Call the original implementation.
  94                         return CKEDITOR.event.prototype.on.apply( this, arguments );
  95                 },
  96
  97                 /** @ignore */
  98                 removeListener : function( eventName )
  99                 {
 100                         // Call the original implementation.
 101                         CKEDITOR.event.prototype.removeListener.apply( this, arguments );
 102
 103                         // If we don't have listeners for this event, clean the DOM up.
 104                         if ( !this.hasListeners( eventName ) )
 105                         {
 106                                 var nativeListeners = this.getCustomData( '_cke_nativeListeners' );
 107                                 var listener = nativeListeners && nativeListeners[ eventName ];
 108                                 if ( listener )
 109                                 {
 110                                         if ( this.$.removeEventListener )
 111                                                 this.$.removeEventListener( eventName, listener, false );
 112                                         else if ( this.$.detachEvent )
 113                                                 this.$.detachEvent( 'on' + eventName, listener );
 114
 115                                         delete nativeListeners[ eventName ];
 116                                 }
 117                         }
 118                 },
 119
 120                 /**
 121                  * Removes any listener set on this object.
 122                  * To avoid memory leaks we must assure that there are no
 123                  * references left after the object is no longer needed.
 124                  */
 125                 removeAllListeners : function()
 126                 {
 127                         var nativeListeners = this.getCustomData( '_cke_nativeListeners' );
 128                         for ( var eventName in nativeListeners )
 129                         {
 130                                 var listener = nativeListeners[ eventName ];
 131                                 if ( this.$.removeEventListener )
 132                                         this.$.removeEventListener( eventName, listener, false );
 133                                 else if ( this.$.detachEvent )
 134                                         this.$.detachEvent( 'on' + eventName, listener );
 135
 136                                 delete nativeListeners[ eventName ];
 137                         }
 138                 }
 139         };
 140 })();
 141
 142 (function( domObjectProto )
 143 {
 144         var customData = {};
 145
 146         /**
 147          * Determines whether the specified object is equal to the current object.
 148          * @name CKEDITOR.dom.domObject.prototype.equals
 149          * @function
 150          * @param {Object} object The object to compare with the current object.
 151          * @returns {Boolean} "true" if the object is equal.
 152          * @example
 153          * var doc = new CKEDITOR.dom.document( document );
 154          * alert( doc.equals( CKEDITOR.document ) );  // "true"
 155          * alert( doc == CKEDITOR.document );         // "false"
 156          */
 157         domObjectProto.equals = function( object )
 158         {
 159                 return ( object && object.$ === this.$ );
 160         };
 161
 162         /**
 163          * Sets a data slot value for this object. These values are shared by all
 164          * instances pointing to that same DOM object.
 165          * @name CKEDITOR.dom.domObject.prototype.setCustomData
 166          * @function
 167          * @param {String} key A key used to identify the data slot.
 168          * @param {Object} value The value to set to the data slot.
 169          * @returns {CKEDITOR.dom.domObject} This DOM object instance.
 170          * @see CKEDITOR.dom.domObject.prototype.getCustomData
 171          * @example
 172          * var element = new CKEDITOR.dom.element( 'span' );
 173          * element.setCustomData( 'hasCustomData', true );
 174          */
 175         domObjectProto.setCustomData = function( key, value )
 176         {
 177                 var expandoNumber = this.getUniqueId(),
 178                         dataSlot = customData[ expandoNumber ] || ( customData[ expandoNumber ] = {} );
 179
 180                 dataSlot[ key ] = value;
 181
 182                 return this;
 183         };
 184
 185         /**
 186          * Gets the value set to a data slot in this object.
 187          * @name CKEDITOR.dom.domObject.prototype.getCustomData
 188          * @function
 189          * @param {String} key The key used to identify the data slot.
 190          * @returns {Object} This value set to the data slot.
 191          * @see CKEDITOR.dom.domObject.prototype.setCustomData
 192          * @example
 193          * var element = new CKEDITOR.dom.element( 'span' );
 194          * alert( element.getCustomData( 'hasCustomData' ) );  // e.g. 'true'
 195          */
 196         domObjectProto.getCustomData = function( key )
 197         {
 198                 var expandoNumber = this.$._cke_expando,
 199                         dataSlot = expandoNumber && customData[ expandoNumber ];
 200
 201                 return dataSlot && dataSlot[ key ];
 202         };
 203
 204         /**
 205          * @name CKEDITOR.dom.domObject.prototype.removeCustomData
 206          */
 207         domObjectProto.removeCustomData = function( key )
 208         {
 209                 var expandoNumber = this.$._cke_expando,
 210                         dataSlot = expandoNumber && customData[ expandoNumber ],
 211                         retval = dataSlot && dataSlot[ key ];
 212
 213                 if ( typeof retval != 'undefined' )
 214                         delete dataSlot[ key ];
 215
 216                 return retval || null;
 217         };
 218
 219         /**
 220          * Removes any data stored on this object.
 221          * To avoid memory leaks we must assure that there are no
 222          * references left after the object is no longer needed.
 223          * @name CKEDITOR.dom.domObject.prototype.clearCustomData
 224          * @function
 225          */
 226         domObjectProto.clearCustomData = function()
 227         {
 228                 // Clear all event listeners
 229                 this.removeAllListeners();
 230
 231                 var expandoNumber = this.$._cke_expando;
 232                 expandoNumber && delete customData[ expandoNumber ];
 233         };
 234
 235         /**
 236          * @name CKEDITOR.dom.domObject.prototype.getCustomData
 237          */
 238         domObjectProto.getUniqueId = function()
 239         {
 240                 return this.$._cke_expando || ( this.$._cke_expando = CKEDITOR.tools.getNextNumber() );
 241         };
 242
 243         // Implement CKEDITOR.event.
 244         CKEDITOR.event.implementOn( domObjectProto );
 245
 246 })( CKEDITOR.dom.domObject.prototype );