ckeditor 3.4.2 → 3.4.3.pre

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/env.js

@@ -11,9 +11,7 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 if ( !CKEDITOR.env )
 {
 	/**
-	 * Environment and browser information.
-	 * @namespace
-	 * @example
+	 * @namespace Environment and browser information.
 	 */
 	CKEDITOR.env = (function()
 	{
@@ -69,10 +67,32 @@ if ( !CKEDITOR.env )
 			 */
 			mac	: ( agent.indexOf( 'macintosh' ) > -1 ),
 
+			/**
+			 * Indicates that CKEditor is running on a quirks mode environemnt.
+			 * @type Boolean
+			 * @example
+			 * if ( CKEDITOR.env.quirks )
+			 *     alert( "Nooooo!" );
+			 */
 			quirks : ( document.compatMode == 'BackCompat' ),
 
+			/**
+			 * Indicates that CKEditor is running on a mobile like environemnt.
+			 * @type Boolean
+			 * @example
+			 * if ( CKEDITOR.env.mobile )
+			 *     alert( "I'm running with CKEditor today!" );
+			 */
 			mobile : ( agent.indexOf( 'mobile' ) > -1 ),
 
+			/**
+			 * Indicates that the browser has a custom domain enabled. This has
+			 * been set with "document.domain".
+			 * @returns {Boolean} "true" if a custom domain is enabled.
+			 * @example
+			 * if ( CKEDITOR.env.isCustomDomain() )
+			 *     alert( "I'm in a custom domain!" );
+			 */
 			isCustomDomain : function()
 			{
 				if ( !this.ie )
@@ -105,19 +125,34 @@ if ( !CKEDITOR.env )
 			version = parseFloat( agent.match( /msie (\d+)/ )[1] );
 
 			/**
-			 *  Indicate IE8 browser.
+			 * Indicates that CKEditor is running on Internet Explorer 8.
+			 * @name CKEDITOR.env.ie8
+			 * @type Boolean
+			 * @example
+			 * if ( CKEDITOR.env.ie8 )
+			 *     alert( "I'm on IE8!" );
 			 */
 			env.ie8 = !!document.documentMode;
 
 			/**
-			 * Indicte IE8 document mode.
+			 * Indicates that CKEditor is running on Internet Explorer 8 on
+			 * standards mode.
+			 * @name CKEDITOR.env.ie8Compat
+			 * @type Boolean
+			 * @example
+			 * if ( CKEDITOR.env.ie8Compat )
+			 *     alert( "Now I'm on IE8, for real!" );
 			 */
 			env.ie8Compat = document.documentMode == 8;
 
 			/**
 			 * Indicates that CKEditor is running on an IE7-like environment, which
 			 * includes IE7 itself and IE8's IE7 document mode.
+			 * @name CKEDITOR.env.ie7Compat
 			 * @type Boolean
+			 * @example
+			 * if ( CKEDITOR.env.ie8Compat )
+			 *     alert( "I'm on IE7 or on an IE7 like IE8!" );
 			 */
 			env.ie7Compat = ( ( version == 7 && !document.documentMode )
 					|| document.documentMode == 7 );
@@ -125,13 +160,13 @@ if ( !CKEDITOR.env )
 			/**
 			 * Indicates that CKEditor is running on an IE6-like environment, which
 			 * includes IE6 itself and IE7 and IE8 quirks mode.
+			 * @name CKEDITOR.env.ie6Compat
 			 * @type Boolean
 			 * @example
 			 * if ( CKEDITOR.env.ie6Compat )
 			 *     alert( "I'm on IE6 or quirks mode!" );
 			 */
 			env.ie6Compat = ( version < 7 || env.quirks );
-
 		}
 
 		// Gecko.
@@ -160,12 +195,12 @@ if ( !CKEDITOR.env )
 			version = parseFloat( agent.match( / applewebkit\/(\d+)/ )[1] );
 
 		/**
-		 * Contains the browser version.
-		 *
+		 * Contains the browser version.<br />
+		 * <br />
 		 * For gecko based browsers (like Firefox) it contains the revision
 		 * number with first three parts concatenated with a padding zero
-		 * (e.g. for revision 1.9.0.2 we have 10900).
-		 *
+		 * (e.g. for revision 1.9.0.2 we have 10900).<br />
+		 * <br />
 		 * For webkit based browser (like Safari and Chrome) it contains the
 		 * WebKit build version (e.g. 522).
 		 * @name CKEDITOR.env.version
@@ -193,8 +228,14 @@ if ( !CKEDITOR.env )
 			( env.webkit && version >= 522 ) ||
 			false );
 
-		// The CSS class to be appended on the main UI containers, making it
-		// easy to apply browser specific styles to it.
+		/**
+		 * The CSS class to be appended on the main UI containers, making it
+		 * easy to apply browser specific styles to it.
+		 * @name CKEDITOR.env.cssClass
+		 * @type String
+		 * @example
+		 * myDiv.className = CKEDITOR.env.cssClass;
+		 */
 		env.cssClass =
 			'cke_browser_' + (
 				env.ie ? 'ie' :
@@ -211,7 +252,7 @@ if ( !CKEDITOR.env )
 		{
 			env.cssClass += ' cke_browser_ie' + (
 				env.version < 7 ? '6' :
-				env.version >= 8 ? '8' :
+				env.version >= 8 ? document.documentMode:
 				'7' );
 
 			if ( env.quirks )

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/event.js

@@ -11,9 +11,15 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 if ( !CKEDITOR.event )
 {
 	/**
-	 * This is a base class for classes and objects that require event handling
-	 * features.
-	 * @constructor
+	 * Creates an event class instance. This constructor is rearely used, being
+	 * the {@link #.implementOn} function used in class prototypes directly
+	 * instead.
+	 * @class This is a base class for classes and objects that require event
+	 * handling features.<br />
+	 * <br />
+	 * Do not confuse this class with {@link CKEDITOR.dom.event} which is
+	 * instead used for DOM events. The CKEDITOR.event class implements the
+	 * internal event system used by the CKEditor to fire API related events.
 	 * @example
 	 */
 	CKEDITOR.event = function()
@@ -21,7 +27,7 @@ if ( !CKEDITOR.event )
 
 	/**
 	 * Implements the {@link CKEDITOR.event} features in an object.
-	 * @param {Object} targetObject The object in which implement the features.
+	 * @param {Object} targetObject The object into which implement the features.
 	 * @example
 	 * var myObject = { message : 'Example' };
 	 * <b>CKEDITOR.event.implementOn( myObject }</b>;
@@ -31,7 +37,7 @@ if ( !CKEDITOR.event )
 	 *     });
 	 * myObject.fire( 'testEvent' );
 	 */
-	CKEDITOR.event.implementOn = function( targetObject, isTargetPrototype )
+	CKEDITOR.event.implementOn = function( targetObject )
 	{
 		var eventProto = CKEDITOR.event.prototype;
 

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/eventInfo.js

@@ -10,11 +10,11 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
  */
 
 /**
- * This class is not really part of the API. It just illustrates the features
- * of the event object passed to event listeners by a {@link CKEDITOR.event}
- * based object.
+ * (Virtual Class) Do not call this constructor. This class is not really part
+ * of the API.
+ * @class Virtual class that illustrates the features of the event object to be
+ * passed to event listeners by a {@link CKEDITOR.event} based object.
  * @name CKEDITOR.eventInfo
- * @constructor
  * @example
  * // Do not do this.
  * var myEvent = new CKEDITOR.eventInfo();  // Error: CKEDITOR.eventInfo is undefined

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/focusmanager.js

@@ -9,11 +9,14 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
  */
 
 /**
- * Manages the focus activity in an editor instance. This class is to be used
- * mainly by UI elements coders when adding interface elements to CKEditor.
- * @constructor
+ * Creates a focusManager class instance.
+ * @class Manages the focus activity in an editor instance. This class is to be
+ * used mainly by UI elements coders when adding interface elements that need
+ * to set the focus state of the editor.
  * @param {CKEDITOR.editor} editor The editor instance.
  * @example
+ * var focusManager = <b>new CKEDITOR.focusManager( editor )</b>;
+ * focusManager.focus();
  */
 CKEDITOR.focusManager = function( editor )
 {
@@ -43,9 +46,10 @@ CKEDITOR.focusManager = function( editor )
 CKEDITOR.focusManager.prototype =
 {
 	/**
-	 * Indicates that the editor instance has the focus.
-	 *
-	 * This function is not used to set the focus in the editor. Use
+	 * Used to indicate that the editor instance has the focus.<br />
+	 * <br />
+	 * Note that this function will not explicitelly set the focus in the
+	 * editor (for example, making the caret blinking on it). Use
 	 * {@link CKEDITOR.editor#focus} for it instead.
 	 * @example
 	 * var editor = CKEDITOR.instances.editor1;
@@ -76,10 +80,11 @@ CKEDITOR.focusManager.prototype =
 	},
 
 	/**
-	 * Indicates that the editor instance has lost the focus. Note that this
-	 * functions acts asynchronously with a delay of 100ms to avoid subsequent
-	 * blur/focus effects. If you want the "blur" to happen immediately, use
-	 * the {@link #forceBlur} function instead.
+	 * Used to indicate that the editor instance has lost the focus.<br />
+	 * <br />
+	 * Note that this functions acts asynchronously with a delay of 100ms to
+	 * avoid subsequent blur/focus effects. If you want the "blur" to happen
+	 * immediately, use the {@link #forceBlur} function instead.
 	 * @example
 	 * var editor = CKEDITOR.instances.editor1;
 	 * <b>editor.focusManager.blur()</b>;
@@ -101,7 +106,7 @@ CKEDITOR.focusManager.prototype =
 	},
 
 	/**
-	 * Indicates that the editor instance has lost the focus. Unlike
+	 * Used to indicate that the editor instance has lost the focus. Unlike
 	 * {@link #blur}, this function is synchronous, marking the instance as
 	 * "blured" immediately.
 	 * @example
@@ -127,6 +132,11 @@ CKEDITOR.focusManager.prototype =
  * @name CKEDITOR.editor#focus
  * @event
  * @param {CKEDITOR.editor} editor The editor instance.
+ * @example
+ * editor.on( 'focus', function( e )
+ *     {
+ *         alert( 'The editor named ' + e.editor.name + ' is now focused' );
+ *     });
  */
 
 /**
@@ -134,4 +144,9 @@ CKEDITOR.focusManager.prototype =
  * @name CKEDITOR.editor#blur
  * @event
  * @param {CKEDITOR.editor} editor The editor instance.
+ * @example
+ * editor.on( 'blur', function( e )
+ *     {
+ *         alert( 'The editor named ' + e.editor.name + ' lost the focus' );
+ *     });
  */

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/htmlparser.js

@@ -4,9 +4,15 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 */
 
 /**
- * HTML text parser.
- * @constructor
+ * Creates a {@link CKEDITOR.htmlParser} class instance.
+ * @class Provides an "event like" system to parse strings of HTML data.
  * @example
+ * var parser = new CKEDITOR.htmlParser();
+ * parser.onTagOpen = function( tagName, attributes, selfClosing )
+ *     {
+ *         alert( tagName );
+ *     };
+ * parser.parse( '<p>Some <b>text</b>.</p>' );
  */
 CKEDITOR.htmlParser = function()
 {
@@ -92,7 +98,7 @@ CKEDITOR.htmlParser = function()
 		 * @param {String} comment The comment text.
 		 * @example
 		 * var parser = new CKEDITOR.htmlParser();
-		 * parser.onText = function( comment )
+		 * parser.onComment = function( comment )
 		 *     {
 		 *         alert( comment );  // e.g. " Example "
 		 *     });

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/htmlparser/fragment.js

@@ -237,6 +237,12 @@ CKEDITOR.htmlParser.fragment = function()
 				{
 					addElement( currentNode, currentNode.parent );
 				}
+				else if ( tagName in CKEDITOR.dtd.$listItem )
+				{
+					parser.onTagOpen( 'ul', {} );
+					addPoint = currentNode;
+					reApply = true;
+				}
 				else
 				{
 					if ( nonBreakingBlocks[ currentName ] )
@@ -386,6 +392,7 @@ CKEDITOR.htmlParser.fragment = function()
 
 		parser.onComment = function( comment )
 		{
+			checkPending();
 			currentNode.add( new CKEDITOR.htmlParser.comment( comment ) );
 		};
 

data/lib/generators/ckeditor/base/templates/ckeditor/_source/core/imagecacher.js

@@ -0,0 +1,80 @@
+/*
+Copyright (c) 2003-2010, CKSource - Frederico Knabben. All rights reserved.
+For licensing, see LICENSE.html or http://ckeditor.com/license
+*/
+
+(function()
+{
+	var loaded = {};
+
+	var loadImage = function( image, callback )
+	{
+		var doCallback = function()
+			{
+				img.removeAllListeners();
+				loaded[ image ] = 1;
+				callback();
+			};
+
+		var img = new CKEDITOR.dom.element( 'img' );
+		img.on( 'load', doCallback );
+		img.on( 'error', doCallback );
+		img.setAttribute( 'src', image );
+	};
+
+	/**
+	 * @namespace Load images into the browser cache.
+	 */
+ 	CKEDITOR.imageCacher =
+	{
+		/**
+		 * Loads one or more images.
+		 * @param {Array} images The URLs of the images to be loaded.
+		 * @param {Function} [callback] A function to be called once all images
+		 *		are loaded.
+		 * @return {CKEDITOR.event} An event object which fires the 'loaded'
+		 *		event when all images are completely loaded. Additionally, the
+		 *		"finished" property is set after the "loaded" event call.
+		 * @example
+		 * var loader = CKEDITOR.imageCacher.load( [ '/image1.png', 'image2.png' ] );
+		 * if ( !loader.finished )
+		 * {
+		 *     loader.on( 'load', function()
+		 *         {
+		 *             alert( 'All images are loaded' );
+		 *         });
+		 * }
+		 */
+		load : function( images, callback )
+		{
+			var pendingCount = images.length;
+
+			var event = new CKEDITOR.event;
+			event.on( 'loaded', function()
+				{
+					event.finished = 1;
+				});
+
+			if ( callback )
+				event.on( 'loaded', callback );
+
+			var checkPending = function()
+				{
+					if ( --pendingCount === 0 )
+						event.fire( 'loaded' );
+				};
+
+			for ( var i = 0 ; i < images.length ; i++ )
+			{
+				var image = images[ i ];
+
+				if ( loaded[ image ] )
+					checkPending();
+				else
+					loadImage( image, checkPending );
+			}
+
+			return event;
+		}
+	};
+})();

data/{generators/ckeditor_install → lib/generators/ckeditor/base}/templates/ckeditor/_source/core/lang.js

@@ -7,6 +7,9 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 {
 	var loadedLangs = {};
 
+	/**
+	 * @namespace Holds language related functions.
+	 */
 	CKEDITOR.lang =
 	{
 		/**
@@ -81,12 +84,11 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 		 * Loads a specific language file, or auto detect it. A callback is
 		 * then called when the file gets loaded.
 		 * @param {String} languageCode The code of the language file to be
-		 *		loaded. If "autoDetect" is set to true, this language will be
-		 *		used as the default one, if the detect language is not
-		 *		available in the core.
-		 * @param {Boolean} autoDetect Indicates that the function must try to
-		 *		detect the user language and load it instead.
-		 * @param {Function} callback The function to be called once the
+		 *		loaded. If null or empty, autodetection will be performed. The
+		 *		same happens if the language is not supported.
+		 * @param {String} defaultLanguage The language to be used if
+		 *		languageCode is not supported or if the autodetection fails.
+		 * @param {Function} callback A function to be called once the
 		 *		language file is loaded. Two parameters are passed to this
 		 *		function: the language code and the loaded language entries.
 		 * @example
@@ -121,6 +123,8 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 		 * supported, a default language is then returned.
 		 * @param {String} defaultLanguage The default language to be returned
 		 *		if the user language is not supported.
+		 * @param {String} [probeLanguage] A language code to try to use,
+		 *		instead of the browser based autodetection.
 		 * @returns {String} The detected language code.
 		 * @example
 		 * alert( CKEDITOR.lang.detect( 'en' ) );  // e.g., in a German browser: "de"