X-Git-Url: https://jasonwoof.com/gitweb/?a=blobdiff_plain;ds=sidebyside;f=_source%2Fcore%2Ftools.js;h=c9d9877dc1c1e5fb410427c1b9a9301a71800936;hb=7cd80714081a8ffdf4a1a8d2c72f120ed5ef3d6d;hp=6f9542869acf7288049bcb804fe2f28143eaecaf;hpb=8761695d9b70afe75905deaac88f78c1f8aeb32d;p=ckeditor.git

diff --git a/_source/core/tools.js b/_source/core/tools.js
index 6f95428..c9d9877 100644
--- a/_source/core/tools.js
+++ b/_source/core/tools.js
@@ -19,6 +19,22 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 	 */
 	CKEDITOR.tools =
 	{
+		/**
+		 * Compare the elements of two arrays.
+		 * @param {Array} arrayA An array to be compared.
+		 * @param {Array} arrayB The other array to be compared.
+		 * @returns {Boolean} "true" is the arrays have the same lenght and
+		 *		their elements match.
+		 * @example
+		 * var a = [ 1, 'a', 3 ];
+		 * var b = [ 1, 3, 'a' ];
+		 * var c = [ 1, 'a', 3 ];
+		 * var d = [ 1, 'a', 3, 4 ];
+		 *
+		 * alert( CKEDITOR.tools.arrayCompare( a, b ) );  // false
+		 * alert( CKEDITOR.tools.arrayCompare( a, c ) );  // true
+		 * alert( CKEDITOR.tools.arrayCompare( a, d ) );  // false
+		 */
 		arrayCompare : function( arrayA, arrayB )
 		{
 			if ( !arrayA && !arrayB )
@@ -189,6 +205,15 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 			return ( !!object && object instanceof Array );
 		},
 
+		isEmpty : function ( object )
+		{
+			for ( var i in object )
+			{
+				if ( object.hasOwnProperty( i ) )
+					return false;
+			}
+			return true;
+		},
 		/**
 		 * Transforms a CSS property name to its relative DOM style name.
 		 * @param {String} cssName The CSS property name.
@@ -267,6 +292,19 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 		},
 
 		/**
+		 * Replace characters can't be represented through CSS Selectors string
+		 * by CSS Escape Notation where the character escape sequence consists
+		 * of a backslash character (\) followed by the orginal characters.
+		 * Ref: http://www.w3.org/TR/css3-selectors/#grammar
+		 * @param cssSelectText
+		 * @return the escaped selector text.
+		 */
+		escapeCssSelector : function( cssSelectText )
+		{
+			return cssSelectText.replace( /[\s#:.,$*^\[\]()~=+>]/g, '\\$&' );
+		},
+
+		/**
 		 * Gets a unique number for this CKEDITOR execution session. It returns
 		 * progressive numbers starting at 1.
 		 * @function
@@ -439,6 +477,24 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 					return -1;
 				},
 
+		/**
+		 * Creates a function that will always execute in the context of a
+		 * specified object.
+		 * @param {Function} func The function to be executed.
+		 * @param {Object} obj The object to which bind the execution context.
+		 * @returns {Function} The function that can be used to execute the
+		 *		"func" function in the context of "obj".
+		 * @example
+		 * var obj = { text : 'My Object' };
+		 *
+		 * function alertText()
+		 * {
+		 *     alert( this.text );
+		 * }
+		 *
+		 * var newFunc = <b>CKEDITOR.tools.bind( alertText, obj )</b>;
+		 * newFunc();  // Alerts "My Object".
+		 */
 		bind : function( func, obj )
 		{
 			return function() { return func.apply( obj, arguments ); };
@@ -450,11 +506,11 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 		 * <ul>
 		 * <li> Static fields </li>
 		 * <li> Private fields </li>
-		 * <li> Public(prototype) fields </li>
+		 * <li> Public (prototype) fields </li>
 		 * <li> Chainable base class constructor </li>
 		 * </ul>
-		 *
-		 * @param {Object} definiton (Optional)The class definiton object.
+		 * @param {Object} definiton The class definiton object.
+		 * @returns {Function} A class-like JavaScript function.
 		 */
 		createClass : function( definition )
 		{
@@ -507,6 +563,22 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 			return $;
 		},
 
+		/**
+		 * Creates a function reference that can be called later using
+		 * CKEDITOR.tools.callFunction. This approach is specially useful to
+		 * make DOM attribute function calls to JavaScript defined functions.
+		 * @param {Function} fn The function to be executed on call.
+		 * @param {Object} [scope] The object to have the context on "fn" execution.
+		 * @returns {Number} A unique reference to be used in conjuction with
+		 *		CKEDITOR.tools.callFunction.
+		 * @example
+		 * var ref = <b>CKEDITOR.tools.addFunction</b>(
+		 *     function()
+		 *     {
+		 *         alert( 'Hello!');
+		 *     });
+		 * CKEDITOR.tools.callFunction( ref );  // Hello!
+		 */
 		addFunction : function( fn, scope )
 		{
 			return functions.push( function()
@@ -515,10 +587,26 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 				}) - 1;
 		},
 
-		callFunction : function( index )
+		/**
+		 * Executes a function based on the reference created with
+		 * CKEDITOR.tools.addFunction.
+		 * @param {Number} ref The function reference created with
+		 *		CKEDITOR.tools.addFunction.
+		 * @param {[Any,[Any,...]} params Any number of parameters to be passed
+		 *		to the executed function.
+		 * @returns {Any} The return value of the function.
+		 * @example
+		 * var ref = CKEDITOR.tools.addFunction(
+		 *     function()
+		 *     {
+		 *         alert( 'Hello!');
+		 *     });
+		 * <b>CKEDITOR.tools.callFunction( ref )</b>;  // Hello!
+		 */
+		callFunction : function( ref )
 		{
-			var fn = functions[ index ];
-			return fn.apply( window, Array.prototype.slice.call( arguments, 1 ) );
+			var fn = functions[ ref ];
+			return fn && fn.apply( window, Array.prototype.slice.call( arguments, 1 ) );
 		},
 
 		cssLength : (function()