libjava/org/w3c/dom/ranges/Range.java

   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.DocumentFragment;
  17 import org.w3c.dom.DOMException;
  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 refNodeThe <code>refNode</code> value. This parameter must be
  82      *   different from <code>null</code>.
  83      * @param offsetThe <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      */
  97     public void setStart(Node refNode,
  98                          int offset)
  99                          throws RangeException, DOMException;
 100
 101     /**
 102      * Sets the attributes describing the end of a Range.
 103      * @param refNodeThe <code>refNode</code> value. This parameter must be
 104      *   different from <code>null</code>.
 105      * @param offsetThe <code>endOffset</code> value.
 106      * @exception RangeException
 107      *   INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
 108      *   of <code>refNode</code> is an Entity, Notation, or DocumentType
 109      *   node.
 110      * @exception DOMException
 111      *   INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater
 112      *   than the number of child units in <code>refNode</code>. Child units
 113      *   are 16-bit units if <code>refNode</code> is a type of CharacterData
 114      *   node (e.g., a Text or Comment node) or a ProcessingInstruction
 115      *   node. Child units are Nodes in all other cases.
 116      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 117      *   been invoked on this object.
 118      */
 119     public void setEnd(Node refNode,
 120                        int offset)
 121                        throws RangeException, DOMException;
 122
 123     /**
 124      * Sets the start position to be before a node
 125      * @param refNodeRange starts before <code>refNode</code>
 126      * @exception RangeException
 127      *   INVALID_NODE_TYPE_ERR: Raised if the root container of
 128      *   <code>refNode</code> is not an Attr, Document, or DocumentFragment
 129      *   node or if <code>refNode</code> is a Document, DocumentFragment,
 130      *   Attr, Entity, or Notation node.
 131      * @exception DOMException
 132      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 133      *   invoked on this object.
 134      */
 135     public void setStartBefore(Node refNode)
 136                                throws RangeException, DOMException;
 137
 138     /**
 139      * Sets the start position to be after a node
 140      * @param refNodeRange starts after <code>refNode</code>
 141      * @exception RangeException
 142      *   INVALID_NODE_TYPE_ERR: Raised if the root container of
 143      *   <code>refNode</code> is not an Attr, Document, or DocumentFragment
 144      *   node or if <code>refNode</code> is a Document, DocumentFragment,
 145      *   Attr, Entity, or Notation node.
 146      * @exception DOMException
 147      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 148      *   invoked on this object.
 149      */
 150     public void setStartAfter(Node refNode)
 151                               throws RangeException, DOMException;
 152
 153     /**
 154      * Sets the end position to be before a node.
 155      * @param refNodeRange ends before <code>refNode</code>
 156      * @exception RangeException
 157      *   INVALID_NODE_TYPE_ERR: Raised if the root container of
 158      *   <code>refNode</code> is not an Attr, Document, or DocumentFragment
 159      *   node or if <code>refNode</code> is a Document, DocumentFragment,
 160      *   Attr, Entity, or Notation node.
 161      * @exception DOMException
 162      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 163      *   invoked on this object.
 164      */
 165     public void setEndBefore(Node refNode)
 166                              throws RangeException, DOMException;
 167
 168     /**
 169      * Sets the end of a Range to be after a node
 170      * @param refNodeRange ends after <code>refNode</code>.
 171      * @exception RangeException
 172      *   INVALID_NODE_TYPE_ERR: Raised if the root container of
 173      *   <code>refNode</code> is not an Attr, Document or DocumentFragment
 174      *   node or if <code>refNode</code> is a Document, DocumentFragment,
 175      *   Attr, Entity, or Notation node.
 176      * @exception DOMException
 177      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 178      *   invoked on this object.
 179      */
 180     public void setEndAfter(Node refNode)
 181                             throws RangeException, DOMException;
 182
 183     /**
 184      * Collapse a Range onto one of its boundary-points
 185      * @param toStartIf TRUE, collapses the Range onto its start; if FALSE,
 186      *   collapses it onto its end.
 187      * @exception DOMException
 188      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 189      *   invoked on this object.
 190      */
 191     public void collapse(boolean toStart)
 192                          throws DOMException;
 193
 194     /**
 195      * Select a node and its contents
 196      * @param refNodeThe node to select.
 197      * @exception RangeException
 198      *   INVALID_NODE_TYPE_ERR: Raised if an ancestor of <code>refNode</code>
 199      *   is an Entity, Notation or DocumentType node or if
 200      *   <code>refNode</code> is a Document, DocumentFragment, Attr, Entity,
 201      *   or Notation node.
 202      * @exception DOMException
 203      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 204      *   invoked on this object.
 205      */
 206     public void selectNode(Node refNode)
 207                            throws RangeException, DOMException;
 208
 209     /**
 210      * Select the contents within a node
 211      * @param refNodeNode to select from
 212      * @exception RangeException
 213      *   INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
 214      *   of <code>refNode</code> is an Entity, Notation or DocumentType node.
 215      * @exception DOMException
 216      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 217      *   invoked on this object.
 218      */
 219     public void selectNodeContents(Node refNode)
 220                                    throws RangeException, DOMException;
 221
 222     // CompareHow
 223     /**
 224      * Compare start boundary-point of <code>sourceRange</code> to start
 225      * boundary-point of Range on which <code>compareBoundaryPoints</code>
 226      * is invoked.
 227      */
 228     public static final short START_TO_START            = 0;
 229     /**
 230      * Compare start boundary-point of <code>sourceRange</code> to end
 231      * boundary-point of Range on which <code>compareBoundaryPoints</code>
 232      * is invoked.
 233      */
 234     public static final short START_TO_END              = 1;
 235     /**
 236      * Compare end boundary-point of <code>sourceRange</code> to end
 237      * boundary-point of Range on which <code>compareBoundaryPoints</code>
 238      * is invoked.
 239      */
 240     public static final short END_TO_END                = 2;
 241     /**
 242      * Compare end boundary-point of <code>sourceRange</code> to start
 243      * boundary-point of Range on which <code>compareBoundaryPoints</code>
 244      * is invoked.
 245      */
 246     public static final short END_TO_START              = 3;
 247
 248     /**
 249      * Compare the boundary-points of two Ranges in a document.
 250      * @param howA code representing the type of comparison, as defined above.
 251      * @param sourceRangeThe <code>Range</code> on which this current
 252      *   <code>Range</code> is compared to.
 253      * @return  -1, 0 or 1 depending on whether the corresponding
 254      *   boundary-point of the Range is respectively before, equal to, or
 255      *   after the corresponding boundary-point of <code>sourceRange</code>.
 256      * @exception DOMException
 257      *   WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same
 258      *   Document or DocumentFragment.
 259      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 260      *   been invoked on this object.
 261      */
 262     public short compareBoundaryPoints(short how,
 263                                        Range sourceRange)
 264                                        throws DOMException;
 265
 266     /**
 267      * Removes the contents of a Range from the containing document or
 268      * document fragment without returning a reference to the removed
 269      * content.
 270      * @exception DOMException
 271      *   NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of
 272      *   the Range is read-only or any of the nodes that contain any of the
 273      *   content of the Range are read-only.
 274      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 275      *   been invoked on this object.
 276      */
 277     public void deleteContents()
 278                                throws DOMException;
 279
 280     /**
 281      * Moves the contents of a Range from the containing document or document
 282      * fragment to a new DocumentFragment.
 283      * @return A DocumentFragment containing the extracted contents.
 284      * @exception DOMException
 285      *   NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of
 286      *   the Range is read-only or any of the nodes which contain any of the
 287      *   content of the Range are read-only.
 288      *   <br>HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
 289      *   extracted into the new DocumentFragment.
 290      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 291      *   been invoked on this object.
 292      */
 293     public DocumentFragment extractContents()
 294                                             throws DOMException;
 295
 296     /**
 297      * Duplicates the contents of a Range
 298      * @return A DocumentFragment that contains content equivalent to this
 299      *   Range.
 300      * @exception DOMException
 301      *   HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
 302      *   extracted into the new DocumentFragment.
 303      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 304      *   been invoked on this object.
 305      */
 306     public DocumentFragment cloneContents()
 307                                           throws DOMException;
 308
 309     /**
 310      * Inserts a node into the Document or DocumentFragment at the start of
 311      * the Range. If the container is a Text node, this will be split at the
 312      * start of the Range (as if the Text node's splitText method was
 313      * performed at the insertion point) and the insertion will occur
 314      * between the two resulting Text nodes. Adjacent Text nodes will not be
 315      * automatically merged. If the node to be inserted is a
 316      * DocumentFragment node, the children will be inserted rather than the
 317      * DocumentFragment node itself.
 318      * @param newNodeThe node to insert at the start of the Range
 319      * @exception DOMException
 320      *   NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the
 321      *   start of the Range is read-only.
 322      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newNode</code> and the
 323      *   container of the start of the Range were not created from the same
 324      *   document.
 325      *   <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of
 326      *   the Range is of a type that does not allow children of the type of
 327      *   <code>newNode</code> or if <code>newNode</code> is an ancestor of
 328      *   the container.
 329      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 330      *   been invoked on this object.
 331      * @exception RangeException
 332      *   INVALID_NODE_TYPE_ERR: Raised if <code>newNode</code> is an Attr,
 333      *   Entity, Notation, or Document node.
 334      */
 335     public void insertNode(Node newNode)
 336                            throws DOMException, RangeException;
 337
 338     /**
 339      * Reparents the contents of the Range to the given node and inserts the
 340      * node at the position of the start of the Range.
 341      * @param newParentThe node to surround the contents with.
 342      * @exception DOMException
 343      *   NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of
 344      *   either boundary-point of the Range is read-only.
 345      *   <br>WRONG_DOCUMENT_ERR: Raised if <code> newParent</code> and the
 346      *   container of the start of the Range were not created from the same
 347      *   document.
 348      *   <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of
 349      *   the Range is of a type that does not allow children of the type of
 350      *   <code>newParent</code> or if <code>newParent</code> is an ancestor
 351      *   of the container or if <code>node</code> would end up with a child
 352      *   node of a type not allowed by the type of <code>node</code>.
 353      *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
 354      *   been invoked on this object.
 355      * @exception RangeException
 356      *   BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a
 357      *   non-text node.
 358      *   <br>INVALID_NODE_TYPE_ERR: Raised if <code> node</code> is an Attr,
 359      *   Entity, DocumentType, Notation, Document, or DocumentFragment node.
 360      */
 361     public void surroundContents(Node newParent)
 362                                  throws DOMException, RangeException;
 363
 364     /**
 365      * Produces a new Range whose boundary-points are equal to the
 366      * boundary-points of the Range.
 367      * @return The duplicated Range.
 368      * @exception DOMException
 369      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 370      *   invoked on this object.
 371      */
 372     public Range cloneRange()
 373                             throws DOMException;
 374
 375     /**
 376      * Returns the contents of a Range as a string. This string contains only
 377      * the data characters, not any markup.
 378      * @return The contents of the Range.
 379      * @exception DOMException
 380      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 381      *   invoked on this object.
 382      */
 383     public String toString()
 384                            throws DOMException;
 385
 386     /**
 387      * Called to indicate that the Range is no longer in use and that the
 388      * implementation may relinquish any resources associated with this
 389      * Range. Subsequent calls to any methods or attribute getters on this
 390      * Range will result in a <code>DOMException</code> being thrown with an
 391      * error code of <code>INVALID_STATE_ERR</code>.
 392      * @exception DOMException
 393      *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
 394      *   invoked on this object.
 395      */
 396     public void detach()
 397                        throws DOMException;
 398
 399 }