+++ /dev/null
-/*\r
- * Copyright (c) 2000 World Wide Web Consortium,\r
- * (Massachusetts Institute of Technology, Institut National de\r
- * Recherche en Informatique et en Automatique, Keio University). All\r
- * Rights Reserved. This program is distributed under the W3C's Software\r
- * Intellectual Property License. This program is distributed in the\r
- * hope that it will be useful, but WITHOUT ANY WARRANTY; without even\r
- * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR\r
- * PURPOSE.\r
- * See W3C License http://www.w3.org/Consortium/Legal/ for more details.\r
- */\r
-\r
-package org.w3c.dom.ranges;\r
-\r
-import org.w3c.dom.Node;\r
-import org.w3c.dom.DocumentFragment;\r
-import org.w3c.dom.DOMException;\r
-\r
-/**\r
- * <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>.\r
- * @since DOM Level 2\r
- */\r
-public interface Range {\r
- /**\r
- * Node within which the Range begins \r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public Node getStartContainer()\r
- throws DOMException;\r
-\r
- /**\r
- * Offset within the starting node of the Range. \r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public int getStartOffset()\r
- throws DOMException;\r
-\r
- /**\r
- * Node within which the Range ends \r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public Node getEndContainer()\r
- throws DOMException;\r
-\r
- /**\r
- * Offset within the ending node of the Range. \r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public int getEndOffset()\r
- throws DOMException;\r
-\r
- /**\r
- * TRUE if the Range is collapsed \r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public boolean getCollapsed()\r
- throws DOMException;\r
-\r
- /**\r
- * The deepest common ancestor container of the Range's two \r
- * boundary-points.\r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public Node getCommonAncestorContainer()\r
- throws DOMException;\r
-\r
- /**\r
- * Sets the attributes describing the start of the Range. \r
- * @param refNodeThe <code>refNode</code> value. This parameter must be \r
- * different from <code>null</code>.\r
- * @param offsetThe <code>startOffset</code> value. \r
- * @exception RangeException\r
- * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor \r
- * of <code>refNode</code> is an Entity, Notation, or DocumentType \r
- * node.\r
- * @exception DOMException\r
- * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater \r
- * than the number of child units in <code>refNode</code>. Child units \r
- * are 16-bit units if <code>refNode</code> is a type of CharacterData \r
- * node (e.g., a Text or Comment node) or a ProcessingInstruction \r
- * node. Child units are Nodes in all other cases.\r
- * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already \r
- * been invoked on this object.\r
- */\r
- public void setStart(Node refNode, \r
- int offset)\r
- throws RangeException, DOMException;\r
-\r
- /**\r
- * Sets the attributes describing the end of a Range.\r
- * @param refNodeThe <code>refNode</code> value. This parameter must be \r
- * different from <code>null</code>.\r
- * @param offsetThe <code>endOffset</code> value. \r
- * @exception RangeException\r
- * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor \r
- * of <code>refNode</code> is an Entity, Notation, or DocumentType \r
- * node.\r
- * @exception DOMException\r
- * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater \r
- * than the number of child units in <code>refNode</code>. Child units \r
- * are 16-bit units if <code>refNode</code> is a type of CharacterData \r
- * node (e.g., a Text or Comment node) or a ProcessingInstruction \r
- * node. Child units are Nodes in all other cases.\r
- * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already \r
- * been invoked on this object.\r
- */\r
- public void setEnd(Node refNode, \r
- int offset)\r
- throws RangeException, DOMException;\r
-\r
- /**\r
- * Sets the start position to be before a node\r
- * @param refNodeRange starts before <code>refNode</code> \r
- * @exception RangeException\r
- * INVALID_NODE_TYPE_ERR: Raised if the root container of \r
- * <code>refNode</code> is not an Attr, Document, or DocumentFragment \r
- * node or if <code>refNode</code> is a Document, DocumentFragment, \r
- * Attr, Entity, or Notation node.\r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public void setStartBefore(Node refNode)\r
- throws RangeException, DOMException;\r
-\r
- /**\r
- * Sets the start position to be after a node\r
- * @param refNodeRange starts after <code>refNode</code> \r
- * @exception RangeException\r
- * INVALID_NODE_TYPE_ERR: Raised if the root container of \r
- * <code>refNode</code> is not an Attr, Document, or DocumentFragment \r
- * node or if <code>refNode</code> is a Document, DocumentFragment, \r
- * Attr, Entity, or Notation node.\r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public void setStartAfter(Node refNode)\r
- throws RangeException, DOMException;\r
-\r
- /**\r
- * Sets the end position to be before a node. \r
- * @param refNodeRange ends before <code>refNode</code> \r
- * @exception RangeException\r
- * INVALID_NODE_TYPE_ERR: Raised if the root container of \r
- * <code>refNode</code> is not an Attr, Document, or DocumentFragment \r
- * node or if <code>refNode</code> is a Document, DocumentFragment, \r
- * Attr, Entity, or Notation node.\r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public void setEndBefore(Node refNode)\r
- throws RangeException, DOMException;\r
-\r
- /**\r
- * Sets the end of a Range to be after a node \r
- * @param refNodeRange ends after <code>refNode</code>. \r
- * @exception RangeException\r
- * INVALID_NODE_TYPE_ERR: Raised if the root container of \r
- * <code>refNode</code> is not an Attr, Document or DocumentFragment \r
- * node or if <code>refNode</code> is a Document, DocumentFragment, \r
- * Attr, Entity, or Notation node.\r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public void setEndAfter(Node refNode)\r
- throws RangeException, DOMException;\r
-\r
- /**\r
- * Collapse a Range onto one of its boundary-points \r
- * @param toStartIf TRUE, collapses the Range onto its start; if FALSE, \r
- * collapses it onto its end. \r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public void collapse(boolean toStart)\r
- throws DOMException;\r
-\r
- /**\r
- * Select a node and its contents \r
- * @param refNodeThe node to select. \r
- * @exception RangeException\r
- * INVALID_NODE_TYPE_ERR: Raised if an ancestor of <code>refNode</code> \r
- * is an Entity, Notation or DocumentType node or if \r
- * <code>refNode</code> is a Document, DocumentFragment, Attr, Entity, \r
- * or Notation node.\r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public void selectNode(Node refNode)\r
- throws RangeException, DOMException;\r
-\r
- /**\r
- * Select the contents within a node \r
- * @param refNodeNode to select from \r
- * @exception RangeException\r
- * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor \r
- * of <code>refNode</code> is an Entity, Notation or DocumentType node.\r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public void selectNodeContents(Node refNode)\r
- throws RangeException, DOMException;\r
-\r
- // CompareHow\r
- /**\r
- * Compare start boundary-point of <code>sourceRange</code> to start \r
- * boundary-point of Range on which <code>compareBoundaryPoints</code> \r
- * is invoked.\r
- */\r
- public static final short START_TO_START = 0;\r
- /**\r
- * Compare start boundary-point of <code>sourceRange</code> to end \r
- * boundary-point of Range on which <code>compareBoundaryPoints</code> \r
- * is invoked.\r
- */\r
- public static final short START_TO_END = 1;\r
- /**\r
- * Compare end boundary-point of <code>sourceRange</code> to end \r
- * boundary-point of Range on which <code>compareBoundaryPoints</code> \r
- * is invoked.\r
- */\r
- public static final short END_TO_END = 2;\r
- /**\r
- * Compare end boundary-point of <code>sourceRange</code> to start \r
- * boundary-point of Range on which <code>compareBoundaryPoints</code> \r
- * is invoked.\r
- */\r
- public static final short END_TO_START = 3;\r
-\r
- /**\r
- * Compare the boundary-points of two Ranges in a document.\r
- * @param howA code representing the type of comparison, as defined above.\r
- * @param sourceRangeThe <code>Range</code> on which this current \r
- * <code>Range</code> is compared to.\r
- * @return -1, 0 or 1 depending on whether the corresponding \r
- * boundary-point of the Range is respectively before, equal to, or \r
- * after the corresponding boundary-point of <code>sourceRange</code>. \r
- * @exception DOMException\r
- * WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same \r
- * Document or DocumentFragment.\r
- * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already \r
- * been invoked on this object.\r
- */\r
- public short compareBoundaryPoints(short how, \r
- Range sourceRange)\r
- throws DOMException;\r
-\r
- /**\r
- * Removes the contents of a Range from the containing document or \r
- * document fragment without returning a reference to the removed \r
- * content. \r
- * @exception DOMException\r
- * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of \r
- * the Range is read-only or any of the nodes that contain any of the \r
- * content of the Range are read-only.\r
- * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already \r
- * been invoked on this object.\r
- */\r
- public void deleteContents()\r
- throws DOMException;\r
-\r
- /**\r
- * Moves the contents of a Range from the containing document or document \r
- * fragment to a new DocumentFragment. \r
- * @return A DocumentFragment containing the extracted contents. \r
- * @exception DOMException\r
- * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of \r
- * the Range is read-only or any of the nodes which contain any of the \r
- * content of the Range are read-only.\r
- * <br>HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be \r
- * extracted into the new DocumentFragment.\r
- * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already \r
- * been invoked on this object.\r
- */\r
- public DocumentFragment extractContents()\r
- throws DOMException;\r
-\r
- /**\r
- * Duplicates the contents of a Range \r
- * @return A DocumentFragment that contains content equivalent to this \r
- * Range.\r
- * @exception DOMException\r
- * HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be \r
- * extracted into the new DocumentFragment.\r
- * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already \r
- * been invoked on this object.\r
- */\r
- public DocumentFragment cloneContents()\r
- throws DOMException;\r
-\r
- /**\r
- * Inserts a node into the Document or DocumentFragment at the start of \r
- * the Range. If the container is a Text node, this will be split at the \r
- * start of the Range (as if the Text node's splitText method was \r
- * performed at the insertion point) and the insertion will occur \r
- * between the two resulting Text nodes. Adjacent Text nodes will not be \r
- * automatically merged. If the node to be inserted is a \r
- * DocumentFragment node, the children will be inserted rather than the \r
- * DocumentFragment node itself.\r
- * @param newNodeThe node to insert at the start of the Range \r
- * @exception DOMException\r
- * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the \r
- * start of the Range is read-only.\r
- * <br>WRONG_DOCUMENT_ERR: Raised if <code>newNode</code> and the \r
- * container of the start of the Range were not created from the same \r
- * document.\r
- * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of \r
- * the Range is of a type that does not allow children of the type of \r
- * <code>newNode</code> or if <code>newNode</code> is an ancestor of \r
- * the container.\r
- * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already \r
- * been invoked on this object.\r
- * @exception RangeException\r
- * INVALID_NODE_TYPE_ERR: Raised if <code>newNode</code> is an Attr, \r
- * Entity, Notation, or Document node.\r
- */\r
- public void insertNode(Node newNode)\r
- throws DOMException, RangeException;\r
-\r
- /**\r
- * Reparents the contents of the Range to the given node and inserts the \r
- * node at the position of the start of the Range. \r
- * @param newParentThe node to surround the contents with. \r
- * @exception DOMException\r
- * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of \r
- * either boundary-point of the Range is read-only.\r
- * <br>WRONG_DOCUMENT_ERR: Raised if <code> newParent</code> and the \r
- * container of the start of the Range were not created from the same \r
- * document.\r
- * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of \r
- * the Range is of a type that does not allow children of the type of \r
- * <code>newParent</code> or if <code>newParent</code> is an ancestor \r
- * of the container or if <code>node</code> would end up with a child \r
- * node of a type not allowed by the type of <code>node</code>.\r
- * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already \r
- * been invoked on this object.\r
- * @exception RangeException\r
- * BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a \r
- * non-text node.\r
- * <br>INVALID_NODE_TYPE_ERR: Raised if <code> node</code> is an Attr, \r
- * Entity, DocumentType, Notation, Document, or DocumentFragment node.\r
- */\r
- public void surroundContents(Node newParent)\r
- throws DOMException, RangeException;\r
-\r
- /**\r
- * Produces a new Range whose boundary-points are equal to the \r
- * boundary-points of the Range. \r
- * @return The duplicated Range. \r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public Range cloneRange()\r
- throws DOMException;\r
-\r
- /**\r
- * Returns the contents of a Range as a string. This string contains only \r
- * the data characters, not any markup. \r
- * @return The contents of the Range.\r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public String toString()\r
- throws DOMException;\r
-\r
- /**\r
- * Called to indicate that the Range is no longer in use and that the \r
- * implementation may relinquish any resources associated with this \r
- * Range. Subsequent calls to any methods or attribute getters on this \r
- * Range will result in a <code>DOMException</code> being thrown with an \r
- * error code of <code>INVALID_STATE_ERR</code>.\r
- * @exception DOMException\r
- * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been \r
- * invoked on this object.\r
- */\r
- public void detach()\r
- throws DOMException;\r
-\r
-}\r