001/*
002 * Copyright (c) 2000 World Wide Web Consortium,
003 * (Massachusetts Institute of Technology, Institut National de
004 * Recherche en Informatique et en Automatique, Keio University). All
005 * Rights Reserved. This program is distributed under the W3C's Software
006 * Intellectual Property License. This program is distributed in the
007 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
008 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
009 * PURPOSE.
010 * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
011 */
012
013package org.w3c.dom.ranges;
014
015import org.w3c.dom.Node;
016import org.w3c.dom.DOMException;
017import org.w3c.dom.DocumentFragment;
018
019/**
020 * <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>.
021 * @since DOM Level 2
022 */
023public interface Range {
024    /**
025     * Node within which the Range begins 
026     * @exception DOMException
027     *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 
028     *   invoked on this object.
029     */
030    public Node getStartContainer()
031                       throws DOMException;
032
033    /**
034     * Offset within the starting node of the Range. 
035     * @exception DOMException
036     *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 
037     *   invoked on this object.
038     */
039    public int getStartOffset()
040                       throws DOMException;
041
042    /**
043     * Node within which the Range ends 
044     * @exception DOMException
045     *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 
046     *   invoked on this object.
047     */
048    public Node getEndContainer()
049                       throws DOMException;
050
051    /**
052     * Offset within the ending node of the Range. 
053     * @exception DOMException
054     *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 
055     *   invoked on this object.
056     */
057    public int getEndOffset()
058                       throws DOMException;
059
060    /**
061     * TRUE if the Range is collapsed 
062     * @exception DOMException
063     *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 
064     *   invoked on this object.
065     */
066    public boolean getCollapsed()
067                       throws DOMException;
068
069    /**
070     * The deepest common ancestor container of the Range's two 
071     * boundary-points.
072     * @exception DOMException
073     *   INVALID_STATE_ERR: Raised if <code>detach()</code> has already been 
074     *   invoked on this object.
075     */
076    public Node getCommonAncestorContainer()
077                       throws DOMException;
078
079    /**
080     * Sets the attributes describing the start of the Range. 
081     * @param refNode The <code>refNode</code> value. This parameter must be 
082     *   different from <code>null</code>.
083     * @param offset The <code>startOffset</code> value. 
084     * @exception RangeException
085     *   INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor 
086     *   of <code>refNode</code> is an Entity, Notation, or DocumentType 
087     *   node.
088     * @exception DOMException
089     *   INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater 
090     *   than the number of child units in <code>refNode</code>. Child units 
091     *   are 16-bit units if <code>refNode</code> is a type of CharacterData 
092     *   node (e.g., a Text or Comment node) or a ProcessingInstruction 
093     *   node. Child units are Nodes in all other cases.
094     *   <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already 
095     *   been invoked on this object.
096     *   <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created 
097     *   from a different document than the one that created this range.
098     */
099    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}