Index: /CKEditor/branches/prototype/_source/plugins/dialog/dialogDefinition.js
===================================================================
--- /CKEditor/branches/prototype/_source/plugins/dialog/dialogDefinition.js	(revision 2596)
+++ /CKEditor/branches/prototype/_source/plugins/dialog/dialogDefinition.js	(revision 2596)
@@ -0,0 +1,315 @@
+/*
+ * CKEditor - The text editor for Internet - http://ckeditor.com
+ * Copyright (C) 2003-2008 Frederico Caldeira Knabben
+ *
+ * == BEGIN LICENSE ==
+ *
+ * Licensed under the terms of any of the following licenses at your
+ * choice:
+ *
+ *  - GNU General Public License Version 2 or later (the "GPL")
+ *    http://www.gnu.org/licenses/gpl.html
+ *
+ *  - GNU Lesser General Public License Version 2.1 or later (the "LGPL")
+ *    http://www.gnu.org/licenses/lgpl.html
+ *
+ *  - Mozilla Public License Version 1.1 or later (the "MPL")
+ *    http://www.mozilla.org/MPL/MPL-1.1.html
+ *
+ * == END LICENSE ==
+ */
+
+/**
+ * @fileOverview Defines the "virtual" dialog, dialog content and dialog button
+ * definition classes.
+ */
+
+/**
+ * This class is not really part of the API. It just illustrates the properties
+ * that developers can use to define and create dialogs.
+ * @name CKEDITOR.dialog.dialogDefinition
+ * @constructor
+ * @example
+ * // There is no constructor for this class, the user just has to define an
+ * // object with the appropriate properties.
+ *
+ * CKEDITOR.dialog.add( 'testOnly', function( editor )
+ *       {
+ *           return {
+ *               title : 'Test Dialog',
+ *               resizable : CKEDITOR.DIALOG_RESIZE_BOTH,
+ *               minWidth : 500,
+ *               minHeight : 400,
+ *               contents : [
+ *                   {
+ *                       id : 'tab1',
+ *                       label : 'First Tab',
+ *                       title : 'First Tab Title',
+ *                       accessKey : 'Q',
+ *                       elements : [
+ *                           {
+ *                               type : 'text',
+ *                               label : 'Test Text 1',
+ *                               id : 'testText1',
+ *                               'default' : 'hello world!'
+ *                           }
+ *                       ]
+ *                    }
+ *               ]
+ *           };
+ *       });
+ */
+
+/**
+ * The dialog title, displayed in the dialog's header. Required.
+ * @name CKEDITOR.dialog.dialogDefinition.prototype.title
+ * @field
+ * @type String
+ * @example
+ */
+
+/**
+ * How the dialog can be resized, must be one of the four contents defined below.
+ * <br /><br />
+ * <strong>CKEDITOR.DIALOG_RESIZE_NONE</strong><br />
+ * <strong>CKEDITOR.DIALOG_RESIZE_WIDTH</strong><br />
+ * <strong>CKEDITOR.DIALOG_RESIZE_HEIGHT</strong><br />
+ * <strong>CKEDITOR.DIALOG_RESIZE_BOTH</strong><br />
+ * @name CKEDITOR.dialog.dialogDefinition.prototype.resizable
+ * @field
+ * @type Number
+ * @default CKEDITOR.DIALOG_RESIZE_NONE
+ * @example
+ */
+
+/**
+ * The minimum width of the dialog, in pixels.
+ * @name CKEDITOR.dialog.dialogDefinition.prototype.minWidth
+ * @field
+ * @type Number
+ * @default 600
+ * @example
+ */
+
+/**
+ * The minimum height of the dialog, in pixels.
+ * @name CKEDITOR.dialog.dialogDefinition.prototype.minHeight
+ * @field
+ * @type Number
+ * @default 400
+ * @example
+ */
+
+/**
+ * The buttons in the dialog, defined as an array of
+ * {@link CKEDITOR.dialog.buttonDefinition} objects.
+ * @name CKEDITOR.dialog.dialogDefinition.prototype.buttons
+ * @field
+ * @type Array
+ * @default [ CKEDITOR.dialog.okButton, CKEDITOR.dialog.cancelButton ]
+ * @example
+ */
+
+/**
+ * The contents in the dialog, defined as an array of
+ * {@link CKEDITOR.dialog.contentDefinition} objects. Required.
+ * @name CKEDITOR.dialog.dialogDefinition.prototype.contents
+ * @field
+ * @type Array
+ * @example
+ */
+
+/**
+ * The function to execute when OK is pressed.
+ * @name CKEDITOR.dialog.dialogDefinition.prototype.onOk
+ * @field
+ * @type Function
+ * @example
+ */
+
+/**
+ * The function to execute when Cancel is pressed.
+ * @name CKEDITOR.dialog.dialogDefinition.prototype.onCancel
+ * @field
+ * @type Function
+ * @example
+ */
+
+/**
+ * The function to execute when the dialog is displayed for the first time.
+ * @name CKEDITOR.dialog.dialogDefinition.prototype.onLoad
+ * @field
+ * @type Function
+ * @example
+ */
+
+/**
+ * This class is not really part of the API. It just illustrates the properties
+ * that developers can use to define and create dialog content pages.
+ * @name CKEDITOR.dialog.contentDefinition
+ * @constructor
+ * @example
+ * // There is no constructor for this class, the user just has to define an
+ * // object with the appropriate properties.
+ */
+
+/**
+ * The id of the content page.
+ * @name CKEDITOR.dialog.contentDefinition.prototype.id
+ * @field
+ * @type String
+ * @example
+ */
+
+/**
+ * The tab label of the content page.
+ * @name CKEDITOR.dialog.contentDefinition.prototype.label
+ * @field
+ * @type String
+ * @example
+ */
+
+/**
+ * The popup message of the tab label.
+ * @name CKEDITOR.dialog.contentDefinition.prototype.title
+ * @field
+ * @type String
+ * @example
+ */
+
+/**
+ * The CTRL hotkey for switching to the tab.
+ * @name CKEDITOR.dialog.contentDefinition.prototype.accessKey
+ * @field
+ * @type String
+ * @example
+ * contentDefinition.accessKey = 'Q';	// Switch to this page when CTRL-Q is pressed.
+ */
+
+/**
+ * The UI elements contained in this content page, defined as an array of
+ * {@link CKEDITOR.dialog.uiElementDefinition} objects.
+ * @name CKEDITOR.dialog.contentDefinition.prototype.elements
+ * @field
+ * @type Array
+ * @example
+ */
+
+/**
+ * This class is not really part of the API. It just illustrates the properties
+ * that developers can use to define and create dialog buttons.
+ * @name CKEDITOR.dialog.buttonDefinition
+ * @constructor
+ * @example
+ * // There is no constructor for this class, the user just has to define an
+ * // object with the appropriate properties.
+ */
+
+/**
+ * The id of the dialog button. Required.
+ * @name CKEDITOR.dialog.buttonDefinition.prototype.id
+ * @type String
+ * @field
+ * @example
+ */
+
+/**
+ * The label of the dialog button. Required.
+ * @name CKEDITOR.dialog.buttonDefinition.prototype.label
+ * @type String
+ * @field
+ * @example
+ */
+
+/**
+ * The popup message of the dialog button.
+ * @name CKEDITOR.dialog.buttonDefinition.prototype.title
+ * @type String
+ * @field
+ * @example
+ */
+
+/**
+ * The CTRL hotkey for the button.
+ * @name CKEDITOR.dialog.buttonDefinition.prototype.accessKey
+ * @type String
+ * @field
+ * @example
+ * exitButton.accessKey = 'X';		// Button will be pressed when user presses CTRL-X
+ */
+
+/**
+ * Whether the button is disabled.
+ * @name CKEDITOR.dialog.buttonDefinition.prototype.disabled
+ * @type Boolean
+ * @field
+ * @default false
+ * @example
+ */
+
+/**
+ * The function to execute when the button is clicked.
+ * @name CKEDITOR.dialog.buttonDefinition.prototype.onClick
+ * @type Function
+ * @field
+ * @example
+ */
+
+/**
+ * This class is not really part of the API. It just illustrates the properties
+ * that developers can use to define and create dialog UI elements.
+ * @name CKEDITOR.dialog.uiElementDefinition
+ * @constructor
+ * @see CKEDITOR.ui.dialog.uiElement
+ * @example
+ * // There is no constructor for this class, the user just has to define an
+ * // object with the appropriate properties.
+ */
+
+/**
+ * The id of the UI element.
+ * @name CKEDITOR.dialog.uiElementDefinition.prototype.id
+ * @field
+ * @type String
+ * @example
+ */
+
+/**
+ * The type of the UI element. Required.
+ * @name CKEDITOR.dialog.uiElementDefinition.prototype.type
+ * @field
+ * @type String
+ * @example
+ */
+
+/**
+ * The popup label of the UI element.
+ * @name CKEDITOR.dialog.uiElementDefinition.prototype.label
+ * @field
+ * @type String
+ * @example
+ */
+
+/**
+ * CSS class names to append to the UI element.
+ * @name CKEDITOR.dialog.uiElementDefinition.prototype.className
+ * @field
+ * @type String
+ * @example
+ */
+
+/**
+ * Inline CSS classes to append to the UI element.
+ * @name CKEDITOR.dialog.uiElementDefinition.prorotype.style
+ * @field
+ * @type String
+ * @example
+ */
+
+/**
+ * Function to execute the first time the UI element is displayed.
+ * @name CKEDITOR.dialog.uiElementDefinition.prototype.onLoad
+ * @field
+ * @type Function
+ * @example
+ */
Index: /CKEditor/branches/prototype/_source/plugins/dialog/plugin.js
===================================================================
--- /CKEditor/branches/prototype/_source/plugins/dialog/plugin.js	(revision 2595)
+++ /CKEditor/branches/prototype/_source/plugins/dialog/plugin.js	(revision 2596)
@@ -439,4 +439,5 @@
 	 * Adds a tabbed page into the dialog.
 	 * @param {Object} contents Content definition.
