vanilla ckeditor-3.5.3

[ckeditor.git] / _source / core / dom / range.js

diff --git a/_source/core/dom/range.js b/_source/core/dom/range.js
index fedbfb9..4c0067b 100644 (file)
--- a/_source/core/dom/range.js
+++ b/_source/core/dom/range.js
@@ -4,16 +4,87 @@ For licensing, see LICENSE.html or http://ckeditor.com/license
 */\r
 \r
 /**\r
- * @class\r
+ * Creates a CKEDITOR.dom.range instance that can be used inside a specific\r
+ * DOM Document.\r
+ * @class Represents a delimited piece of content in a DOM Document.\r
+ * It is contiguous in the sense that it can be characterized as selecting all\r
+ * of the content between a pair of boundary-points.<br>\r
+ * <br>\r
+ * This class shares much of the W3C\r
+ * <a href="http://www.w3.org/TR/DOM-Level-2-Traversal-Range/ranges.html">Document Object Model Range</a>\r
+ * ideas and features, adding several range manipulation tools to it, but it's\r
+ * not intended to be compatible with it.\r
+ * @param {CKEDITOR.dom.document} document The document into which the range\r
+ *             features will be available.\r
+ * @example\r
+ * // Create a range for the entire contents of the editor document body.\r
+ * var range = new CKEDITOR.dom.range( editor.document );\r
+ * range.selectNodeContents( editor.document.getBody() );\r
+ * // Delete the contents.\r
+ * range.deleteContents();\r
  */\r
 CKEDITOR.dom.range = function( document )\r
 {\r
+       /**\r
+        * Node within which the range begins.\r
+        * @type {CKEDITOR.NODE_ELEMENT|CKEDITOR.NODE_TEXT}\r
+        * @example\r
+        * var range = new CKEDITOR.dom.range( editor.document );\r
+        * range.selectNodeContents( editor.document.getBody() );\r
+        * alert( range.startContainer.getName() );  // "body"\r
+        */\r
        this.startContainer     = null;\r
+\r
+       /**\r
+        * Offset within the starting node of the range.\r
+        * @type {Number}\r
+        * @example\r
+        * var range = new CKEDITOR.dom.range( editor.document );\r
+        * range.selectNodeContents( editor.document.getBody() );\r
+        * alert( range.startOffset );  // "0"\r
+        */\r
        this.startOffset        = null;\r
+\r
+       /**\r
+        * Node within which the range ends.\r
+        * @type {CKEDITOR.NODE_ELEMENT|CKEDITOR.NODE_TEXT}\r
+        * @example\r
+        * var range = new CKEDITOR.dom.range( editor.document );\r
+        * range.selectNodeContents( editor.document.getBody() );\r
+        * alert( range.endContainer.getName() );  // "body"\r
+        */\r
        this.endContainer       = null;\r
+\r
+       /**\r
+        * Offset within the ending node of the range.\r
+        * @type {Number}\r
+        * @example\r
+        * var range = new CKEDITOR.dom.range( editor.document );\r
+        * range.selectNodeContents( editor.document.getBody() );\r
+        * alert( range.endOffset );  // == editor.document.getBody().getChildCount()\r
+        */\r
        this.endOffset          = null;\r
+\r
+       /**\r
+        * Indicates that this is a collapsed range. A collapsed range has it's\r
+        * start and end boudaries at the very same point so nothing is contained\r
+        * in it.\r
+        * @example\r
+        * var range = new CKEDITOR.dom.range( editor.document );\r
+        * range.selectNodeContents( editor.document.getBody() );\r
+        * alert( range.collapsed );  // "false"\r
+        * range.collapse();\r
+        * alert( range.collapsed );  // "true"\r
+        */\r
        this.collapsed          = true;\r
 \r
+       /**\r
+        * The document within which the range can be used.\r
+        * @type {CKEDITOR.dom.document}\r
+        * @example\r
+        * // Selects the body contents of the range document.\r
+        * range.selectNodeContents( range.document.getBody() );\r
+        */\r
        this.document = document;\r
 };\r
 \r
@@ -518,6 +589,10 @@ CKEDITOR.dom.range = function( document )
                                                startContainer = child;\r
                                                startOffset = 0;\r
                                        }\r
+\r
+                                       // Get the normalized offset.\r
+                                       if ( child && child.type == CKEDITOR.NODE_ELEMENT )\r
+                                               startOffset = child.getIndex( 1 );\r
                                }\r
 \r
                                // Normalize the start.\r
@@ -546,6 +621,10 @@ CKEDITOR.dom.range = function( document )
                                                        endContainer = child;\r
                                                        endOffset = 0;\r
                                                }\r
+\r
+                                               // Get the normalized offset.\r
+                                               if ( child && child.type == CKEDITOR.NODE_ELEMENT )\r
+                                                       endOffset = child.getIndex( 1 );\r
                                        }\r
 \r
                                        // Normalize the end.\r