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() throws DOMException;
031:
032: /**
033: * Offset within the starting node of the Range.
034: * @exception DOMException
035: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
036: * invoked on this object.
037: */
038: public int getStartOffset() throws DOMException;
039:
040: /**
041: * Node within which the Range ends
042: * @exception DOMException
043: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
044: * invoked on this object.
045: */
046: public Node getEndContainer() throws DOMException;
047:
048: /**
049: * Offset within the ending node of the Range.
050: * @exception DOMException
051: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
052: * invoked on this object.
053: */
054: public int getEndOffset() throws DOMException;
055:
056: /**
057: * TRUE if the Range is collapsed
058: * @exception DOMException
059: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
060: * invoked on this object.
061: */
062: public boolean getCollapsed() throws DOMException;
063:
064: /**
065: * The deepest common ancestor container of the Range's two
066: * boundary-points.
067: * @exception DOMException
068: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
069: * invoked on this object.
070: */
071: public Node getCommonAncestorContainer() throws DOMException;
072:
073: /**
074: * Sets the attributes describing the start of the Range.
075: * @param refNode The <code>refNode</code> value. This parameter must be
076: * different from <code>null</code>.
077: * @param offset The <code>startOffset</code> value.
078: * @exception RangeException
079: * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
080: * of <code>refNode</code> is an Entity, Notation, or DocumentType
081: * node.
082: * @exception DOMException
083: * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater
084: * than the number of child units in <code>refNode</code>. Child units
085: * are 16-bit units if <code>refNode</code> is a type of CharacterData
086: * node (e.g., a Text or Comment node) or a ProcessingInstruction
087: * node. Child units are Nodes in all other cases.
088: * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
089: * been invoked on this object.
090: * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
091: * from a different document than the one that created this range.
092: */
093: public void setStart(Node refNode, int offset)
094: throws RangeException, DOMException;
095:
096: /**
097: * Sets the attributes describing the end of a Range.
098: * @param refNode The <code>refNode</code> value. This parameter must be
099: * different from <code>null</code>.
100: * @param offset The <code>endOffset</code> value.
101: * @exception RangeException
102: * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
103: * of <code>refNode</code> is an Entity, Notation, or DocumentType
104: * node.
105: * @exception DOMException
106: * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater
107: * than the number of child units in <code>refNode</code>. Child units
108: * are 16-bit units if <code>refNode</code> is a type of CharacterData
109: * node (e.g., a Text or Comment node) or a ProcessingInstruction
110: * node. Child units are Nodes in all other cases.
111: * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
112: * been invoked on this object.
113: * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
114: * from a different document than the one that created this range.
115: */
116: public void setEnd(Node refNode, int offset) throws RangeException,
117: DOMException;
118:
119: /**
120: * Sets the start position to be before a node
121: * @param refNode Range starts before <code>refNode</code>
122: * @exception RangeException
123: * INVALID_NODE_TYPE_ERR: Raised if the root container of
124: * <code>refNode</code> is not an Attr, Document, or DocumentFragment
125: * node or if <code>refNode</code> is a Document, DocumentFragment,
126: * Attr, Entity, or Notation node.
127: * @exception DOMException
128: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
129: * invoked on this object.
130: * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
131: * from a different document than the one that created this range.
132: */
133: public void setStartBefore(Node refNode) throws RangeException,
134: DOMException;
135:
136: /**
137: * Sets the start position to be after a node
138: * @param refNode Range starts after <code>refNode</code>
139: * @exception RangeException
140: * INVALID_NODE_TYPE_ERR: Raised if the root container of
141: * <code>refNode</code> is not an Attr, Document, or DocumentFragment
142: * node or if <code>refNode</code> is a Document, DocumentFragment,
143: * Attr, Entity, or Notation node.
144: * @exception DOMException
145: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
146: * invoked on this object.
147: * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
148: * from a different document than the one that created this range.
149: */
150: public void setStartAfter(Node refNode) throws RangeException,
151: DOMException;
152:
153: /**
154: * Sets the end position to be before a node.
155: * @param refNode Range ends before <code>refNode</code>
156: * @exception RangeException
157: * INVALID_NODE_TYPE_ERR: Raised if the root container of
158: * <code>refNode</code> is not an Attr, Document, or DocumentFragment
159: * node or if <code>refNode</code> is a Document, DocumentFragment,
160: * Attr, Entity, or Notation node.
161: * @exception DOMException
162: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
163: * invoked on this object.
164: * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
165: * from a different document than the one that created this range.
166: */
167: public void setEndBefore(Node refNode) throws RangeException,
168: DOMException;
169:
170: /**
171: * Sets the end of a Range to be after a node
172: * @param refNode Range ends after <code>refNode</code>.
173: * @exception RangeException
174: * INVALID_NODE_TYPE_ERR: Raised if the root container of
175: * <code>refNode</code> is not an Attr, Document or DocumentFragment
176: * node or if <code>refNode</code> is a Document, DocumentFragment,
177: * Attr, Entity, or Notation node.
178: * @exception DOMException
179: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
180: * invoked on this object.
181: * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
182: * from a different document than the one that created this range.
183: */
184: public void setEndAfter(Node refNode) throws RangeException,
185: DOMException;
186:
187: /**
188: * Collapse a Range onto one of its boundary-points
189: * @param toStart If TRUE, collapses the Range onto its start; if FALSE,
190: * collapses it onto its end.
191: * @exception DOMException
192: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
193: * invoked on this object.
194: */
195: public void collapse(boolean toStart) throws DOMException;
196:
197: /**
198: * Select a node and its contents
199: * @param refNode The node to select.
200: * @exception RangeException
201: * INVALID_NODE_TYPE_ERR: Raised if an ancestor of <code>refNode</code>
202: * is an Entity, Notation or DocumentType node or if
203: * <code>refNode</code> is a Document, DocumentFragment, Attr, Entity,
204: * or Notation node.
205: * @exception DOMException
206: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
207: * invoked on this object.
208: * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
209: * from a different document than the one that created this range.
210: */
211: public void selectNode(Node refNode) throws RangeException,
212: DOMException;
213:
214: /**
215: * Select the contents within a node
216: * @param refNode Node to select from
217: * @exception RangeException
218: * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
219: * of <code>refNode</code> is an Entity, Notation or DocumentType node.
220: * @exception DOMException
221: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
222: * invoked on this object.
223: * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
224: * from a different document than the one that created this range.
225: */
226: public void selectNodeContents(Node refNode) throws RangeException,
227: DOMException;
228:
229: // CompareHow
230: /**
231: * Compare start boundary-point of <code>sourceRange</code> to start
232: * boundary-point of Range on which <code>compareBoundaryPoints</code>
233: * is invoked.
234: */
235: public static final short START_TO_START = 0;
236: /**
237: * Compare start boundary-point of <code>sourceRange</code> to end
238: * boundary-point of Range on which <code>compareBoundaryPoints</code>
239: * is invoked.
240: */
241: public static final short START_TO_END = 1;
242: /**
243: * Compare end boundary-point of <code>sourceRange</code> to end
244: * boundary-point of Range on which <code>compareBoundaryPoints</code>
245: * is invoked.
246: */
247: public static final short END_TO_END = 2;
248: /**
249: * Compare end boundary-point of <code>sourceRange</code> to start
250: * boundary-point of Range on which <code>compareBoundaryPoints</code>
251: * is invoked.
252: */
253: public static final short END_TO_START = 3;
254:
255: /**
256: * Compare the boundary-points of two Ranges in a document.
257: * @param how A code representing the type of comparison, as defined
258: * above.
259: * @param sourceRange The <code>Range</code> on which this current
260: * <code>Range</code> is compared to.
261: * @return -1, 0 or 1 depending on whether the corresponding
262: * boundary-point of the Range is respectively before, equal to, or
263: * after the corresponding boundary-point of <code>sourceRange</code>.
264: * @exception DOMException
265: * WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same
266: * Document or DocumentFragment.
267: * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
268: * been invoked on this object.
269: */
270: public short compareBoundaryPoints(short how, Range sourceRange)
271: throws DOMException;
272:
273: /**
274: * Removes the contents of a Range from the containing document or
275: * document fragment without returning a reference to the removed
276: * content.
277: * @exception DOMException
278: * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of
279: * the Range is read-only or any of the nodes that contain any of the
280: * content of the Range are read-only.
281: * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
282: * been invoked on this object.
283: */
284: public void deleteContents() throws DOMException;
285:
286: /**
287: * Moves the contents of a Range from the containing document or document
288: * fragment to a new DocumentFragment.
289: * @return A DocumentFragment containing the extracted contents.
290: * @exception DOMException
291: * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of
292: * the Range is read-only or any of the nodes which contain any of the
293: * content of the Range are read-only.
294: * <br>HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
295: * extracted into the new DocumentFragment.
296: * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
297: * been invoked on this object.
298: */
299: public DocumentFragment extractContents() throws DOMException;
300:
301: /**
302: * Duplicates the contents of a Range
303: * @return A DocumentFragment that contains content equivalent to this
304: * Range.
305: * @exception DOMException
306: * HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
307: * extracted into the new DocumentFragment.
308: * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
309: * been invoked on this object.
310: */
311: public DocumentFragment cloneContents() throws DOMException;
312:
313: /**
314: * Inserts a node into the Document or DocumentFragment at the start of
315: * the Range. If the container is a Text node, this will be split at the
316: * start of the Range (as if the Text node's splitText method was
317: * performed at the insertion point) and the insertion will occur
318: * between the two resulting Text nodes. Adjacent Text nodes will not be
319: * automatically merged. If the node to be inserted is a
320: * DocumentFragment node, the children will be inserted rather than the
321: * DocumentFragment node itself.
322: * @param newNode The node to insert at the start of the Range
323: * @exception DOMException
324: * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the
325: * start of the Range is read-only.
326: * <br>WRONG_DOCUMENT_ERR: Raised if <code>newNode</code> and the
327: * container of the start of the Range were not created from the same
328: * document.
329: * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of
330: * the Range is of a type that does not allow children of the type of
331: * <code>newNode</code> or if <code>newNode</code> is an ancestor of
332: * the container.
333: * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
334: * been invoked on this object.
335: * @exception RangeException
336: * INVALID_NODE_TYPE_ERR: Raised if <code>newNode</code> is an Attr,
337: * Entity, Notation, or Document node.
338: */
339: public void insertNode(Node newNode) throws DOMException,
340: RangeException;
341:
342: /**
343: * Reparents the contents of the Range to the given node and inserts the
344: * node at the position of the start of the Range.
345: * @param newParent The node to surround the contents with.
346: * @exception DOMException
347: * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of
348: * either boundary-point of the Range is read-only.
349: * <br>WRONG_DOCUMENT_ERR: Raised if <code> newParent</code> and the
350: * container of the start of the Range were not created from the same
351: * document.
352: * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of
353: * the Range is of a type that does not allow children of the type of
354: * <code>newParent</code> or if <code>newParent</code> is an ancestor
355: * of the container or if <code>node</code> would end up with a child
356: * node of a type not allowed by the type of <code>node</code>.
357: * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
358: * been invoked on this object.
359: * @exception RangeException
360: * BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a
361: * non-text node.
362: * <br>INVALID_NODE_TYPE_ERR: Raised if <code> node</code> is an Attr,
363: * Entity, DocumentType, Notation, Document, or DocumentFragment node.
364: */
365: public void surroundContents(Node newParent) throws DOMException,
366: RangeException;
367:
368: /**
369: * Produces a new Range whose boundary-points are equal to the
370: * boundary-points of the Range.
371: * @return The duplicated Range.
372: * @exception DOMException
373: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
374: * invoked on this object.
375: */
376: public Range cloneRange() throws DOMException;
377:
378: /**
379: * Returns the contents of a Range as a string. This string contains only
380: * the data characters, not any markup.
381: * @return The contents of the Range.
382: * @exception DOMException
383: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
384: * invoked on this object.
385: */
386: public String toString() throws DOMException;
387:
388: /**
389: * Called to indicate that the Range is no longer in use and that the
390: * implementation may relinquish any resources associated with this
391: * Range. Subsequent calls to any methods or attribute getters on this
392: * Range will result in a <code>DOMException</code> being thrown with an
393: * error code of <code>INVALID_STATE_ERR</code>.
394: * @exception DOMException
395: * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
396: * invoked on this object.
397: */
398: public void detach() throws DOMException;
399:
400: }
|