+	 * @example
 	 */
 	addPage : function( contents )
@@ -554,4 +555,5 @@
 	 * @param {String} pageId id of dialog page.
 	 * @param {String} elementId id of UI element.
+	 * @example
 	 * @returns {CKEDITOR.ui.dialog.uiElement} The dialog UI element.
 	 */
@@ -565,4 +567,5 @@
 	 * @param {String} pageId id of dialog page.
 	 * @param {String} elementId id of UI element.
+	 * @example
 	 * @returns {Object} The value of the UI element.
 	 */
@@ -577,4 +580,5 @@
 	 * @param {String} elementId id of the UI element.
 	 * @param {Object} value The new value of the UI element.
+	 * @example
 	 */
 	setValueOf : function( pageId, elementId, value )
@@ -586,4 +590,5 @@
 	 * Gets the UI element of a button in the dialog's button row.
 	 * @param {String} id The id of the button.
+	 * @example
 	 * @returns {CKEDITOR.ui.dialog.button} The button object.
 	 */
@@ -596,4 +601,5 @@
 	 * Simulates a click to a dialog button in the dialog's button row.
 	 * @param {String} id The id of the button.
+	 * @example
 	 * @returns The return value of the dialog's "click" event.
 	 */
@@ -606,4 +612,5 @@
 	 * Disables a dialog button.
 	 * @param {String} id The id of the button.
