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.  Sun designates this

     7  * particular file as subject to the "Classpath" exception as provided

     8  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    21  * CA 95054 USA or visit www.sun.com if you need additional information or

    22  * have any 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 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      */

    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      */

    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      */

    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      */

    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      */

    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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   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      */

   442     public void detach()

   443                        throws DOMException;

   444 

   445 }