Index: /CKEditor/branches/prototype/_source/plugins/dialog/plugin.js =================================================================== --- /CKEditor/branches/prototype/_source/plugins/dialog/plugin.js (revision 2594) +++ /CKEditor/branches/prototype/_source/plugins/dialog/plugin.js (revision 2595) @@ -20,4 +20,8 @@ */ +/** + * @fileOverview The floating dialog plugin. + */ + CKEDITOR.plugins.add( 'dialog', { @@ -25,9 +29,37 @@ }); +/** + * No resize for this dialog. + * @constant + */ CKEDITOR.DIALOG_RESIZE_NONE = 0; + +/** + * Only allow horizontal resizing for this dialog, disable vertical resizing. + * @constant + */ CKEDITOR.DIALOG_RESIZE_WIDTH = 1; + +/** + * Only allow vertical resizing for this dialog, disable horizontal resizing. + * @constant + */ CKEDITOR.DIALOG_RESIZE_HEIGHT = 2; + +/* + * Allow the dialog to be resized in both directions. + * @constant + */ CKEDITOR.DIALOG_RESIZE_BOTH = 3; + +/** + * This is the base class for runtime dialog objects. + * @param {Object} editor The editor which created the dialog. + * @param {String} dialogName The dialog's registered name. + * @constructor + * @example + * var dialogObj = new CKEDITOR.dialog( editor, 'smiley' ); + */ CKEDITOR.dialog = function( editor, dialogName ) { @@ -120,4 +152,5 @@ }, this, null, 0); + /** @ignore */ var iterContents = function( func ) { @@ -211,4 +244,12 @@ CKEDITOR.dialog.prototype = { + /** + * Resizes the dialog. + * @param {Number} width The width of the dialog in pixels. + * @param {Number} height The height of the dialog in pixels. + * @function + * @example + * dialogObj.resize( 800, 640 ); + */ resize : (function() { @@ -248,4 +289,10 @@ })(), + /** + * Gets the current size of the dialog in pixels. + * @returns {Object} An object with "width" and "height" properties. + * @example + * var width = dialogObj.getSize().width; + */ getSize : function() { @@ -253,4 +300,12 @@ }, + /** + * Moves the dialog to an (x, y) coordinate relative to the window. + * @function + * @param {Number} x The target x-coordinate. + * @param {Number} y The target y-coordinate. + * @example + * dialogObj.move( 10, 40 ); + */ move : (function() { @@ -285,6 +340,17 @@ })(), + /** + * Gets the dialog's position in the window. + * @returns {Object} An object with "x" and "y" properties. + * @example + * var dialogX = dialogObj.getPosition().x; + */ getPosition : function(){ return CKEDITOR.tools.extend( {}, this._.position ); }, + /** + * Shows the dialog box. + * @example + * dialogObj.show(); + */ show : function() { @@ -340,4 +406,9 @@ }, + /** + * Hides the dialog box. + * @example + * dialogObj.hide(); + */ hide : function() { @@ -365,4 +436,8 @@ }, + /** + * Adds a tabbed page into the dialog. + * @param {Object} contents Content definition. + */ addPage : function( contents ) { @@ -411,4 +486,10 @@ }, + /** + * Activates a tab page in the dialog by its id. + * @param {String} id The id of the dialog tab to be activated. + * @example + * dialogObj.selectPage( 'tab_1' ); + */ selectPage : function( id ) { @@ -457,4 +538,11 @@ }, + /** + * Gets the root DOM element of the dialog. + * @returns {CKEDITOR.dom.element} The <span> element containing this dialog. + * @example + * var dialogElement = dialogObj.getElement().getFirst(); + * dialogElement.setStyle( 'padding', '5px' ); + */ getElement : function() { @@ -462,4 +550,10 @@ }, + /** + * Gets a dialog UI element object from a dialog page. + * @param {String} pageId id of dialog page. + * @param {String} elementId id of UI element. + * @returns {CKEDITOR.ui.dialog.uiElement} The dialog UI element. + */ getContentElement : function( pageId, elementId ) { @@ -467,4 +561,10 @@ }, + /** + * Gets the value of a dialog UI element. + * @param {String} pageId id of dialog page. + * @param {String} elementId id of UI element. + * @returns {Object} The value of the UI element. + */ getValueOf : function( pageId, elementId ) { @@ -472,4 +572,10 @@ }, + /** + * Sets the value of a dialog UI element. + * @param {String} pageId id of the dialog page. + * @param {String} elementId id of the UI element. + * @param {Object} value The new value of the UI element. + */ setValueOf : function( pageId, elementId, value ) { @@ -477,4 +583,9 @@ }, + /** + * Gets the UI element of a button in the dialog's button row. + * @param {String} id The id of the button. + * @returns {CKEDITOR.ui.dialog.button} The button object. + */ getButton : function( id ) { @@ -482,4 +593,9 @@ }, + /** + * Simulates a click to a dialog button in the dialog's button row. + * @param {String} id The id of the button. + * @returns The return value of the dialog's "click" event. + */ click : function( id ) { @@ -487,4 +603,8 @@ }, + /** + * Disables a dialog button. + * @param {String} id The id of the button. + */ disableButton : function( id ) { @@ -492,4 +612,8 @@ }, + /** + * Enables a dialog button. + * @param {String} id The id of the button. + */ enableButton : function( id ) { @@ -499,5 +623,13 @@ CKEDITOR.tools.extend( CKEDITOR.dialog, - { + /** + * @lends CKEDITOR.dialog + */ + { + /** + * Registers a dialog. + * @param {String} name The dialog's name. + * @param {String} dialogDefinition The dialog's definition. + */ add : function( name, dialogDefinition ) { @@ -505,4 +637,10 @@ }, + /** + * The default OK button for dialogs. Fires the "ok" event and closes the dialog if the event succeeds. + * @static + * @field + * @type CKEDITOR.ui.dialog.button + */ okButton : { @@ -519,4 +657,10 @@ }, + /** + * The default cancel button for dialogs. Fires the "cancel" event and closes the dialog if no UI element value changed. + * @static + * @field + * @type CKEDITOR.ui.dialog.button + */ cancelButton : { @@ -533,4 +677,9 @@ }, + /** + * Registers a dialog UI element. + * @param {String} typeName The name of the UI element. + * @param {Function} builder The function to build the UI element. + */ addUIElement : function( typeName, builder ) { @@ -538,4 +687,13 @@ }, + /** + * Sets the width of margins of dialogs, which is used for the dialog moving and resizing logic. + * The margin here means the area between the dialog's container
and the visual boundary of the dialog. + * Typically this area is used for dialog shadows. + * @param {Number} top The top margin in pixels. + * @param {Number} right The right margin in pixels. + * @param {Number} bottom The bottom margin in pixels. + * @param {Number} left The left margin in pixels. + */ setMargins : function( top, right, bottom, left ) { @@ -996,4 +1154,8 @@ CKEDITOR.ui.dialog = { + /** + * The base class of all dialog UI elements. + * @constructor + */ uiElement : function( dialog, elementDefinition, htmlList, nodeNameArg, stylesArg, attributesArg, contentsArg ) { @@ -1062,4 +1224,9 @@ }, + /** + * Horizontal layout box for dialog UI elements, auto-expends to available width of container. + * @constructor + * @extends CKEDITOR.ui.dialog.uiElement + */ hbox : function( dialog, childObjList, childHtmlList, htmlList, elementDefinition ) { @@ -1073,4 +1240,5 @@ height = elementDefinition && elementDefinition.height || null, i; + /** @ignore */ var innerHTML = function() { @@ -1104,4 +1272,9 @@ }, + /** + * Vertical layout box for dialog UI elements. + * @constructor + * @extends CKEDITOR.ui.dialog.uiElement + */ vbox : function( dialog, childObjList, childHtmlList, htmlList, elementDefinition ) { @@ -1114,4 +1287,5 @@ width = elementDefinition && elementDefinition.width || null, heights = elementDefinition && elementDefinition.heights || null; + /** @ignore */ var innerHTML = function() { @@ -1137,4 +1311,10 @@ CKEDITOR.ui.dialog.uiElement.prototype = { + /** + * Gets the root DOM element of this dialog UI object. + * @returns {CKEDITOR.dom.element} Root DOM element of UI object. + * @example + * uiElement.getElement().hide(); + */ getElement: function() { @@ -1142,4 +1322,10 @@ }, + /** + * Sets the value of this dialog UI object. + * @param {Object} value The new value. + * @example + * uiElement.setValue( 'Dingo' ); + */ setValue : function( value ) { @@ -1147,4 +1333,10 @@ }, + /** + * Gets the current value of this dialog UI object. + * @returns {Object} The current value. + * @example + * var myValue = uiElement.getValue(); + */ getValue : function() { @@ -1152,4 +1344,11 @@ }, + /** + * Tells whether the UI object's value has changed. + * @returns {Boolean} true if changed, false if not changed. + * @example + * if ( uiElement.isChanged() ) + *   confirm( 'Value changed! Continue?' ); + */ isChanged : function() { @@ -1158,4 +1357,9 @@ }, + /** + * Puts the focus to the UI object. Switches tabs if the UI object isn't in the active tab page. + * @example + * uiElement.focus(); + */ focus : function() { @@ -1172,4 +1376,7 @@ CKEDITOR.ui.dialog.hbox.prototype = CKEDITOR.tools.extend( new CKEDITOR.ui.dialog.uiElement, + /** + * @lends CKEDITOR.ui.dialog.hbox.prototype + */ { getChild : function( indices ) @@ -1193,8 +1400,18 @@ }, true ); +/** @borrows CKEDITOR.ui.hbox.prototype as CKEDITOR.ui.vbox.prototype */ CKEDITOR.ui.dialog.vbox.prototype = CKEDITOR.ui.dialog.hbox.prototype; CKEDITOR.tools.extend( CKEDITOR.editor.prototype, - { + /** @lends CKEDITOR.editor.prototype */ + { + /** + * Loads and opens a registered dialog. + * @param {String} dialogName The registered name of the dialog. + * @see CKEDITOR.dialog.add + * @example + * CKEDITOR.instances.editor1.openDialog( 'smiley' ); + * @returns {CKEDITOR.dialog} The dialog object corresponding to the dialog displayed. null if the dialog name is not registered. + */ openDialog : function( dialogName ) { Index: /CKEditor/branches/prototype/_source/plugins/dialogui/plugin.js =================================================================== --- /CKEditor/branches/prototype/_source/plugins/dialogui/plugin.js (revision 2594) +++ /CKEditor/branches/prototype/_source/plugins/dialogui/plugin.js (revision 2595) @@ -19,4 +19,7 @@ * == END LICENSE == */ + +/** @fileoverview The "dialogui" plugin. */ + CKEDITOR.plugins.add( 'dialogui' ); @@ -63,5 +66,11 @@ CKEDITOR.tools.extend( CKEDITOR.ui.dialog, + /** @lends CKEDITOR.ui.dialog */ { + /** + * Base class for all dialog elements with a textual label on the left. + * @constructor + * @extends CKEDITOR.ui.dialog.uiElement + */ labeledElement : function( dialog, elementDefinition, htmlList, contentHtml ) { @@ -71,4 +80,5 @@ initPrivateObject.call( this, elementDefinition ); var children = this._.children = []; + /** @ignore */ var innerHTML = function() { @@ -85,4 +95,9 @@ }, + /** + * A text input with a label. + * @constructor + * @extends CKEDITOR.ui.dialog.labeledElement + */ textInput : function( dialog, elementDefinition, htmlList, stylesArg, attributesArg, contentsArg ) { @@ -142,4 +157,5 @@ this.validate = elementDefinition.validate; + /** @ignore */ var innerHTML = function() { @@ -153,4 +169,9 @@ }, + /** + * A single checkbox with a label on the right. + * @constructor + * @extends CKEDITOR.ui.dialog.uiElement + */ checkbox : function( dialog, elementDefinition, htmlList ) { @@ -163,4 +184,5 @@ this.validate = elementDefinition.validate(); + /** @ignore */ var innerHTML = function() { @@ -183,4 +205,9 @@ }, + /** + * A group of radio buttons. + * @constructor + * @extends CKEDITOR.ui.dialog.labeledElement + */ radio : function( dialog, elementDefinition, htmlList ) { @@ -195,4 +222,5 @@ var children = []; + /** @ignore */ var innerHTML = function() { @@ -236,4 +264,9 @@ }, + /** + * A button with a label inside. + * @constructor + * @extends CKEDITOR.ui.dialog.uiElement + */ button : function( dialog, elementDefinition, htmlList ) { @@ -243,4 +276,5 @@ initPrivateObject.call( this, elementDefinition, { disabled : false } ); + /** @ignore */ var innerHTML = function() { @@ -308,4 +342,9 @@ }, + /** + * A dialog element made from raw HTML code. + * @extends CKEDITOR.ui.dialog.uiElement + * @constructor + */ html : function( dialog, elementDefinition, htmlList ) { @@ -315,5 +354,5 @@ CKEDITOR.ui.dialog.uiElement.call( this, dialog, elementDefinition, htmlList, 'span', null, null, elementDefinition.html ); } - }, true); + }, true ); CKEDITOR.ui.dialog.labeledElement.prototype @@ -321,11 +360,19 @@ CKEDITOR.ui.dialog.button.prototype = CKEDITOR.tools.extend( new CKEDITOR.ui.dialog.uiElement, - { + /** @lends CKEDITOR.ui.dialog.button.prototype */ + { + /** + * Simulates a click to the button. + * @returns {Object} Return value of the 'click' event. + */ click : function() { if ( !this._.disabled ) - this.fire( 'click', { dialog : this._.dialog } ); - }, - + return this.fire( 'click', { dialog : this._.dialog } ); + }, + + /** + * Enables the button. + */ enable : function() { @@ -334,4 +381,7 @@ }, + /** + * Disables the button. + */ disable : function() { @@ -342,5 +392,10 @@ CKEDITOR.ui.dialog.textInput.prototype = CKEDITOR.tools.extend( new CKEDITOR.ui.dialog.labeledElement, - { + /** @lends CKEDITOR.ui.dialog.textInput.prototype */ + { + /** + * Gets the text input DOM element under this UI object. + * @returns {CKEDITOR.dom.element} The DOM element of the text input. + */ getElement : function() { @@ -348,4 +403,7 @@ }, + /** + * Selects all the text in the text input. + */ select : function() { @@ -356,5 +414,10 @@ CKEDITOR.ui.dialog.checkbox.prototype = CKEDITOR.tools.extend( new CKEDITOR.ui.dialog.uiElement, - { + /** @lends CKEDITOR.ui.dialog.checkbox.prototype */ + { + /** + * Gets the checkbox DOM element. + * @returns {CKEDITOR.dom.element} The DOM element of the checkbox. + */ getElement : function() { @@ -362,4 +425,8 @@ }, + /** + * Sets the state of the checkbox. + * @param {Boolean} true to tick the checkbox, false to untick it. + */ setValue : function( checked ) { @@ -367,4 +434,8 @@ }, + /** + * Gets the state of the checkbox. + * @returns {Boolean} true means the checkbox is ticked, false means it's not ticked. + */ getValue : function() { @@ -374,5 +445,10 @@ CKEDITOR.ui.dialog.radio.prototype = CKEDITOR.tools.extend( new CKEDITOR.ui.dialog.uiElement, - { + /** @lends CKEDITOR.ui.dialog.radio.prototype */ + { + /** + * Checks one of the radio buttons in this button group. + * @param {String} value The value of the button to be chcked. + */ setValue : function( value ) { @@ -385,4 +461,8 @@ }, + /** + * Gets the value of the currently checked radio button. + * @returns {String} The currently checked button's value. + */ getValue : function() {