+	 * @example
 	 */
 	disableButton : function( id )
@@ -615,4 +622,5 @@
 	 * Enables a dialog button.
 	 * @param {String} id The id of the button.
+	 * @example
 	 */
 	enableButton : function( id )
@@ -630,5 +638,10 @@
 		 * Registers a dialog.
 		 * @param {String} name The dialog's name.
-		 * @param {String} dialogDefinition The dialog's definition.
+		 * @param {Function|String} dialogDefinition
+		 * A function returning the dialog's definition, or the URL to the .js file holding the function.
+		 * The function should accept an argument "editor" which is the current editor instance, and
+		 * return an object conforming to {@link CKEDITOR.dialog.dialogDefinition}.
+		 * @example
+		 * @see CKEDITOR.dialog.dialogDefinition
 		 */
 		add : function( name, dialogDefinition )
@@ -641,4 +654,5 @@
 		 * @static
 		 * @field
+		 * @example
 		 * @type CKEDITOR.ui.dialog.button
 		 */
@@ -661,4 +675,5 @@
 		 * @static
 		 * @field
+		 * @example
 		 * @type CKEDITOR.ui.dialog.button
 		 */
@@ -681,4 +696,5 @@
 		 * @param {String} typeName The name of the UI element.
 		 * @param {Function} builder The function to build the UI element.
