| Frames | No Frames |
1: /* 2: * Copyright (c) 2000 World Wide Web Consortium, 3: * (Massachusetts Institute of Technology, Institut National de 4: * Recherche en Informatique et en Automatique, Keio University). All 5: * Rights Reserved. This program is distributed under the W3C's Software 6: * Intellectual Property License. This program is distributed in the 7: * hope that it will be useful, but WITHOUT ANY WARRANTY; without even 8: * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 9: * PURPOSE. 10: * See W3C License http://www.w3.org/Consortium/Legal/ for more details. 11: */ 12: 13: package org.w3c.dom.ranges; 14: 15: import org.w3c.dom.Node; 16: import org.w3c.dom.DOMException; 17: import org.w3c.dom.DocumentFragment; 18: 19: /** 20: * <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>. 21: * @since DOM Level 2 22: */ 23: public interface Range { 24: /** 25: * Node within which the Range begins 26: * @exception DOMException 27: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 28: * invoked on this object. 29: */ 30: public Node getStartContainer() 31: throws DOMException; 32: 33: /** 34: * Offset within the starting node of the Range. 35: * @exception DOMException 36: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 37: * invoked on this object. 38: */ 39: public int getStartOffset() 40: throws DOMException; 41: 42: /** 43: * Node within which the Range ends 44: * @exception DOMException 45: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 46: * invoked on this object. 47: */ 48: public Node getEndContainer() 49: throws DOMException; 50: 51: /** 52: * Offset within the ending node of the Range. 53: * @exception DOMException 54: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 55: * invoked on this object. 56: */ 57: public int getEndOffset() 58: throws DOMException; 59: 60: /** 61: * TRUE if the Range is collapsed 62: * @exception DOMException 63: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 64: * invoked on this object. 65: */ 66: public boolean getCollapsed() 67: throws DOMException; 68: 69: /** 70: * The deepest common ancestor container of the Range's two 71: * boundary-points. 72: * @exception DOMException 73: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 74: * invoked on this object. 75: */ 76: public Node getCommonAncestorContainer() 77: throws DOMException; 78: 79: /** 80: * Sets the attributes describing the start of the Range. 81: * @param refNode The <code>refNode</code> value. This parameter must be 82: * different from <code>null</code>. 83: * @param offset The <code>startOffset</code> value. 84: * @exception RangeException 85: * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor 86: * of <code>refNode</code> is an Entity, Notation, or DocumentType 87: * node. 88: * @exception DOMException 89: * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater 90: * than the number of child units in <code>refNode</code>. Child units 91: * are 16-bit units if <code>refNode</code> is a type of CharacterData 92: * node (e.g., a Text or Comment node) or a ProcessingInstruction 93: * node. Child units are Nodes in all other cases. 94: * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 95: * been invoked on this object. 96: * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 97: * from a different document than the one that created this range. 98: */ 99: 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: }