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
10
* See W3C License http://www.w3.org/Consortium/Legal/ for more details.
13
package org.w3c.dom.ranges;
15
import org.w3c.dom.Node;
16
import org.w3c.dom.DOMException;
17
import org.w3c.dom.DocumentFragment;
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>.
23
public interface Range {
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.
30
public Node getStartContainer()
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.
39
public int getStartOffset()
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.
48
public Node getEndContainer()
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.
57
public int getEndOffset()
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.
66
public boolean getCollapsed()
70
* The deepest common ancestor container of the Range's two
72
* @exception DOMException
73
* INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
74
* invoked on this object.
76
public Node getCommonAncestorContainer()
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
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.
99
public void setStart(Node refNode,
101
throws RangeException, DOMException;
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
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.
123
public void setEnd(Node refNode,
125
throws RangeException, DOMException;
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.
141
public void setStartBefore(Node refNode)
142
throws RangeException, DOMException;
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.
158
public void setStartAfter(Node refNode)
159
throws RangeException, DOMException;
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.
175
public void setEndBefore(Node refNode)
176
throws RangeException, DOMException;
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.
192
public void setEndAfter(Node refNode)
193
throws RangeException, DOMException;
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.
203
public void collapse(boolean toStart)
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,
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.
220
public void selectNode(Node refNode)
221
throws RangeException, DOMException;
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.
235
public void selectNodeContents(Node refNode)
236
throws RangeException, DOMException;
240
* Compare start boundary-point of <code>sourceRange</code> to start
241
* boundary-point of Range on which <code>compareBoundaryPoints</code>
244
public static final short START_TO_START = 0;
246
* Compare start boundary-point of <code>sourceRange</code> to end
247
* boundary-point of Range on which <code>compareBoundaryPoints</code>
250
public static final short START_TO_END = 1;
252
* Compare end boundary-point of <code>sourceRange</code> to end
253
* boundary-point of Range on which <code>compareBoundaryPoints</code>
256
public static final short END_TO_END = 2;
258
* Compare end boundary-point of <code>sourceRange</code> to start
259
* boundary-point of Range on which <code>compareBoundaryPoints</code>
262
public static final short END_TO_START = 3;
265
* Compare the boundary-points of two Ranges in a document.
266
* @param how A code representing the type of comparison, as defined
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.
279
public short compareBoundaryPoints(short how,
284
* Removes the contents of a Range from the containing document or
285
* document fragment without returning a reference to the removed
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.
294
public void deleteContents()
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.
310
public DocumentFragment extractContents()
314
* Duplicates the contents of a Range
315
* @return A DocumentFragment that contains content equivalent to this
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.
323
public DocumentFragment cloneContents()
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
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
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.
352
public void insertNode(Node newNode)
353
throws DOMException, RangeException;
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
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
375
* <br>INVALID_NODE_TYPE_ERR: Raised if <code> node</code> is an Attr,
376
* Entity, DocumentType, Notation, Document, or DocumentFragment node.
378
public void surroundContents(Node newParent)
379
throws DOMException, RangeException;
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.
389
public Range cloneRange()
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.
400
public String toString()
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.
added
removed
debian/dom2-bindings/org/w3c/dom/ranges/Range.java
