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. Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
22 * 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 9, 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 }