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. package org.w3c.dom.ranges;
  13. import org.w3c.dom.Node;
  14. import org.w3c.dom.DOMException;
  15. import org.w3c.dom.DocumentFragment;
  16. /**
  17. * <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>.
  18. * @since DOM Level 2
  19. */
  20. public interface Range {
  21. /**
  22. * Node within which the Range begins
  23. * @exception DOMException
  24. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  25. * invoked on this object.
  26. */
  27. public Node getStartContainer()
  28. throws DOMException;
  29. /**
  30. * Offset within the starting node of the Range.
  31. * @exception DOMException
  32. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  33. * invoked on this object.
  34. */
  35. public int getStartOffset()
  36. throws DOMException;
  37. /**
  38. * Node within which the Range ends
  39. * @exception DOMException
  40. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  41. * invoked on this object.
  42. */
  43. public Node getEndContainer()
  44. throws DOMException;
  45. /**
  46. * Offset within the ending node of the Range.
  47. * @exception DOMException
  48. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  49. * invoked on this object.
  50. */
  51. public int getEndOffset()
  52. throws DOMException;
  53. /**
  54. * TRUE if the Range is collapsed
  55. * @exception DOMException
  56. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  57. * invoked on this object.
  58. */
  59. public boolean getCollapsed()
  60. throws DOMException;
  61. /**
  62. * The deepest common ancestor container of the Range's two
  63. * boundary-points.
  64. * @exception DOMException
  65. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  66. * invoked on this object.
  67. */
  68. public Node getCommonAncestorContainer()
  69. throws DOMException;
  70. /**
  71. * Sets the attributes describing the start of the Range.
  72. * @param refNode The <code>refNode</code> value. This parameter must be
  73. * different from <code>null</code>.
  74. * @param offset The <code>startOffset</code> value.
  75. * @exception RangeException
  76. * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
  77. * of <code>refNode</code> is an Entity, Notation, or DocumentType
  78. * node.
  79. * @exception DOMException
  80. * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater
  81. * than the number of child units in <code>refNode</code>. Child units
  82. * are 16-bit units if <code>refNode</code> is a type of CharacterData
  83. * node (e.g., a Text or Comment node) or a ProcessingInstruction
  84. * node. Child units are Nodes in all other cases.
  85. * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
  86. * been invoked on this object.
  87. * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
  88. * from a different document than the one that created this range.
  89. */
  90. public void setStart(Node refNode,
  91. int offset)
  92. throws RangeException, DOMException;
  93. /**
  94. * Sets the attributes describing the end of a Range.
  95. * @param refNode The <code>refNode</code> value. This parameter must be
  96. * different from <code>null</code>.
  97. * @param offset The <code>endOffset</code> value.
  98. * @exception RangeException
  99. * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
  100. * of <code>refNode</code> is an Entity, Notation, or DocumentType
  101. * node.
  102. * @exception DOMException
  103. * INDEX_SIZE_ERR: Raised if <code>offset</code> is negative or greater
  104. * than the number of child units in <code>refNode</code>. Child units
  105. * are 16-bit units if <code>refNode</code> is a type of CharacterData
  106. * node (e.g., a Text or Comment node) or a ProcessingInstruction
  107. * node. Child units are Nodes in all other cases.
  108. * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
  109. * been invoked on this object.
  110. * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
  111. * from a different document than the one that created this range.
  112. */
  113. public void setEnd(Node refNode,
  114. int offset)
  115. throws RangeException, DOMException;
  116. /**
  117. * Sets the start position to be before a node
  118. * @param refNode Range starts before <code>refNode</code>
  119. * @exception RangeException
  120. * INVALID_NODE_TYPE_ERR: Raised if the root container of
  121. * <code>refNode</code> is not an Attr, Document, or DocumentFragment
  122. * node or if <code>refNode</code> is a Document, DocumentFragment,
  123. * Attr, Entity, or Notation node.
  124. * @exception DOMException
  125. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  126. * invoked on this object.
  127. * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
  128. * from a different document than the one that created this range.
  129. */
  130. public void setStartBefore(Node refNode)
  131. throws RangeException, DOMException;
  132. /**
  133. * Sets the start position to be after a node
  134. * @param refNode Range starts after <code>refNode</code>
  135. * @exception RangeException
  136. * INVALID_NODE_TYPE_ERR: Raised if the root container of
  137. * <code>refNode</code> is not an Attr, Document, or DocumentFragment
  138. * node or if <code>refNode</code> is a Document, DocumentFragment,
  139. * Attr, Entity, or Notation node.
  140. * @exception DOMException
  141. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  142. * invoked on this object.
  143. * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
  144. * from a different document than the one that created this range.
  145. */
  146. public void setStartAfter(Node refNode)
  147. throws RangeException, DOMException;
  148. /**
  149. * Sets the end position to be before a node.
  150. * @param refNode Range ends before <code>refNode</code>
  151. * @exception RangeException
  152. * INVALID_NODE_TYPE_ERR: Raised if the root container of
  153. * <code>refNode</code> is not an Attr, Document, or DocumentFragment
  154. * node or if <code>refNode</code> is a Document, DocumentFragment,
  155. * Attr, Entity, or Notation node.
  156. * @exception DOMException
  157. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  158. * invoked on this object.
  159. * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
  160. * from a different document than the one that created this range.
  161. */
  162. public void setEndBefore(Node refNode)
  163. throws RangeException, DOMException;
  164. /**
  165. * Sets the end of a Range to be after a node
  166. * @param refNode Range ends after <code>refNode</code>.
  167. * @exception RangeException
  168. * INVALID_NODE_TYPE_ERR: Raised if the root container of
  169. * <code>refNode</code> is not an Attr, Document or DocumentFragment
  170. * node or if <code>refNode</code> is a Document, DocumentFragment,
  171. * Attr, Entity, or Notation node.
  172. * @exception DOMException
  173. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  174. * invoked on this object.
  175. * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
  176. * from a different document than the one that created this range.
  177. */
  178. public void setEndAfter(Node refNode)
  179. throws RangeException, DOMException;
  180. /**
  181. * Collapse a Range onto one of its boundary-points
  182. * @param toStart If TRUE, collapses the Range onto its start; if FALSE,
  183. * collapses it onto its end.
  184. * @exception DOMException
  185. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  186. * invoked on this object.
  187. */
  188. public void collapse(boolean toStart)
  189. throws DOMException;
  190. /**
  191. * Select a node and its contents
  192. * @param refNode The node to select.
  193. * @exception RangeException
  194. * INVALID_NODE_TYPE_ERR: Raised if an ancestor of <code>refNode</code>
  195. * is an Entity, Notation or DocumentType node or if
  196. * <code>refNode</code> is a Document, DocumentFragment, Attr, Entity,
  197. * 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 selectNode(Node refNode)
  205. throws RangeException, DOMException;
  206. /**
  207. * Select the contents within a node
  208. * @param refNode Node to select from
  209. * @exception RangeException
  210. * INVALID_NODE_TYPE_ERR: Raised if <code>refNode</code> or an ancestor
  211. * of <code>refNode</code> is an Entity, Notation or DocumentType node.
  212. * @exception DOMException
  213. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  214. * invoked on this object.
  215. * <br>WRONG_DOCUMENT_ERR: Raised if <code>refNode</code> was created
  216. * from a different document than the one that created this range.
  217. */
  218. public void selectNodeContents(Node refNode)
  219. throws RangeException, DOMException;
  220. // CompareHow
  221. /**
  222. * Compare start boundary-point of <code>sourceRange</code> to start
  223. * boundary-point of Range on which <code>compareBoundaryPoints</code>
  224. * is invoked.
  225. */
  226. public static final short START_TO_START = 0;
  227. /**
  228. * Compare start boundary-point of <code>sourceRange</code> to end
  229. * boundary-point of Range on which <code>compareBoundaryPoints</code>
  230. * is invoked.
  231. */
  232. public static final short START_TO_END = 1;
  233. /**
  234. * Compare end boundary-point of <code>sourceRange</code> to end
  235. * boundary-point of Range on which <code>compareBoundaryPoints</code>
  236. * is invoked.
  237. */
  238. public static final short END_TO_END = 2;
  239. /**
  240. * Compare end 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 END_TO_START = 3;
  245. /**
  246. * Compare the boundary-points of two Ranges in a document.
  247. * @param how A code representing the type of comparison, as defined
  248. * above.
  249. * @param sourceRange The <code>Range</code> on which this current
  250. * <code>Range</code> is compared to.
  251. * @return -1, 0 or 1 depending on whether the corresponding
  252. * boundary-point of the Range is respectively before, equal to, or
  253. * after the corresponding boundary-point of <code>sourceRange</code>.
  254. * @exception DOMException
  255. * WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same
  256. * Document or DocumentFragment.
  257. * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
  258. * been invoked on this object.
  259. */
  260. public short compareBoundaryPoints(short how,
  261. Range sourceRange)
  262. throws DOMException;
  263. /**
  264. * Removes the contents of a Range from the containing document or
  265. * document fragment without returning a reference to the removed
  266. * content.
  267. * @exception DOMException
  268. * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of
  269. * the Range is read-only or any of the nodes that contain any of the
  270. * content of the Range are read-only.
  271. * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
  272. * been invoked on this object.
  273. */
  274. public void deleteContents()
  275. throws DOMException;
  276. /**
  277. * Moves the contents of a Range from the containing document or document
  278. * fragment to a new DocumentFragment.
  279. * @return A DocumentFragment containing the extracted contents.
  280. * @exception DOMException
  281. * NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of
  282. * the Range is read-only or any of the nodes which contain any of the
  283. * content of the Range are read-only.
  284. * <br>HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
  285. * extracted into the new DocumentFragment.
  286. * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
  287. * been invoked on this object.
  288. */
  289. public DocumentFragment extractContents()
  290. throws DOMException;
  291. /**
  292. * Duplicates the contents of a Range
  293. * @return A DocumentFragment that contains content equivalent to this
  294. * Range.
  295. * @exception DOMException
  296. * HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be
  297. * extracted into the new DocumentFragment.
  298. * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
  299. * been invoked on this object.
  300. */
  301. public DocumentFragment cloneContents()
  302. throws DOMException;
  303. /**
  304. * Inserts a node into the Document or DocumentFragment at the start of
  305. * the Range. If the container is a Text node, this will be split at the
  306. * start of the Range (as if the Text node's splitText method was
  307. * performed at the insertion point) and the insertion will occur
  308. * between the two resulting Text nodes. Adjacent Text nodes will not be
  309. * automatically merged. If the node to be inserted is a
  310. * DocumentFragment node, the children will be inserted rather than the
  311. * DocumentFragment node itself.
  312. * @param newNode The node to insert at the start of the Range
  313. * @exception DOMException
  314. * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the
  315. * start of the Range is read-only.
  316. * <br>WRONG_DOCUMENT_ERR: Raised if <code>newNode</code> and the
  317. * container of the start of the Range were not created from the same
  318. * document.
  319. * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of
  320. * the Range is of a type that does not allow children of the type of
  321. * <code>newNode</code> or if <code>newNode</code> is an ancestor of
  322. * the container.
  323. * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
  324. * been invoked on this object.
  325. * @exception RangeException
  326. * INVALID_NODE_TYPE_ERR: Raised if <code>newNode</code> is an Attr,
  327. * Entity, Notation, or Document node.
  328. */
  329. public void insertNode(Node newNode)
  330. throws DOMException, RangeException;
  331. /**
  332. * Reparents the contents of the Range to the given node and inserts the
  333. * node at the position of the start of the Range.
  334. * @param newParent The node to surround the contents with.
  335. * @exception DOMException
  336. * NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of
  337. * either boundary-point of the Range is read-only.
  338. * <br>WRONG_DOCUMENT_ERR: Raised if <code> newParent</code> and the
  339. * container of the start of the Range were not created from the same
  340. * document.
  341. * <br>HIERARCHY_REQUEST_ERR: Raised if the container of the start of
  342. * the Range is of a type that does not allow children of the type of
  343. * <code>newParent</code> or if <code>newParent</code> is an ancestor
  344. * of the container or if <code>node</code> would end up with a child
  345. * node of a type not allowed by the type of <code>node</code>.
  346. * <br>INVALID_STATE_ERR: Raised if <code>detach()</code> has already
  347. * been invoked on this object.
  348. * @exception RangeException
  349. * BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a
  350. * non-text node.
  351. * <br>INVALID_NODE_TYPE_ERR: Raised if <code> node</code> is an Attr,
  352. * Entity, DocumentType, Notation, Document, or DocumentFragment node.
  353. */
  354. public void surroundContents(Node newParent)
  355. throws DOMException, RangeException;
  356. /**
  357. * Produces a new Range whose boundary-points are equal to the
  358. * boundary-points of the Range.
  359. * @return The duplicated Range.
  360. * @exception DOMException
  361. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  362. * invoked on this object.
  363. */
  364. public Range cloneRange()
  365. throws DOMException;
  366. /**
  367. * Returns the contents of a Range as a string. This string contains only
  368. * the data characters, not any markup.
  369. * @return The contents of the Range.
  370. * @exception DOMException
  371. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  372. * invoked on this object.
  373. */
  374. public String toString()
  375. throws DOMException;
  376. /**
  377. * Called to indicate that the Range is no longer in use and that the
  378. * implementation may relinquish any resources associated with this
  379. * Range. Subsequent calls to any methods or attribute getters on this
  380. * Range will result in a <code>DOMException</code> being thrown with an
  381. * error code of <code>INVALID_STATE_ERR</code>.
  382. * @exception DOMException
  383. * INVALID_STATE_ERR: Raised if <code>detach()</code> has already been
  384. * invoked on this object.
  385. */
  386. public void detach()
  387. throws DOMException;
  388. }