1 /* 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * 4 * This code is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU General Public License version 2 only, as 6 * published by the Free Software Foundation. Oracle designates this 7 * particular file as subject to the "Classpath" exception as provided 8 * by Oracle in the LICENSE file that accompanied this code. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25 /* 26 * This file is available under and governed by the GNU General Public 27 * License version 2 only, as published by the Free Software Foundation. 28 * However, the following notice accompanied the original version of this 29 * file and, per its terms, should not be removed: 30 * 31 * Copyright (c) 2000 World Wide Web Consortium, 32 * (Massachusetts Institute of Technology, Institut National de 33 * Recherche en Informatique et en Automatique, Keio University). All 34 * Rights Reserved. This program is distributed under the W3C's Software 35 * Intellectual Property License. This program is distributed in the 36 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even 37 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 38 * PURPOSE. 39 * See W3C License http://www.w3.org/Consortium/Legal/ for more details. 40 */ 41 42 package org.w3c.dom.ranges; 43 44 import org.w3c.dom.Node; 45 import org.w3c.dom.DOMException; 46 import org.w3c.dom.DocumentFragment; 47 48 /** 49 * <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>. 50 * @since 9, DOM Level 2 51 */ 52 public interface Range { 53 /** 54 * Node within which the Range begins 55 * @exception DOMException 56 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 57 * invoked on this object. 58 */ getStartContainer()59 public Node getStartContainer() 60 throws DOMException; 61 62 /** 63 * Offset within the starting node of the Range. 64 * @exception DOMException 65 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 66 * invoked on this object. 67 */ getStartOffset()68 public int getStartOffset() 69 throws DOMException; 70 71 /** 72 * Node within which the Range ends 73 * @exception DOMException 74 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 75 * invoked on this object. 76 */ getEndContainer()77 public Node getEndContainer() 78 throws DOMException; 79 80 /** 81 * Offset within the ending node of the Range. 82 * @exception DOMException 83 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 84 * invoked on this object. 85 */ getEndOffset()86 public int getEndOffset() 87 throws DOMException; 88 89 /** 90 * TRUE if the Range is collapsed 91 * @exception DOMException 92 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 93 * invoked on this object. 94 */ getCollapsed()95 public boolean getCollapsed() 96 throws DOMException; 97 98 /** 99 * The deepest common ancestor container of the Range's two 100 * boundary-points. 101 * @exception DOMException 102 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 103 * invoked on this object. 104 */ getCommonAncestorContainer()105 public Node getCommonAncestorContainer() 106 throws DOMException; 107 108 /** 109 * Sets the attributes describing the start of the Range. 110 * @param refNode The <code>refNode</code> value. This parameter must be 111 * different from <code>null</code>. 112 * @param offset The <code>startOffset</code> value. 113 * @exception RangeException 114 * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor 115 * of <code>refNode</code> is an Entity, Notation, or DocumentType 116 * node. 117 * @exception DOMException 118 * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater 119 * than the number of child units in <code>refNode</code>. Child units 120 * are 16-bit units if <code>refNode</code> is a type of CharacterData 121 * node (e.g., a Text or Comment node) or a ProcessingInstruction 122 * node. Child units are Nodes in all other cases. 123 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 124 * been invoked on this object. 125 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 126 * from a different document than the one that created this range. 127 */ setStart(Node refNode, int offset)128 public void setStart(Node refNode, 129 int offset) 130 throws RangeException, DOMException; 131 132 /** 133 * Sets the attributes describing the end of a Range. 134 * @param refNode The <code>refNode</code> value. This parameter must be 135 * different from <code>null</code>. 136 * @param offset The <code>endOffset</code> value. 137 * @exception RangeException 138 * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor 139 * of <code>refNode</code> is an Entity, Notation, or DocumentType 140 * node. 141 * @exception DOMException 142 * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater 143 * than the number of child units in <code>refNode</code>. Child units 144 * are 16-bit units if <code>refNode</code> is a type of CharacterData 145 * node (e.g., a Text or Comment node) or a ProcessingInstruction 146 * node. Child units are Nodes in all other cases. 147 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 148 * been invoked on this object. 149 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 150 * from a different document than the one that created this range. 151 */ setEnd(Node refNode, int offset)152 public void setEnd(Node refNode, 153 int offset) 154 throws RangeException, DOMException; 155 156 /** 157 * Sets the start position to be before a node 158 * @param refNode Range starts before <code>refNode</code> 159 * @exception RangeException 160 * INVALID_NODE_TYPE_ERR: Raised if the root container of 161 * <code>refNode</code> is not an Attr, Document, or DocumentFragment 162 * node or if <code>refNode</code> is a Document, DocumentFragment, 163 * Attr, Entity, or Notation node. 164 * @exception DOMException 165 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 166 * invoked on this object. 167 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 168 * from a different document than the one that created this range. 169 */ setStartBefore(Node refNode)170 public void setStartBefore(Node refNode) 171 throws RangeException, DOMException; 172 173 /** 174 * Sets the start position to be after a node 175 * @param refNode Range starts after <code>refNode</code> 176 * @exception RangeException 177 * INVALID_NODE_TYPE_ERR: Raised if the root container of 178 * <code>refNode</code> is not an Attr, Document, or DocumentFragment 179 * node or if <code>refNode</code> is a Document, DocumentFragment, 180 * Attr, Entity, or Notation node. 181 * @exception DOMException 182 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 183 * invoked on this object. 184 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 185 * from a different document than the one that created this range. 186 */ setStartAfter(Node refNode)187 public void setStartAfter(Node refNode) 188 throws RangeException, DOMException; 189 190 /** 191 * Sets the end position to be before a node. 192 * @param refNode Range ends before <code>refNode</code> 193 * @exception RangeException 194 * INVALID_NODE_TYPE_ERR: Raised if the root container of 195 * <code>refNode</code> is not an Attr, Document, or DocumentFragment 196 * node or if <code>refNode</code> is a Document, DocumentFragment, 197 * Attr, Entity, or Notation node. 198 * @exception DOMException 199 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 200 * invoked on this object. 201 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 202 * from a different document than the one that created this range. 203 */ setEndBefore(Node refNode)204 public void setEndBefore(Node refNode) 205 throws RangeException, DOMException; 206 207 /** 208 * Sets the end of a Range to be after a node 209 * @param refNode Range ends after <code>refNode</code>. 210 * @exception RangeException 211 * INVALID_NODE_TYPE_ERR: Raised if the root container of 212 * <code>refNode</code> is not an Attr, Document or DocumentFragment 213 * node or if <code>refNode</code> is a Document, DocumentFragment, 214 * Attr, Entity, or Notation node. 215 * @exception DOMException 216 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 217 * invoked on this object. 218 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 219 * from a different document than the one that created this range. 220 */ setEndAfter(Node refNode)221 public void setEndAfter(Node refNode) 222 throws RangeException, DOMException; 223 224 /** 225 * Collapse a Range onto one of its boundary-points 226 * @param toStart If TRUE, collapses the Range onto its start; if FALSE, 227 * collapses it onto its end. 228 * @exception DOMException 229 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 230 * invoked on this object. 231 */ collapse(boolean toStart)232 public void collapse(boolean toStart) 233 throws DOMException; 234 235 /** 236 * Select a node and its contents 237 * @param refNode The node to select. 238 * @exception RangeException 239 * INVALID_NODE_TYPE_ERR: Raised if an ancestor of <code>refNode</code> 240 * is an Entity, Notation or DocumentType node or if 241 * <code>refNode</code> is a Document, DocumentFragment, Attr, Entity, 242 * or Notation node. 243 * @exception DOMException 244 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 245 * invoked on this object. 246 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 247 * from a different document than the one that created this range. 248 */ selectNode(Node refNode)249 public void selectNode(Node refNode) 250 throws RangeException, DOMException; 251 252 /** 253 * Select the contents within a node 254 * @param refNode Node to select from 255 * @exception RangeException 256 * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor 257 * of <code>refNode</code> is an Entity, Notation or DocumentType node. 258 * @exception DOMException 259 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 260 * invoked on this object. 261 * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 262 * from a different document than the one that created this range. 263 */ selectNodeContents(Node refNode)264 public void selectNodeContents(Node refNode) 265 throws RangeException, DOMException; 266 267 // CompareHow 268 /** 269 * Compare start boundary-point of <code>sourceRange</code> to start 270 * boundary-point of Range on which <code>compareBoundaryPoints</code> 271 * is invoked. 272 */ 273 public static final short START_TO_START = 0; 274 /** 275 * Compare start boundary-point of <code>sourceRange</code> to end 276 * boundary-point of Range on which <code>compareBoundaryPoints</code> 277 * is invoked. 278 */ 279 public static final short START_TO_END = 1; 280 /** 281 * Compare end boundary-point of <code>sourceRange</code> to end 282 * boundary-point of Range on which <code>compareBoundaryPoints</code> 283 * is invoked. 284 */ 285 public static final short END_TO_END = 2; 286 /** 287 * Compare end boundary-point of <code>sourceRange</code> to start 288 * boundary-point of Range on which <code>compareBoundaryPoints</code> 289 * is invoked. 290 */ 291 public static final short END_TO_START = 3; 292 293 /** 294 * Compare the boundary-points of two Ranges in a document. 295 * @param how A code representing the type of comparison, as defined 296 * above. 297 * @param sourceRange The <code>Range</code> on which this current 298 * <code>Range</code> is compared to. 299 * @return -1, 0 or 1 depending on whether the corresponding 300 * boundary-point of the Range is respectively before, equal to, or 301 * after the corresponding boundary-point of <code>sourceRange</code>. 302 * @exception DOMException 303 * WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same 304 * Document or DocumentFragment. 305 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 306 * been invoked on this object. 307 */ compareBoundaryPoints(short how, Range sourceRange)308 public short compareBoundaryPoints(short how, 309 Range sourceRange) 310 throws DOMException; 311 312 /** 313 * Removes the contents of a Range from the containing document or 314 * document fragment without returning a reference to the removed 315 * content. 316 * @exception DOMException 317 * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of 318 * the Range is read-only or any of the nodes that contain any of the 319 * content of the Range are read-only. 320 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 321 * been invoked on this object. 322 */ deleteContents()323 public void deleteContents() 324 throws DOMException; 325 326 /** 327 * Moves the contents of a Range from the containing document or document 328 * fragment to a new DocumentFragment. 329 * @return A DocumentFragment containing the extracted contents. 330 * @exception DOMException 331 * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of 332 * the Range is read-only or any of the nodes which contain any of the 333 * content of the Range are read-only. 334 * <br>HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be 335 * extracted into the new DocumentFragment. 336 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 337 * been invoked on this object. 338 */ extractContents()339 public DocumentFragment extractContents() 340 throws DOMException; 341 342 /** 343 * Duplicates the contents of a Range 344 * @return A DocumentFragment that contains content equivalent to this 345 * Range. 346 * @exception DOMException 347 * HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be 348 * extracted into the new DocumentFragment. 349 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 350 * been invoked on this object. 351 */ cloneContents()352 public DocumentFragment cloneContents() 353 throws DOMException; 354 355 /** 356 * Inserts a node into the Document or DocumentFragment at the start of 357 * the Range. If the container is a Text node, this will be split at the 358 * start of the Range (as if the Text node's splitText method was 359 * performed at the insertion point) and the insertion will occur 360 * between the two resulting Text nodes. Adjacent Text nodes will not be 361 * automatically merged. If the node to be inserted is a 362 * DocumentFragment node, the children will be inserted rather than the 363 * DocumentFragment node itself. 364 * @param newNode The node to insert at the start of the Range 365 * @exception DOMException 366 * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the 367 * start of the Range is read-only. 368 * <br>WRONG_DOCUMENT_ERR: Raised if <code>newNode</code> and the 369 * container of the start of the Range were not created from the same 370 * document. 371 * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of 372 * the Range is of a type that does not allow children of the type of 373 * <code>newNode</code> or if <code>newNode</code> is an ancestor of 374 * the container. 375 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 376 * been invoked on this object. 377 * @exception RangeException 378 * INVALID_NODE_TYPE_ERR: Raised if <code>newNode</code> is an Attr, 379 * Entity, Notation, or Document node. 380 */ insertNode(Node newNode)381 public void insertNode(Node newNode) 382 throws DOMException, RangeException; 383 384 /** 385 * Reparents the contents of the Range to the given node and inserts the 386 * node at the position of the start of the Range. 387 * @param newParent The node to surround the contents with. 388 * @exception DOMException 389 * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of 390 * either boundary-point of the Range is read-only. 391 * <br>WRONG_DOCUMENT_ERR: Raised if <code> newParent</code> and the 392 * container of the start of the Range were not created from the same 393 * document. 394 * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of 395 * the Range is of a type that does not allow children of the type of 396 * <code>newParent</code> or if <code>newParent</code> is an ancestor 397 * of the container or if <code>node</code> would end up with a child 398 * node of a type not allowed by the type of <code>node</code>. 399 * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 400 * been invoked on this object. 401 * @exception RangeException 402 * BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a 403 * non-text node. 404 * <br>INVALID_NODE_TYPE_ERR: Raised if <code> node</code> is an Attr, 405 * Entity, DocumentType, Notation, Document, or DocumentFragment node. 406 */ surroundContents(Node newParent)407 public void surroundContents(Node newParent) 408 throws DOMException, RangeException; 409 410 /** 411 * Produces a new Range whose boundary-points are equal to the 412 * boundary-points of the Range. 413 * @return The duplicated Range. 414 * @exception DOMException 415 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 416 * invoked on this object. 417 */ cloneRange()418 public Range cloneRange() 419 throws DOMException; 420 421 /** 422 * Returns the contents of a Range as a string. This string contains only 423 * the data characters, not any markup. 424 * @return The contents of the Range. 425 * @exception DOMException 426 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 427 * invoked on this object. 428 */ toString()429 public String toString() 430 throws DOMException; 431 432 /** 433 * Called to indicate that the Range is no longer in use and that the 434 * implementation may relinquish any resources associated with this 435 * Range. Subsequent calls to any methods or attribute getters on this 436 * Range will result in a <code>DOMException</code> being thrown with an 437 * error code of <code>INVALID_STATE_ERR</code>. 438 * @exception DOMException 439 * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 440 * invoked on this object. 441 */ detach()442 public void detach() 443 throws DOMException; 444 445 } 446