lib/classpath/external/w3c_dom/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.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 }