001 /* 002 * Copyright (c) 2000 World Wide Web Consortium, 003 * (Massachusetts Institute of Technology, Institut National de 004 * Recherche en Informatique et en Automatique, Keio University). All 005 * Rights Reserved. This program is distributed under the W3C's Software 006 * Intellectual Property License. This program is distributed in the 007 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even 008 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 009 * PURPOSE. 010 * See W3C License http://www.w3.org/Consortium/Legal/ for more details. 011 */ 012 013 package org.w3c.dom.ranges; 014 015 import org.w3c.dom.Node; 016 import org.w3c.dom.DOMException; 017 import org.w3c.dom.DocumentFragment; 018 019 /** 020 * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>. 021 * @since DOM Level 2 022 */ 023 public interface Range { 024 /** 025 * Node within which the Range begins 026 * @exception DOMException 027 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 028 * invoked on this object. 029 */ 030 public Node getStartContainer() 031 throws DOMException; 032 033 /** 034 * Offset within the starting node of the Range. 035 * @exception DOMException 036 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 037 * invoked on this object. 038 */ 039 public int getStartOffset() 040 throws DOMException; 041 042 /** 043 * Node within which the Range ends 044 * @exception DOMException 045 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 046 * invoked on this object. 047 */ 048 public Node getEndContainer() 049 throws DOMException; 050 051 /** 052 * Offset within the ending node of the Range. 053 * @exception DOMException 054 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 055 * invoked on this object. 056 */ 057 public int getEndOffset() 058 throws DOMException; 059 060 /** 061 * TRUE if the Range is collapsed 062 * @exception DOMException 063 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 064 * invoked on this object. 065 */ 066 public boolean getCollapsed() 067 throws DOMException; 068 069 /** 070 * The deepest common ancestor container of the Range's two 071 * boundary-points. 072 * @exception DOMException 073 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 074 * invoked on this object. 075 */ 076 public Node getCommonAncestorContainer() 077 throws DOMException; 078 079 /** 080 * Sets the attributes describing the start of the Range. 081 * @param refNode The <code>refNode</code> value. This parameter must be 082 * different from <code>null</code>. 083 * @param offset The <code>startOffset</code> value. 084 * @exception RangeException 085 * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor 086 * of <code>refNode</code> is an Entity, Notation, or DocumentType 087 * node. 088 * @exception DOMException 089 * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater 090 * than the number of child units in <code>refNode</code>. Child units 091 * are 16-bit units if <code>refNode</code> is a type of CharacterData 092 * node (e.g., a Text or Comment node) or a ProcessingInstruction 093 * node. Child units are Nodes in all other cases. 094 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 095 * been invoked on this object. 096 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 097 * from a different document than the one that created this range. 098 */ 099 public void setStart(Node refNode, 100 int offset) 101 throws RangeException, DOMException; 102 103 /** 104 * Sets the attributes describing the end of a Range. 105 * @param refNode The <code>refNode</code> value. This parameter must be 106 * different from <code>null</code>. 107 * @param offset The <code>endOffset</code> value. 108 * @exception RangeException 109 * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor 110 * of <code>refNode</code> is an Entity, Notation, or DocumentType 111 * node. 112 * @exception DOMException 113 * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater 114 * than the number of child units in <code>refNode</code>. Child units 115 * are 16-bit units if <code>refNode</code> is a type of CharacterData 116 * node (e.g., a Text or Comment node) or a ProcessingInstruction 117 * node. Child units are Nodes in all other cases. 118 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 119 * been invoked on this object. 120 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 121 * from a different document than the one that created this range. 122 */ 123 public void setEnd(Node refNode, 124 int offset) 125 throws RangeException, DOMException; 126 127 /** 128 * Sets the start position to be before a node 129 * @param refNode Range starts before <code>refNode</code> 130 * @exception RangeException 131 * INVALID_NODE_TYPE_ERR: Raised if the root container of 132 * <code>refNode</code> is not an Attr, Document, or DocumentFragment 133 * node or if <code>refNode</code> is a Document, DocumentFragment, 134 * Attr, Entity, or Notation node. 135 * @exception DOMException 136 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 137 * invoked on this object. 138 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 139 * from a different document than the one that created this range. 140 */ 141 public void setStartBefore(Node refNode) 142 throws RangeException, DOMException; 143 144 /** 145 * Sets the start position to be after a node 146 * @param refNode Range starts after <code>refNode</code> 147 * @exception RangeException 148 * INVALID_NODE_TYPE_ERR: Raised if the root container of 149 * <code>refNode</code> is not an Attr, Document, or DocumentFragment 150 * node or if <code>refNode</code> is a Document, DocumentFragment, 151 * Attr, Entity, or Notation node. 152 * @exception DOMException 153 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 154 * invoked on this object. 155 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 156 * from a different document than the one that created this range. 157 */ 158 public void setStartAfter(Node refNode) 159 throws RangeException, DOMException; 160 161 /** 162 * Sets the end position to be before a node. 163 * @param refNode Range ends before <code>refNode</code> 164 * @exception RangeException 165 * INVALID_NODE_TYPE_ERR: Raised if the root container of 166 * <code>refNode</code> is not an Attr, Document, or DocumentFragment 167 * node or if <code>refNode</code> is a Document, DocumentFragment, 168 * Attr, Entity, or Notation node. 169 * @exception DOMException 170 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 171 * invoked on this object. 172 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 173 * from a different document than the one that created this range. 174 */ 175 public void setEndBefore(Node refNode) 176 throws RangeException, DOMException; 177 178 /** 179 * Sets the end of a Range to be after a node 180 * @param refNode Range ends after <code>refNode</code>. 181 * @exception RangeException 182 * INVALID_NODE_TYPE_ERR: Raised if the root container of 183 * <code>refNode</code> is not an Attr, Document or DocumentFragment 184 * node or if <code>refNode</code> is a Document, DocumentFragment, 185 * Attr, Entity, or Notation node. 186 * @exception DOMException 187 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 188 * invoked on this object. 189 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 190 * from a different document than the one that created this range. 191 */ 192 public void setEndAfter(Node refNode) 193 throws RangeException, DOMException; 194 195 /** 196 * Collapse a Range onto one of its boundary-points 197 * @param toStart If TRUE, collapses the Range onto its start; if FALSE, 198 * collapses it onto its end. 199 * @exception DOMException 200 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 201 * invoked on this object. 202 */ 203 public void collapse(boolean toStart) 204 throws DOMException; 205 206 /** 207 * Select a node and its contents 208 * @param refNode The node to select. 209 * @exception RangeException 210 * INVALID_NODE_TYPE_ERR: Raised if an ancestor of <code>refNode</code> 211 * is an Entity, Notation or DocumentType node or if 212 * <code>refNode</code> is a Document, DocumentFragment, Attr, Entity, 213 * or Notation node. 214 * @exception DOMException 215 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 216 * invoked on this object. 217 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 218 * from a different document than the one that created this range. 219 */ 220 public void selectNode(Node refNode) 221 throws RangeException, DOMException; 222 223 /** 224 * Select the contents within a node 225 * @param refNode Node to select from 226 * @exception RangeException 227 * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor 228 * of <code>refNode</code> is an Entity, Notation or DocumentType node. 229 * @exception DOMException 230 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 231 * invoked on this object. 232 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 233 * from a different document than the one that created this range. 234 */ 235 public void selectNodeContents(Node refNode) 236 throws RangeException, DOMException; 237 238 // CompareHow 239 /** 240 * Compare start boundary-point of <code>sourceRange</code> to start 241 * boundary-point of Range on which <code>compareBoundaryPoints</code> 242 * is invoked. 243 */ 244 public static final short START_TO_START = 0; 245 /** 246 * Compare start boundary-point of <code>sourceRange</code> to end 247 * boundary-point of Range on which <code>compareBoundaryPoints</code> 248 * is invoked. 249 */ 250 public static final short START_TO_END = 1; 251 /** 252 * Compare end boundary-point of <code>sourceRange</code> to end 253 * boundary-point of Range on which <code>compareBoundaryPoints</code> 254 * is invoked. 255 */ 256 public static final short END_TO_END = 2; 257 /** 258 * Compare end boundary-point of <code>sourceRange</code> to start 259 * boundary-point of Range on which <code>compareBoundaryPoints</code> 260 * is invoked. 261 */ 262 public static final short END_TO_START = 3; 263 264 /** 265 * Compare the boundary-points of two Ranges in a document. 266 * @param how A code representing the type of comparison, as defined 267 * above. 268 * @param sourceRange The <code>Range</code> on which this current 269 * <code>Range</code> is compared to. 270 * @return -1, 0 or 1 depending on whether the corresponding 271 * boundary-point of the Range is respectively before, equal to, or 272 * after the corresponding boundary-point of <code>sourceRange</code>. 273 * @exception DOMException 274 * WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same 275 * Document or DocumentFragment. 276 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 277 * been invoked on this object. 278 */ 279 public short compareBoundaryPoints(short how, 280 Range sourceRange) 281 throws DOMException; 282 283 /** 284 * Removes the contents of a Range from the containing document or 285 * document fragment without returning a reference to the removed 286 * content. 287 * @exception DOMException 288 * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of 289 * the Range is read-only or any of the nodes that contain any of the 290 * content of the Range are read-only. 291 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 292 * been invoked on this object. 293 */ 294 public void deleteContents() 295 throws DOMException; 296 297 /** 298 * Moves the contents of a Range from the containing document or document 299 * fragment to a new DocumentFragment. 300 * @return A DocumentFragment containing the extracted contents. 301 * @exception DOMException 302 * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of 303 * the Range is read-only or any of the nodes which contain any of the 304 * content of the Range are read-only. 305 * <br>HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be 306 * extracted into the new DocumentFragment. 307 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 308 * been invoked on this object. 309 */ 310 public DocumentFragment extractContents() 311 throws DOMException; 312 313 /** 314 * Duplicates the contents of a Range 315 * @return A DocumentFragment that contains content equivalent to this 316 * Range. 317 * @exception DOMException 318 * HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be 319 * extracted into the new DocumentFragment. 320 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 321 * been invoked on this object. 322 */ 323 public DocumentFragment cloneContents() 324 throws DOMException; 325 326 /** 327 * Inserts a node into the Document or DocumentFragment at the start of 328 * the Range. If the container is a Text node, this will be split at the 329 * start of the Range (as if the Text node's splitText method was 330 * performed at the insertion point) and the insertion will occur 331 * between the two resulting Text nodes. Adjacent Text nodes will not be 332 * automatically merged. If the node to be inserted is a 333 * DocumentFragment node, the children will be inserted rather than the 334 * DocumentFragment node itself. 335 * @param newNode The node to insert at the start of the Range 336 * @exception DOMException 337 * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the 338 * start of the Range is read-only. 339 * <br>WRONG_DOCUMENT_ERR: Raised if <code>newNode</code> and the 340 * container of the start of the Range were not created from the same 341 * document. 342 * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of 343 * the Range is of a type that does not allow children of the type of 344 * <code>newNode</code> or if <code>newNode</code> is an ancestor of 345 * the container. 346 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 347 * been invoked on this object. 348 * @exception RangeException 349 * INVALID_NODE_TYPE_ERR: Raised if <code>newNode</code> is an Attr, 350 * Entity, Notation, or Document node. 351 */ 352 public void insertNode(Node newNode) 353 throws DOMException, RangeException; 354 355 /** 356 * Reparents the contents of the Range to the given node and inserts the 357 * node at the position of the start of the Range. 358 * @param newParent The node to surround the contents with. 359 * @exception DOMException 360 * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of 361 * either boundary-point of the Range is read-only. 362 * <br>WRONG_DOCUMENT_ERR: Raised if <code> newParent</code> and the 363 * container of the start of the Range were not created from the same 364 * document. 365 * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of 366 * the Range is of a type that does not allow children of the type of 367 * <code>newParent</code> or if <code>newParent</code> is an ancestor 368 * of the container or if <code>node</code> would end up with a child 369 * node of a type not allowed by the type of <code>node</code>. 370 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 371 * been invoked on this object. 372 * @exception RangeException 373 * BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a 374 * non-text node. 375 * <br>INVALID_NODE_TYPE_ERR: Raised if <code> node</code> is an Attr, 376 * Entity, DocumentType, Notation, Document, or DocumentFragment node. 377 */ 378 public void surroundContents(Node newParent) 379 throws DOMException, RangeException; 380 381 /** 382 * Produces a new Range whose boundary-points are equal to the 383 * boundary-points of the Range. 384 * @return The duplicated Range. 385 * @exception DOMException 386 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 387 * invoked on this object. 388 */ 389 public Range cloneRange() 390 throws DOMException; 391 392 /** 393 * Returns the contents of a Range as a string. This string contains only 394 * the data characters, not any markup. 395 * @return The contents of the Range. 396 * @exception DOMException 397 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 398 * invoked on this object. 399 */ 400 public String toString() 401 throws DOMException; 402 403 /** 404 * Called to indicate that the Range is no longer in use and that the 405 * implementation may relinquish any resources associated with this 406 * Range. Subsequent calls to any methods or attribute getters on this 407 * Range will result in a <code>DOMException</code> being thrown with an 408 * error code of <code>INVALID_STATE_ERR</code>. 409 * @exception DOMException 410 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 411 * invoked on this object. 412 */ 413 public void detach() 414 throws DOMException; 415 416 }