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    
013    package org.w3c.dom.ranges;
014    
015    import org.w3c.dom.Node;
016    import org.w3c.dom.DOMException;
017    import 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     */
023    public 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    }