vanilla ckeditor-3.4.2

[ckeditor.git] / _source / core / tools.js

diff --git a/_source/core/tools.js b/_source/core/tools.js
index 0fd703f..ee00f91 100644 (file)
--- a/_source/core/tools.js
+++ b/_source/core/tools.js
@@ -12,6 +12,11 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 {\r
        var functions = [];\r
 \r
+       CKEDITOR.on( 'reset', function()\r
+               {\r
+                       functions = [];\r
+               });\r
+\r
        /**\r
         * Utility functions.\r
         * @namespace\r
@@ -215,6 +220,10 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                        return ( !!object && object instanceof Array );\r
                },\r
 \r
+               /**\r
+                * Whether the object contains no properties of it's own.\r
+                * @param object\r
+                */\r
                isEmpty : function ( object )\r
                {\r
                        for ( var i in object )\r
@@ -224,6 +233,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                        }\r
                        return true;\r
                },\r
+\r
                /**\r
                 * Transforms a CSS property name to its relative DOM style name.\r
                 * @param {String} cssName The CSS property name.\r
@@ -255,7 +265,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                } )(),\r
 \r
                /**\r
-                * Build the HTML snippet of a set of <style>/<link>.\r
+                * Build the HTML snippet of a set of &lt;style>/&lt;link>.\r
                 * @param css {String|Array} Each of which are url (absolute) of a CSS file or\r
                 * a trunk of style text.\r
                 */\r
@@ -323,16 +333,16 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                },\r
 \r
                /**\r
-                * Replace characters can't be represented through CSS Selectors string\r
-                * by CSS Escape Notation where the character escape sequence consists\r
-                * of a backslash character (\) followed by the orginal characters.\r
-                * Ref: http://www.w3.org/TR/css3-selectors/#grammar\r
-                * @param cssSelectText\r
-                * @return the escaped selector text.\r
+                * Replace special HTML characters in HTMLElement's attribute with their relative HTML entity values.\r
+                * @param {String} The attribute's value to be encoded.\r
+                * @returns {String} The encode value.\r
+                * @example\r
+                * element.setAttribute( 'title', '<a " b >' );\r
+                * alert( CKEDITOR.tools.htmlEncodeAttr( element.getAttribute( 'title' ) );  // "&gt;a &quot; b &lt;"\r
                 */\r
-               escapeCssSelector : function( cssSelectText )\r
+               htmlEncodeAttr : function( text )\r
                {\r
-                       return cssSelectText.replace( /[\s#:.,$*^\[\]()~=+>]/g, '\\$&' );\r
+                       return text.replace( /"/g, '&quot;' ).replace( /</g, '&lt;' ).replace( />/g, '&gt;' );\r
                },\r
 \r
                /**\r
@@ -354,6 +364,20 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                })(),\r
 \r
                /**\r
+                * Gets a unique ID for CKEditor's interface elements. It returns a\r
+                * string with the "cke_" prefix and a progressive number.\r
+                * @function\r
+                * @returns {String} A unique ID.\r
+                * @example\r
+                * alert( CKEDITOR.tools.<b>getNextId()</b> );  // "cke_1" (e.g.)\r
+                * alert( CKEDITOR.tools.<b>getNextId()</b> );  // "cke_2"\r
+                */\r
+               getNextId : function()\r
+               {\r
+                       return 'cke_' + this.getNextNumber();\r
+               },\r
+\r
+               /**\r
                 * Creates a function override.\r
                 * @param {Function} originalFunction The function to be overridden.\r
                 * @param {Function} functionBuilder A function that returns the new\r
@@ -540,7 +564,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                 * <li> Public (prototype) fields </li>\r
                 * <li> Chainable base class constructor </li>\r
                 * </ul>\r
-                * @param {Object} definiton The class definiton object.\r
+                * @param {Object} definition The class definition object.\r
                 * @returns {Function} A class-like JavaScript function.\r
                 */\r
                createClass : function( definition )\r
@@ -650,6 +674,10 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                        return fn && fn.apply( window, Array.prototype.slice.call( arguments, 1 ) );\r
                },\r
 \r
+               /**\r
+                * Append the 'px' length unit to the size if it's missing.\r
+                * @param length\r
+                */\r
                cssLength : (function()\r
                {\r
                        var decimalRegex = /^\d+(?:\.\d+)?$/;\r
@@ -659,11 +687,20 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                        };\r
                })(),\r
 \r
+               /**\r
+                * String specified by {@param str} repeats {@param times} times.\r
+                * @param str\r
+                * @param times\r
+                */\r
                repeat : function( str, times )\r
                {\r
                        return new Array( times + 1 ).join( str );\r
                },\r
 \r
+               /**\r
+                * Return the first successfully executed function's return value that\r
+                * doesn't throw any exception.\r
+                */\r
                tryThese : function()\r
                {\r
                        var returnValue;\r
@@ -678,6 +715,18 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
                                catch (e) {}\r
                        }\r
                        return returnValue;\r
+               },\r
+\r
+               /**\r
+                * Generate a combined key from a series of params.\r
+                * @param {String} subKey One or more string used as sub keys.\r
+                * @example\r
+                * var key = CKEDITOR.tools.genKey( 'key1', 'key2', 'key3' );\r
+                * alert( key );                // "key1-key2-key3".\r
+                */\r
+               genKey : function()\r
+               {\r
+                       return Array.prototype.slice.call( arguments ).join( '-' );\r
                }\r
        };\r
 })();\r