Index: /CKEditor/trunk/_source/plugins/devtools/plugin.js =================================================================== --- /CKEditor/trunk/_source/plugins/devtools/plugin.js (revision 7084) +++ /CKEditor/trunk/_source/plugins/devtools/plugin.js (revision 7085) @@ -128,6 +128,6 @@ /** - * A function that returns the text to be displayed inside the developer tooltip when hovering over a dialog UI element. - * There are 4 parameters that are being passed into the function: editor, dialog, element, tab name. + * A function that returns the text to be displayed inside the Developer Tools tooltip when hovering over a dialog UI element. + * There are 4 parameters that are being passed into the function: editor, dialog window, element, tab name. * @name editor.config.devtools_textCallback * @since 3.6 @@ -136,5 +136,5 @@ * @example * // This is actually the default value. - * // Show dialog name, tab id and element id. + * // Show dialog window name, tab ID, and element ID. * config.devtools_textCallback = function( editor, dialog, element, tabName ) * { @@ -159,5 +159,5 @@ /** - * A setting that holds CSS rules to be injected do page and contain styles to be applied to the tooltip element. + * A setting that stores CSS rules to be injected into the page with styles to be applied to the tooltip element. * @name CKEDITOR.config.devtools_styles * @since 3.6 Index: /CKEditor/trunk/_source/plugins/resize/plugin.js =================================================================== --- /CKEditor/trunk/_source/plugins/resize/plugin.js (revision 7084) +++ /CKEditor/trunk/_source/plugins/resize/plugin.js (revision 7085) @@ -111,6 +111,6 @@ /** - * The minimum editor width, in pixels, when resizing it with the resize handle. - * Note: It fallbacks to editor's actual width if that's smaller than the default value. + * The minimum editor width, in pixels, when resizing the editor interface by using the resize handle. + * Note: It falls back to editor's actual width if it is smaller than the default value. * @name CKEDITOR.config.resize_minWidth * @type Number @@ -121,6 +121,6 @@ /** - * The minimum editor height, in pixels, when resizing it with the resize handle. - * Note: It fallbacks to editor's actual height if that's smaller than the default value. + * The minimum editor height, in pixels, when resizing the editor interface by using the resize handle. + * Note: It falls back to editor's actual height if it is smaller than the default value. * @name CKEDITOR.config.resize_minHeight * @type Number @@ -131,5 +131,5 @@ /** - * The maximum editor width, in pixels, when resizing it with the resize handle. + * The maximum editor width, in pixels, when resizing the editor interface by using the resize handle. * @name CKEDITOR.config.resize_maxWidth * @type Number @@ -140,5 +140,5 @@ /** - * The maximum editor height, in pixels, when resizing it with the resize handle. + * The maximum editor height, in pixels, when resizing the editor interface by using the resize handle. * @name CKEDITOR.config.resize_maxHeight * @type Number @@ -149,5 +149,5 @@ /** - * Whether to enable the resizing feature. If disabled the resize handler will not be visible. + * Whether to enable the resizing feature. If this feature is disabled, the resize handle will not be visible. * @name CKEDITOR.config.resize_enabled * @type Boolean @@ -158,6 +158,6 @@ /** - * The directions to which the editor resizing is enabled. Possible values - * are "both", "vertical" and "horizontal". + * The dimensions for which the editor resizing is enabled. Possible values + * are both, vertical, and horizontal. * @name CKEDITOR.config.resize_dir * @type String Index: /CKEditor/trunk/_source/plugins/selection/plugin.js =================================================================== --- /CKEditor/trunk/_source/plugins/selection/plugin.js (revision 7084) +++ /CKEditor/trunk/_source/plugins/selection/plugin.js (revision 7085) @@ -490,8 +490,8 @@ /** * Gets the current selection from the editing area when in WYSIWYG mode. - * @returns {CKEDITOR.dom.selection} A selection object or null if not on + * @returns {CKEDITOR.dom.selection} A selection object or null if not in * WYSIWYG mode or no selection is available. * @example - * var selection = CKEDITOR.instances.editor1.getSelection(); + * var selection = CKEDITOR.instances.editor1.getSelection(); * alert( selection.getType() ); */ @@ -510,5 +510,5 @@ * @returns {CKEDITOR.dom.selection} A selection object. * @example - * var selection = CKEDITOR.instances.editor1.document.getSelection(); + * var selection = CKEDITOR.instances.editor1.document.getSelection(); * alert( selection.getType() ); */ @@ -529,9 +529,9 @@ /** - * Text or collapsed selection. + * A text or a collapsed selection. * @constant * @example * if ( editor.getSelection().getType() == CKEDITOR.SELECTION_TEXT ) - * alert( 'Text is selected' ); + * alert( 'A text is selected' ); */ CKEDITOR.SELECTION_TEXT = 2; @@ -549,5 +549,7 @@ * Manipulates the selection in a DOM document. * @constructor + * @param {CKEDITOR.dom.document} document The DOM document that contains the selection. * @example + * var sel = new CKEDITOR.dom.selection( CKEDITOR.document ); */ CKEDITOR.dom.selection = function( document ) @@ -567,5 +569,5 @@ /** * IE BUG: The selection's document may be a different document than the - * editor document. Return null if that's the case. + * editor document. Return null if that is the case. */ if ( CKEDITOR.env.ie ) @@ -594,7 +596,7 @@ * Gets the native selection object from the browser. * @function - * @returns {Object} The native selection object. + * @returns {Object} The native browser selection object. * @example - * var selection = editor.getSelection().getNative(); + * var selection = editor.getSelection().getNative(); */ getNative : @@ -614,17 +616,17 @@ * available: * * @function * @returns {Number} One of the following constant values: - * {@link CKEDITOR.SELECTION_NONE}, {@link CKEDITOR.SELECTION_TEXT} or - * {@link CKEDITOR.SELECTION_ELEMENT}. + * {@link CKEDITOR.SELECTION_NONE}, {@link CKEDITOR.SELECTION_TEXT}, or + * {@link CKEDITOR.SELECTION_ELEMENT}. * @example - * if ( editor.getSelection().getType() == CKEDITOR.SELECTION_TEXT ) - * alert( 'Text is selected' ); + * if ( editor.getSelection().getType() == CKEDITOR.SELECTION_TEXT ) + * alert( 'A text is selected' ); */ getType : @@ -694,11 +696,13 @@ /** - * Retrieve the {@link CKEDITOR.dom.range} instances that represent the current selection. - * Note: Some browsers returns multiple ranges even on a sequent selection, e.g. Firefox returns - * one range for each table cell when one or more table row is selected. - * @return {Array} + * Retrieves the {@link CKEDITOR.dom.range} instances that represent the current selection. + * Note: Some browsers return multiple ranges even for a continuous selection. Firefox, for example, returns + * one range for each table cell when one or more table rows are selected. + * @function + * @param {Boolean} [onlyEditables] If set to true, this function retrives editable ranges only. + * @return {Array} Range instances that represent the current selection. * @example - * var ranges = selection.getRanges(); - * alert(ranges.length); + * var ranges = selection.getRanges(); + * alert( ranges.length ); */ getRanges : (function() @@ -1032,5 +1036,5 @@ * selection. * @example - * var element = editor.getSelection().getStartElement(); + * var element = editor.getSelection().getStartElement(); * alert( element.getName() ); */ @@ -1108,10 +1112,10 @@ /** - * Gets the current selected element. + * Gets the currently selected element. * @returns {CKEDITOR.dom.element} The selected element. Null if no * selection is available or the selection type is not - * {@link CKEDITOR.SELECTION_ELEMENT}. + * {@link CKEDITOR.SELECTION_ELEMENT}. * @example - * var element = editor.getSelection().getSelectedElement(); + * var element = editor.getSelection().getSelectedElement(); * alert( element.getName() ); */ @@ -1155,9 +1159,9 @@ /** - * Retrieves the text contained within the range, empty string is returned for non-text selection. - * @returns {String} string of text within the current selection. + * Retrieves the text contained within the range. An empty string is returned for non-text selection. + * @returns {String} A string of text within the current selection. * @since 3.6.1 * @example - * var text = editor.getSelectedText(); + * var text = editor.getSelection().getSelectedText(); * alert( text ); */ @@ -1176,4 +1180,12 @@ }, + /** + * Locks the selection made in the editor in order to make it possible to + * manipulate it without browser interference. A locked selection is + * cached and remains unchanged until it is released with the #unlock + * method. + * @example + * editor.getSelection().lock(); + */ lock : function() { @@ -1193,4 +1205,11 @@ }, + /** + * Unlocks the selection made in the editor and locked with the #lock method. + * An unlocked selection is no longer cached and can be changed. + * @param {Boolean} [restore] If set to true, the selection is restored back to the selection saved earlier by using the #lock method. + * @example + * editor.getSelection().unlock(); + */ unlock : function( restore ) { @@ -1226,4 +1245,9 @@ }, + /** + * Clears the selection cache. + * @example + * editor.getSelection().reset(); + */ reset : function() { @@ -1232,6 +1256,9 @@ /** - * Make the current selection of type {@link CKEDITOR.SELECTION_ELEMENT} by enclosing the specified element. - * @param element + * Makes the current selection of type {@link CKEDITOR.SELECTION_ELEMENT} by enclosing the specified element. + * @param {CKEDITOR.dom.element} element The element to enclose in the selection. + * @example + * var element = editor.document.getById( 'sampleElement' ); + * editor.getSelection.selectElement( element ); */ selectElement : function( element ) @@ -1262,7 +1289,10 @@ /** - * Adding the specified ranges to document selection preceding - * by clearing up the original selection. - * @param {CKEDITOR.dom.range} ranges + * Clears the original selection and adds the specified ranges + * to the document selection. + * @param {Array} ranges An array of {@link CKEDITOR.dom.range} instances representing ranges to be added to the document. + * @example + * var ranges = new CKEDITOR.dom.range( editor.document ); + * editor.getSelection().selectRanges( [ ranges ] ); */ selectRanges : function( ranges ) @@ -1408,8 +1438,11 @@ /** - * Create bookmark for every single of this selection range (from #getRanges) - * by calling the {@link CKEDITOR.dom.range.prototype.createBookmark} method, - * with extra cares to avoid interferon among those ranges. Same arguments are - * received as with the underlay range method. + * Creates a bookmark for each range of this selection (from #getRanges) + * by calling the {@link CKEDITOR.dom.range.prototype.createBookmark} method, + * with extra care taken to avoid interference among those ranges. The arguments + * received are the same as with the underlying range method. + * @returns {Array} Array of bookmarks for each range. + * @example + * var bookmarks = editor.getSelection().createBookmarks(); */ createBookmarks : function( serializable ) @@ -1419,8 +1452,11 @@ /** - * Create bookmark for every single of this selection range (from #getRanges) - * by calling the {@link CKEDITOR.dom.range.prototype.createBookmark2} method, - * with extra cares to avoid interferon among those ranges. Same arguments are - * received as with the underlay range method. + * Creates a bookmark for each range of this selection (from #getRanges) + * by calling the {@link CKEDITOR.dom.range.prototype.createBookmark2} method, + * with extra care taken to avoid interference among those ranges. The arguments + * received are the same as with the underlying range method. + * @returns {Array} Array of bookmarks for each range. + * @example + * var bookmarks = editor.getSelection().createBookmarks2(); */ createBookmarks2 : function( normalized ) @@ -1430,6 +1466,10 @@ /** - * Select the virtual ranges denote by the bookmarks by calling #selectRanges. - * @param bookmarks + * Selects the virtual ranges denoted by the bookmarks by calling #selectRanges. + * @param {Array} bookmarks The bookmarks representing ranges to be selected. + * @returns {CKEDITOR.dom.selection} This selection object, after the ranges were selected. + * @example + * var bookmarks = editor.getSelection().createBookmarks(); + * editor.getSelection().selectBookmarks( bookmarks ); */ selectBookmarks : function( bookmarks ) @@ -1447,5 +1487,8 @@ /** - * Retrieve the common ancestor node of the first range and the last range. + * Retrieves the common ancestor node of the first range and the last range. + * @returns {CKEDITOR.dom.element} The common ancestor of the selection. + * @example + * var ancestor = editor.getSelection().getCommonAncestor(); */ getCommonAncestor : function() @@ -1458,5 +1501,7 @@ /** - * Moving scroll bar to the current selection's start position. + * Moves the scrollbar to the starting position of the current selection. + * @example + * editor.getSelection().scrollIntoView(); */ scrollIntoView : function()