+		 * @example
 		 */
 		addUIElement : function( typeName, builder )
@@ -695,4 +711,5 @@
 		 * @param {Number} bottom The bottom margin in pixels.
 		 * @param {Number} left The left margin in pixels.
+		 * @example
 		 */
 		setMargins : function( top, right, bottom, left )
@@ -1019,4 +1036,18 @@
 	margins : [0, 0, 0, 0],
 
+	/**
+	 * This class is not really part of the API. It is the "definition" property value
+	 * passed to "dialogDefinition" event handlers.
+	 * @constructor
+	 * @name CKEDITOR.dialog.dialogDefinitionObject
+	 * @extends CKEDITOR.dialog.dialogDefinition
+	 * @example
+	 * CKEDITOR.on( 'dialogDefinition', function( evt )
+	 * 	{
+	 * 		var definition = evt.data.definition;
+	 * 		var content = definition.getContents( 'page1' );
+	 * 		...
+	 * 	} );
+	 */
 	definitionObject : function( dialog, dialogDefinition )
 	{
@@ -1031,4 +1062,18 @@
 	},
 
+	/**
+	 * This class is not really part of the API. It is the template of the objects
+	 * representing content pages inside the CKEDITOR.dialog.dialogDefinitionObject.
+	 * @constructor
+	 * @name CKEDITOR.dialog.contentDefinitionObject
+	 * @example
+	 * CKEDITOR.on( 'dialogDefinition', function( evt )
+	 * 	{
+	 * 		var definition = evt.data.definition;
+	 * 		var content = definition.getContents( 'page1' );
+	 *		content.remove( 'textInput1' );
+	 * 		...
+	 * 	} );
+	 */
 	contentObject : function( dialog, id, contentDefinition )
 	{
@@ -1045,5 +1090,12 @@
 
 CKEDITOR.dialog._.definitionObject.prototype = 
+/** @lends CKEDITOR.dialog.dialogDefinitionObject.prototype */
 {
+	/**
+	 * Gets a content definition in the dialog definition.
+	 * @param {String} id The id of the content definition.
+	 * @returns {CKEDITOR.dialog.contentDefinition} The content definition with id.
+	 * @example
+	 */
 	getContents : function( id )
 	{
@@ -1056,4 +1108,10 @@
 	},
 
+	/**
+	 * Gets a button definition in the dialog definition.
+	 * @param {String} id The id of the button definition.
+	 * @returns {CKEDITOR.dialog.buttonDefinition} The button definition with id.
+	 * @example
+	 */
 	getButton : function( id )
 	{
@@ -1066,4 +1124,12 @@
 	},
 
+	/**
+	 * Adds a content definition object under the dialog definition.
+	 * @param {CKEDITOR.dialog.contentDefinition} The content definition.
+	 * @param {String} nextSiblingId The id of an existing content definition which the new content definition
+	 * will be inserted before. Omit if the new content definition is to be inserted as the last item.
+	 * @returns {CKEDITOR.dialog.contentDefinition} The inserted content definition.
+	 * @example
+	 */
 	addContents : function( contentDefinition, nextSiblingId )
 	{
@@ -1080,4 +1146,12 @@
 	},
 
+	/**
+	 * Adds a button definition object under the dialog definition.
+	 * @param {CKEDITOR.dialog.buttonDefinition} The button definition.
+	 * @param {String} nextSiblingId The id of an existing button definition which the new button definition
+	 * will be inserted before. Omit if the new button definition is to be inserted as the last item.
+	 * @returns {CKEDITOR.dialog.buttonDefinition} The inserted button definition.
+	 * @example
+	 */
 	addButton : function( buttonDefinition, nextSiblingId )
 	{
@@ -1094,4 +1168,10 @@
 	},
 
+	/**
+	 * Removes a content definition from the dialog definition.
+	 * @param {String} id The id of the content definition to be removed.
+	 * @returns {CKEDITOR.dialog.contentDefinition} The removed content definition.
+	 * @example
+	 */
 	removeContents : function( id )
 	{
@@ -1104,4 +1184,10 @@
 	},
 
+	/**
+	 * Removes a button definition from the dialog definition.
+	 * @param {String} id The id of the button definition to be removed.
+	 * @returns {CKEDITOR.dialog.buttonDefinition} The removed button definition.
+	 * @example
+	 */
 	removeButton : function( id )
 	{
@@ -1116,5 +1202,12 @@
 
 CKEDITOR.dialog._.contentObject.prototype = 
+/** @lends CKEDITOR.dialog.contentDefinitionObject.prototype */
 {
+	/**
+	 * Gets a UI element definition under the content definition.
+	 * @param {String} id The id of the UI element definition.
+	 * @returns {CKEDITOR.dialog.uiElementDefinition} 
+	 * @example
+	 */
 	get : function( id )
 	{
@@ -1127,4 +1220,14 @@
 	},
 
+	/**
+	 * Adds a UI element definition to the content definition.
+	 * @param {CKEDITOR.dialog.uiElementDefinition} elementDefinition The UI elemnet definition
+	 * to be added.
+	 * @param {String} nextSiblingId The id of an existing UI element definition which the new 
+	 * UI element definition will be inserted before. Omit if the new button definition is to 
+	 * be inserted as the last item.
+	 * @returns {CKEDITOR.dialog.uiElementDefinition} The element definition inserted.
+	 * @example
+	 */
 	add : function( elementDefinition, nextSiblingId )
 	{
@@ -1141,4 +1244,10 @@
 	},
 
+	/**
+	 * Removes a UI element definition from the content definition.
+	 * @param {String} id The id of the UI element definition to be removed.
+	 * @returns {CKEDITOR.dialog.uiElementDefinition} The element definition removed.
+	 * @example
+	 */
 	remove : function( id )
 	{
@@ -1157,4 +1266,5 @@
 	 * The base class of all dialog UI elements.
 	 * @constructor
+	 * @example
 	 */
 	uiElement : function( dialog, elementDefinition, htmlList, nodeNameArg, stylesArg, attributesArg, contentsArg )
@@ -1228,4 +1338,5 @@
 	 * @constructor
 	 * @extends CKEDITOR.ui.dialog.uiElement
+	 * @example
 	 */
 	hbox : function( dialog, childObjList, childHtmlList, htmlList, elementDefinition )
@@ -1275,5 +1386,6 @@
 	 * Vertical layout box for dialog UI elements.
 	 * @constructor
-	 * @extends CKEDITOR.ui.dialog.uiElement
+	 * @extends CKEDITOR.ui.dialog.hbox
+	 * @example
 	 */
 	vbox : function( dialog, childObjList, childHtmlList, htmlList, elementDefinition )
@@ -1380,4 +1492,14 @@
 	 */
 	{
+		/**
+		 * Gets a child UI element inside this container.
+		 * @param {Array|Number} indices An array or a single number to indicate the child's 
+		 * position in the container's descendant tree. Omit to get all the children in an array.
+		 * @returns {Array|CKEDITOR.ui.dialog.uiElement} Array of all UI elements in the container
+		 * if no argument given, or the specified UI element if indices is given.
+		 * @example
+		 * var checkbox = hbox.getChild( [0,1] );
+		 * checkbox.setValue( true );
+		 */
 		getChild : function( indices )
 		{
@@ -1400,6 +1522,5 @@
 	}, true );
 
-/** @borrows CKEDITOR.ui.hbox.prototype as CKEDITOR.ui.vbox.prototype */
-CKEDITOR.ui.dialog.vbox.prototype = CKEDITOR.ui.dialog.hbox.prototype;
+CKEDITOR.ui.dialog.vbox.prototype = new CKEDITOR.ui.dialog.hbox();
 
 CKEDITOR.tools.extend( CKEDITOR.editor.prototype,
Index: /CKEditor/branches/prototype/_source/plugins/dialogui/plugin.js
===================================================================
--- /CKEditor/branches/prototype/_source/plugins/dialogui/plugin.js	(revision 2595)
+++ /CKEditor/branches/prototype/_source/plugins/dialogui/plugin.js	(revision 2596)
@@ -71,4 +71,5 @@
 			 * Base class for all dialog elements with a textual label on the left.
 			 * @constructor
+			 * @example
 			 * @extends CKEDITOR.ui.dialog.uiElement
 			 */
@@ -98,4 +99,5 @@
 			 * A text input with a label.
 			 * @constructor
+			 * @example
 			 * @extends CKEDITOR.ui.dialog.labeledElement
 			 */
@@ -208,4 +210,5 @@
 			 * A group of radio buttons.
 			 * @constructor
+			 * @example
 			 * @extends CKEDITOR.ui.dialog.labeledElement
 			 */
@@ -267,4 +270,5 @@
 			 * A button with a label inside.
 			 * @constructor
+			 * @example
 			 * @extends CKEDITOR.ui.dialog.uiElement
 			 */
@@ -274,5 +278,5 @@
 					return;
 
-				initPrivateObject.call( this, elementDefinition, { disabled : false } );
+				initPrivateObject.call( this, elementDefinition, { disabled : elementDefinition.disabled || false } );
 
 				/** @ignore */
@@ -345,4 +349,5 @@
 			 * A dialog element made from raw HTML code.
 			 * @extends CKEDITOR.ui.dialog.uiElement
+			 * @example
 			 * @constructor
 			 */
@@ -364,4 +369,5 @@
 				/**
 				 * Simulates a click to the button.
+				 * @example
 				 * @returns {Object} Return value of the 'click' event.
 				 */
@@ -374,4 +380,5 @@
 				/**
 				 * Enables the button.
+				 * @example
 				 */
 				enable : function()
@@ -383,4 +390,5 @@
 				/**
 				 * Disables the button.
+				 * @example
 				 */
 				disable : function()
@@ -396,4 +404,5 @@
 				/**
 				 * Gets the text input DOM element under this UI object.
+				 * @example
 				 * @returns {CKEDITOR.dom.element} The DOM element of the text input.
 				 */
@@ -405,4 +414,5 @@
 				/**
 				 * Selects all the text in the text input.
+				 * @example
 				 */
 				select : function()
@@ -418,4 +428,5 @@
 				/**
 				 * Gets the checkbox DOM element.
+				 * @example
 				 * @returns {CKEDITOR.dom.element} The DOM element of the checkbox.
 				 */
@@ -427,4 +438,5 @@
 				/**
 				 * Sets the state of the checkbox.
+				 * @example
 				 * @param {Boolean} true to tick the checkbox, false to untick it.
 				 */
@@ -436,4 +448,5 @@
 				/**
 				 * Gets the state of the checkbox.
+				 * @example
 				 * @returns {Boolean} true means the checkbox is ticked, false means it's not ticked.
 				 */
@@ -449,4 +462,5 @@
 				/**
 				 * Checks one of the radio buttons in this button group.
+				 * @example
 				 * @param {String} value The value of the button to be chcked.
 				 */
@@ -463,4 +477,5 @@
 				/**
 				 * Gets the value of the currently checked radio button.
+				 * @example
 				 * @returns {String} The currently checked button's value.
 				 */