_source/core/tools.js

   1 /*\r
   2 Copyright (c) 2003-2009, CKSource - Frederico Knabben. All rights reserved.\r
   3 For licensing, see LICENSE.html or http://ckeditor.com/license\r
   4 */\r
   5 \r
   6 /**\r
   7  * @fileOverview Defines the {@link CKEDITOR.tools} object, which contains\r
   8  *              utility functions.\r
   9  */\r
  10 \r
  11 (function()\r
  12 {\r
  13         var functions = [];\r
  14 \r
  15         /**\r
  16          * Utility functions.\r
  17          * @namespace\r
  18          * @example\r
  19          */\r
  20         CKEDITOR.tools =\r
  21         {\r
  22                 arrayCompare : function( arrayA, arrayB )\r
  23                 {\r
  24                         if ( !arrayA && !arrayB )\r
  25                                 return true;\r
  26 \r
  27                         if ( !arrayA || !arrayB || arrayA.length != arrayB.length )\r
  28                                 return false;\r
  29 \r
  30                         for ( var i = 0 ; i < arrayA.length ; i++ )\r
  31                         {\r
  32                                 if ( arrayA[ i ] != arrayB[ i ] )\r
  33                                         return false;\r
  34                         }\r
  35 \r
  36                         return true;\r
  37                 },\r
  38 \r
  39                 /**\r
  40                  * Creates a deep copy of an object.\r
  41                  * Attention: there is no support for recursive references.\r
  42                  * @param {Object} object The object to be cloned.\r
  43                  * @returns {Object} The object clone.\r
  44                  * @example\r
  45                  * var obj =\r
  46                  *     {\r
  47                  *         name : 'John',\r
  48                  *         cars :\r
  49                  *             {\r
  50                  *                 Mercedes : { color : 'blue' },\r
  51                  *                 Porsche : { color : 'red' }\r
  52                  *             }\r
  53                  *     };\r
  54                  * var clone = CKEDITOR.tools.clone( obj );\r
  55                  * clone.name = 'Paul';\r
  56                  * clone.cars.Porsche.color = 'silver';\r
  57                  * alert( obj.name );   // John\r
  58                  * alert( clone.name ); // Paul\r
  59                  * alert( obj.cars.Porsche.color );     // red\r
  60                  * alert( clone.cars.Porsche.color );   // silver\r
  61                  */\r
  62                 clone : function( obj )\r
  63                 {\r
  64                         var clone;\r
  65 \r
  66                         // Array.\r
  67                         if ( obj && ( obj instanceof Array ) )\r
  68                         {\r
  69                                 clone = [];\r
  70 \r
  71                                 for ( var i = 0 ; i < obj.length ; i++ )\r
  72                                         clone[ i ] = this.clone( obj[ i ] );\r
  73 \r
  74                                 return clone;\r
  75                         }\r
  76 \r
  77                         // "Static" types.\r
  78                         if ( obj === null\r
  79                                 || ( typeof( obj ) != 'object' )\r
  80                                 || ( obj instanceof String )\r
  81                                 || ( obj instanceof Number )\r
  82                                 || ( obj instanceof Boolean )\r
  83                                 || ( obj instanceof Date ) )\r
  84                         {\r
  85                                 return obj;\r
  86                         }\r
  87 \r
  88                         // Objects.\r
  89                         clone = new obj.constructor();\r
  90 \r
  91                         for ( var propertyName in obj )\r
  92                         {\r
  93                                 var property = obj[ propertyName ];\r
  94                                 clone[ propertyName ] = this.clone( property );\r
  95                         }\r
  96 \r
  97                         return clone;\r
  98                 },\r
  99 \r
 100                 /**\r
 101                  * Copy the properties from one object to another. By default, properties\r
 102                  * already present in the target object <strong>are not</strong> overwritten.\r
 103                  * @param {Object} target The object to be extended.\r
 104                  * @param {Object} source[,souce(n)] The objects from which copy\r
 105                  *              properties. Any number of objects can be passed to this function.\r
 106                  * @param {Boolean} [overwrite] If 'true' is specified it indicates that\r
 107                  *            properties already present in the target object could be\r
 108                  *            overwritten by subsequent objects.\r
 109                  * @param {Object} [properties] Only properties within the specified names\r
 110                  *            list will be received from the source object.\r
 111                  * @returns {Object} the extended object (target).\r
 112                  * @example\r
 113                  * // Create the sample object.\r
 114                  * var myObject =\r
 115                  * {\r
 116                  *     prop1 : true\r
 117                  * };\r
 118                  *\r
 119                  * // Extend the above object with two properties.\r
 120                  * CKEDITOR.tools.extend( myObject,\r
 121                  *     {\r
 122                  *         prop2 : true,\r
 123                  *         prop3 : true\r
 124                  *     } );\r
 125                  *\r
 126                  * // Alert "prop1", "prop2" and "prop3".\r
 127                  * for ( var p in myObject )\r
 128                  *     alert( p );\r
 129                  */\r
 130                 extend : function( target )\r
 131                 {\r
 132                         var argsLength = arguments.length,\r
 133                                 overwrite, propertiesList;\r
 134 \r
 135                         if ( typeof ( overwrite = arguments[ argsLength - 1 ] ) == 'boolean')\r
 136                                 argsLength--;\r
 137                         else if ( typeof ( overwrite = arguments[ argsLength - 2 ] ) == 'boolean' )\r
 138                         {\r
 139                                 propertiesList = arguments [ argsLength -1 ];\r
 140                                 argsLength-=2;\r
 141                         }\r
 142                         for ( var i = 1 ; i < argsLength ; i++ )\r
 143                         {\r
 144                                 var source = arguments[ i ];\r
 145                                 for ( var propertyName in source )\r
 146                                 {\r
 147                                         // Only copy existed fields if in overwrite mode.\r
 148                                         if ( overwrite === true || target[ propertyName ] == undefined )\r
 149                                         {\r
 150                                                 // Only copy  specified fields if list is provided.\r
 151                                                 if ( !propertiesList || ( propertyName in propertiesList ) )\r
 152                                                         target[ propertyName ] = source[ propertyName ];\r
 153 \r
 154                                         }\r
 155                                 }\r
 156                         }\r
 157 \r
 158                         return target;\r
 159                 },\r
 160 \r
 161                 /**\r
 162                  * Creates an object which is an instance of a class which prototype is a\r
 163                  * predefined object. All properties defined in the source object are\r
 164                  * automatically inherited by the resulting object, including future\r
 165                  * changes to it.\r
 166                  * @param {Object} source The source object to be used as the prototype for\r
 167                  *              the final object.\r
 168                  * @returns {Object} The resulting copy.\r
 169                  */\r
 170                 prototypedCopy : function( source )\r
 171                 {\r
 172                         var copy = function()\r
 173                         {};\r
 174                         copy.prototype = source;\r
 175                         return new copy();\r
 176                 },\r
 177 \r
 178                 /**\r
 179                  * Checks if an object is an Array.\r
 180                  * @param {Object} object The object to be checked.\r
 181                  * @type Boolean\r
 182                  * @returns <i>true</i> if the object is an Array, otherwise <i>false</i>.\r
 183                  * @example\r
 184                  * alert( CKEDITOR.tools.isArray( [] ) );      // "true"\r
 185                  * alert( CKEDITOR.tools.isArray( 'Test' ) );  // "false"\r
 186                  */\r
 187                 isArray : function( object )\r
 188                 {\r
 189                         return ( !!object && object instanceof Array );\r
 190                 },\r
 191 \r
 192                 /**\r
 193                  * Transforms a CSS property name to its relative DOM style name.\r
 194                  * @param {String} cssName The CSS property name.\r
 195                  * @returns {String} The transformed name.\r
 196                  * @example\r
 197                  * alert( CKEDITOR.tools.cssStyleToDomStyle( 'background-color' ) );  // "backgroundColor"\r
 198                  * alert( CKEDITOR.tools.cssStyleToDomStyle( 'float' ) );             // "cssFloat"\r
 199                  */\r
 200                 cssStyleToDomStyle : ( function()\r
 201                 {\r
 202                         var test = document.createElement( 'div' ).style;\r
 203 \r
 204                         var cssFloat = ( typeof test.cssFloat != 'undefined' ) ? 'cssFloat'\r
 205                                 : ( typeof test.styleFloat != 'undefined' ) ? 'styleFloat'\r
 206                                 : 'float';\r
 207 \r
 208                         return function( cssName )\r
 209                         {\r
 210                                 if ( cssName == 'float' )\r
 211                                         return cssFloat;\r
 212                                 else\r
 213                                 {\r
 214                                         return cssName.replace( /-./g, function( match )\r
 215                                                 {\r
 216                                                         return match.substr( 1 ).toUpperCase();\r
 217                                                 });\r
 218                                 }\r
 219                         };\r
 220                 } )(),\r
 221 \r
 222                 /**\r
 223                  * Replace special HTML characters in a string with their relative HTML\r
 224                  * entity values.\r
 225                  * @param {String} text The string to be encoded.\r
 226                  * @returns {String} The encode string.\r
 227                  * @example\r
 228                  * alert( CKEDITOR.tools.htmlEncode( 'A > B & C < D' ) );  // "A &amp;gt; B &amp;amp; C &amp;lt; D"\r
 229                  */\r
 230                 htmlEncode : function( text )\r
 231                 {\r
 232                         var standard = function( text )\r
 233                         {\r
 234                                 var span = new CKEDITOR.dom.element( 'span' );\r
 235                                 span.setText( text );\r
 236                                 return span.getHtml();\r
 237                         };\r
 238 \r
 239                         var fix1 = ( standard( '\n' ).toLowerCase() == '<br>' ) ?\r
 240                                 function( text )\r
 241                                 {\r
 242                                         // #3874 IE and Safari encode line-break into <br>\r
 243                                         return standard( text ).replace( /<br>/gi, '\n' );\r
 244                                 } :\r
 245                                 standard;\r
 246 \r
 247                         var fix2 = ( standard( '>' ) == '>' ) ?\r
 248                                 function( text )\r
 249                                 {\r
 250                                         // WebKit does't encode the ">" character, which makes sense, but\r
 251                                         // it's different than other browsers.\r
 252                                         return fix1( text ).replace( />/g, '&gt;' );\r
 253                                 } :\r
 254                                 fix1;\r
 255 \r
 256                         var fix3 = ( standard( '  ' ) == '&nbsp; ' ) ?\r
 257                                 function( text )\r
 258                                 {\r
 259                                         // #3785 IE8 changes spaces (>= 2) to &nbsp;\r
 260                                         return fix2( text ).replace( /&nbsp;/g, ' ' );\r
 261                                 } :\r
 262                                 fix2;\r
 263 \r
 264                         this.htmlEncode = fix3;\r
 265 \r
 266                         return this.htmlEncode( text );\r
 267                 },\r
 268 \r
 269                 /**\r
 270                  * Gets a unique number for this CKEDITOR execution session. It returns\r
 271                  * progressive numbers starting at 1.\r
 272                  * @function\r
 273                  * @returns {Number} A unique number.\r
 274                  * @example\r
 275                  * alert( CKEDITOR.tools.<b>getNextNumber()</b> );  // "1" (e.g.)\r
 276                  * alert( CKEDITOR.tools.<b>getNextNumber()</b> );  // "2"\r
 277                  */\r
 278                 getNextNumber : (function()\r
 279                 {\r
 280                         var last = 0;\r
 281                         return function()\r
 282                         {\r
 283                                 return ++last;\r
 284                         };\r
 285                 })(),\r
 286 \r
 287                 /**\r
 288                  * Creates a function override.\r
 289                  * @param {Function} originalFunction The function to be overridden.\r
 290                  * @param {Function} functionBuilder A function that returns the new\r
 291                  *              function. The original function reference will be passed to this\r
 292                  *              function.\r
 293                  * @returns {Function} The new function.\r
 294                  * @example\r
 295                  * var example =\r
 296                  * {\r
 297                  *     myFunction : function( name )\r
 298                  *     {\r
 299                  *         alert( 'Name: ' + name );\r
 300                  *     }\r
 301                  * };\r
 302                  *\r
 303                  * example.myFunction = CKEDITOR.tools.override( example.myFunction, function( myFunctionOriginal )\r
 304                  *     {\r
 305                  *         return function( name )\r
 306                  *             {\r
 307                  *                 alert( 'Override Name: ' + name );\r
 308                  *                 myFunctionOriginal.call( this, name );\r
 309                  *             };\r
 310                  *     });\r
 311                  */\r
 312                 override : function( originalFunction, functionBuilder )\r
 313                 {\r
 314                         return functionBuilder( originalFunction );\r
 315                 },\r
 316 \r
 317                 /**\r
 318                  * Executes a function after specified delay.\r
 319                  * @param {Function} func The function to be executed.\r
 320                  * @param {Number} [milliseconds] The amount of time (millisecods) to wait\r
 321                  *              to fire the function execution. Defaults to zero.\r
 322                  * @param {Object} [scope] The object to hold the function execution scope\r
 323                  *              (the "this" object). By default the "window" object.\r
 324                  * @param {Object|Array} [args] A single object, or an array of objects, to\r
 325                  *              pass as arguments to the function.\r
 326                  * @param {Object} [ownerWindow] The window that will be used to set the\r
 327                  *              timeout. By default the current "window".\r
 328                  * @returns {Object} A value that can be used to cancel the function execution.\r
 329                  * @example\r
 330                  * CKEDITOR.tools.<b>setTimeout(\r
 331                  *     function()\r
 332                  *     {\r
 333                  *         alert( 'Executed after 2 seconds' );\r
 334                  *     },\r
 335                  *     2000 )</b>;\r
 336                  */\r
 337                 setTimeout : function( func, milliseconds, scope, args, ownerWindow )\r
 338                 {\r
 339                         if ( !ownerWindow )\r
 340                                 ownerWindow = window;\r
 341 \r
 342                         if ( !scope )\r
 343                                 scope = ownerWindow;\r
 344 \r
 345                         return ownerWindow.setTimeout(\r
 346                                 function()\r
 347                                 {\r
 348                                         if ( args )\r
 349                                                 func.apply( scope, [].concat( args ) ) ;\r
 350                                         else\r
 351                                                 func.apply( scope ) ;\r
 352                                 },\r
 353                                 milliseconds || 0 );\r
 354                 },\r
 355 \r
 356                 /**\r
 357                  * Remove spaces from the start and the end of a string. The following\r
 358                  * characters are removed: space, tab, line break, line feed.\r
 359                  * @function\r
 360                  * @param {String} str The text from which remove the spaces.\r
 361                  * @returns {String} The modified string without the boundary spaces.\r
 362                  * @example\r
 363                  * alert( CKEDITOR.tools.trim( '  example ' );  // "example"\r
 364                  */\r
 365                 trim : (function()\r
 366                 {\r
 367                         // We are not using \s because we don't want "non-breaking spaces" to be caught.\r
 368                         var trimRegex = /(?:^[ \t\n\r]+)|(?:[ \t\n\r]+$)/g;\r
 369                         return function( str )\r
 370                         {\r
 371                                 return str.replace( trimRegex, '' ) ;\r
 372                         };\r
 373                 })(),\r
 374 \r
 375                 /**\r
 376                  * Remove spaces from the start (left) of a string. The following\r
 377                  * characters are removed: space, tab, line break, line feed.\r
 378                  * @function\r
 379                  * @param {String} str The text from which remove the spaces.\r
 380                  * @returns {String} The modified string excluding the removed spaces.\r
 381                  * @example\r
 382                  * alert( CKEDITOR.tools.ltrim( '  example ' );  // "example "\r
 383                  */\r
 384                 ltrim : (function()\r
 385                 {\r
 386                         // We are not using \s because we don't want "non-breaking spaces" to be caught.\r
 387                         var trimRegex = /^[ \t\n\r]+/g;\r
 388                         return function( str )\r
 389                         {\r
 390                                 return str.replace( trimRegex, '' ) ;\r
 391                         };\r
 392                 })(),\r
 393 \r
 394                 /**\r
 395                  * Remove spaces from the end (right) of a string. The following\r
 396                  * characters are removed: space, tab, line break, line feed.\r
 397                  * @function\r
 398                  * @param {String} str The text from which remove the spaces.\r
 399                  * @returns {String} The modified string excluding the removed spaces.\r
 400                  * @example\r
 401                  * alert( CKEDITOR.tools.ltrim( '  example ' );  // "  example"\r
 402                  */\r
 403                 rtrim : (function()\r
 404                 {\r
 405                         // We are not using \s because we don't want "non-breaking spaces" to be caught.\r
 406                         var trimRegex = /[ \t\n\r]+$/g;\r
 407                         return function( str )\r
 408                         {\r
 409                                 return str.replace( trimRegex, '' ) ;\r
 410                         };\r
 411                 })(),\r
 412 \r
 413                 /**\r
 414                  * Returns the index of an element in an array.\r
 415                  * @param {Array} array The array to be searched.\r
 416                  * @param {Object} entry The element to be found.\r
 417                  * @returns {Number} The (zero based) index of the first entry that matches\r
 418                  *              the entry, or -1 if not found.\r
 419                  * @example\r
 420                  * var letters = [ 'a', 'b', 0, 'c', false ];\r
 421                  * alert( CKEDITOR.tools.indexOf( letters, '0' ) );  "-1" because 0 !== '0'\r
 422                  * alert( CKEDITOR.tools.indexOf( letters, false ) );  "4" because 0 !== false\r
 423                  */\r
 424                 indexOf :\r
 425                         // #2514: We should try to use Array.indexOf if it does exist.\r
 426                         ( Array.prototype.indexOf ) ?\r
 427                                 function( array, entry )\r
 428                                         {\r
 429                                                 return array.indexOf( entry );\r
 430                                         }\r
 431                         :\r
 432                                 function( array, entry )\r
 433                                 {\r
 434                                         for ( var i = 0, len = array.length ; i < len ; i++ )\r
 435                                         {\r
 436                                                 if ( array[ i ] === entry )\r
 437                                                         return i;\r
 438                                         }\r
 439                                         return -1;\r
 440                                 },\r
 441 \r
 442                 bind : function( func, obj )\r
 443                 {\r
 444                         return function() { return func.apply( obj, arguments ); };\r
 445                 },\r
 446 \r
 447                 /**\r
 448                  * Class creation based on prototype inheritance, with supports of the\r
 449                  * following features:\r
 450                  * <ul>\r
 451                  * <li> Static fields </li>\r
 452                  * <li> Private fields </li>\r
 453                  * <li> Public(prototype) fields </li>\r
 454                  * <li> Chainable base class constructor </li>\r
 455                  * </ul>\r
 456                  *\r
 457                  * @param {Object} definiton (Optional)The class definiton object.\r
 458                  */\r
 459                 createClass : function( definition )\r
 460                 {\r
 461                         var $ = definition.$,\r
 462                                 baseClass = definition.base,\r
 463                                 privates = definition.privates || definition._,\r
 464                                 proto = definition.proto,\r
 465                                 statics = definition.statics;\r
 466 \r
 467                         if ( privates )\r
 468                         {\r
 469                                 var originalConstructor = $;\r
 470                                 $ = function()\r
 471                                 {\r
 472                                         // Create (and get) the private namespace.\r
 473                                         var _ = this._ || ( this._ = {} );\r
 474 \r
 475                                         // Make some magic so "this" will refer to the main\r
 476                                         // instance when coding private functions.\r
 477                                         for ( var privateName in privates )\r
 478                                         {\r
 479                                                 var priv = privates[ privateName ];\r
 480 \r
 481                                                 _[ privateName ] =\r
 482                                                         ( typeof priv == 'function' ) ? CKEDITOR.tools.bind( priv, this ) : priv;\r
 483                                         }\r
 484 \r
 485                                         originalConstructor.apply( this, arguments );\r
 486                                 };\r
 487                         }\r
 488 \r
 489                         if ( baseClass )\r
 490                         {\r
 491                                 $.prototype = this.prototypedCopy( baseClass.prototype );\r
 492                                 $.prototype.constructor = $;\r
 493                                 $.prototype.base = function()\r
 494                                 {\r
 495                                         this.base = baseClass.prototype.base;\r
 496                                         baseClass.apply( this, arguments );\r
 497                                         this.base = arguments.callee;\r
 498                                 };\r
 499                         }\r
 500 \r
 501                         if ( proto )\r
 502                                 this.extend( $.prototype, proto, true );\r
 503 \r
 504                         if ( statics )\r
 505                                 this.extend( $, statics, true );\r
 506 \r
 507                         return $;\r
 508                 },\r
 509 \r
 510                 addFunction : function( fn, scope )\r
 511                 {\r
 512                         return functions.push( function()\r
 513                                 {\r
 514                                         fn.apply( scope || this, arguments );\r
 515                                 }) - 1;\r
 516                 },\r
 517 \r
 518                 callFunction : function( index )\r
 519                 {\r
 520                         var fn = functions[ index ];\r
 521                         return fn.apply( window, Array.prototype.slice.call( arguments, 1 ) );\r
 522                 },\r
 523 \r
 524                 cssLength : (function()\r
 525                 {\r
 526                         var decimalRegex = /^\d+(?:\.\d+)?$/;\r
 527                         return function( length )\r
 528                         {\r
 529                                 return length + ( decimalRegex.test( length ) ? 'px' : '' );\r
 530                         };\r
 531                 })(),\r
 532 \r
 533                 repeat : function( str, times )\r
 534                 {\r
 535                         return new Array( times + 1 ).join( str );\r
 536                 }\r
 537         };\r
 538 })();\r
 539 \r
 540 // PACKAGER_RENAME( CKEDITOR.tools )\r