KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > w3c > dom > ranges > Range


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 JavaDoc;
16 import org.w3c.dom.DOMException JavaDoc;
17 import org.w3c.dom.DocumentFragment JavaDoc;
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 JavaDoc getStartContainer()
31                        throws DOMException JavaDoc;
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 JavaDoc;
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 JavaDoc getEndContainer()
49                        throws DOMException JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc getCommonAncestorContainer()
77                        throws DOMException JavaDoc;
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 JavaDoc refNode,
100                          int offset)
101                          throws RangeException, DOMException JavaDoc;
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 JavaDoc refNode,
124                        int offset)
125                        throws RangeException, DOMException JavaDoc;
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 JavaDoc refNode)
142                                throws RangeException, DOMException JavaDoc;
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 JavaDoc refNode)
159                               throws RangeException, DOMException JavaDoc;
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 JavaDoc refNode)
176                              throws RangeException, DOMException JavaDoc;
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 JavaDoc refNode)
193                             throws RangeException, DOMException JavaDoc;
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 JavaDoc;
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 JavaDoc refNode)
221                            throws RangeException, DOMException JavaDoc;
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 JavaDoc refNode)
236                                    throws RangeException, DOMException JavaDoc;
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 JavaDoc;
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 JavaDoc;
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 JavaDoc extractContents()
311                                             throws DOMException JavaDoc;
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 JavaDoc cloneContents()
324                                           throws DOMException JavaDoc;
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 JavaDoc newNode)
353                            throws DOMException JavaDoc, 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 JavaDoc newParent)
379                                  throws DOMException JavaDoc, 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 JavaDoc;
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 JavaDoc toString()
401                            throws DOMException JavaDoc;
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 JavaDoc;
415
416 }
417
Popular Tags