Abcd efgh XY blah ijkl
Consider the insertion of the text "inserted text" at the following positions: 1. Before the 'X':Abcd efgh inserted textXY blah ijkl
2. After the 'X':Abcd efgh Xinserted textY blah ijkl
3. After the 'Y':Abcd efgh XYinserted text blah ijkl
4. After the 'h' in "Y blah":Abcd efgh XY blahinserted text ijkl
2.12.2. Deletions Any deletion from the document tree can be considered as a sequence of deleteContents() operations applied to a minimal set of disjoint Ranges. To specify how a Range is modified under deletions we need only consider what happens to a Range under a single deleteContents()operation of another Range. And, in fact, we need only consider what happens to a single boundary-point of the Range since both boundary-points are modified using the same algorithm. If a boundary-point of the original Range is within the content being deleted, then after the deletion it will be at the same position as the resulting boundary-point of the (now collapsed) Range used to delete the contents. If a boundary-point is after the content being deleted then it is not affected by the deletion unless its container is also the container of one of the boundary-points of the Range being deleted. If there is such a common container, then the index of the boundary-point is modified so that the boundary-point maintains its position relative to the content of the container. If a boundary-point is before the content being deleted then it is not affected by the deletion at all. Examples: In these examples, the Range on which deleteContents()is invoked is indicated by the underline. Example 1. Before:Abcd efgh The Range ijkl
After:Abcd Range ijkl
Example 2. Before:Abcd efgh The Range ijkl
After:Abcd ^kl
Example 3. Before:ABCD efgh The Range ijkl
After:ABCD ange ijkl
In this example, the container of the start boundary-point after the deletion is the Text node holding the string "ange". Example 4. Before:Abcd efgh The Range ijkl
After:Abcd he Range ijkl
Example 5. Before:Abcd efgh The Range ijkl
After:Abcd ^kl
2.13. Formal Description of the Range Interface To summarize, the complete, formal description of the Range interface is given below: Interface Range (introduced in DOM Level 2) IDL Definition // Introduced in DOM Level 2: interface Range { readonly attribute Node startContainer; // raises(DOMException) on retrieval readonly attribute long startOffset; // raises(DOMException) on retrieval readonly attribute Node endContainer; // raises(DOMException) on retrieval readonly attribute long endOffset; // raises(DOMException) on retrieval readonly attribute boolean collapsed; // raises(DOMException) on retrieval readonly attribute Node commonAncestorContainer; // raises(DOMException) on retrieval void setStart(in Node refNode, in long offset) raises(RangeException, DOMException); void setEnd(in Node refNode, in long offset) raises(RangeException, DOMException); void setStartBefore(in Node refNode) raises(RangeException, DOMException); void setStartAfter(in Node refNode) raises(RangeException, DOMException); void setEndBefore(in Node refNode) raises(RangeException, DOMException); void setEndAfter(in Node refNode) raises(RangeException, DOMException); void collapse(in boolean toStart) raises(DOMException); void selectNode(in Node refNode) raises(RangeException, DOMException); void selectNodeContents(in Node refNode) raises(RangeException, DOMException); // CompareHow const unsigned short START_TO_START = 0; const unsigned short START_TO_END = 1; const unsigned short END_TO_END = 2; const unsigned short END_TO_START = 3; short compareBoundaryPoints(in unsigned short how, in Range sourceRange) raises(DOMException); void deleteContents() raises(DOMException); DocumentFragment extractContents() raises(DOMException); DocumentFragment cloneContents() raises(DOMException); void insertNode(in Node newNode) raises(DOMException, RangeException); void surroundContents(in Node newParent) raises(DOMException, RangeException); Range cloneRange() raises(DOMException); DOMString toString() raises(DOMException); void detach() raises(DOMException); }; Definition group CompareHow Passed as a parameter to the compareBoundaryPoints method. Defined Constants END_TO_END Compare end boundary-point of sourceRange to end boundary-point of Range on which compareBoundaryPoints is invoked. END_TO_START Compare end boundary-point of sourceRange to start boundary-point of Range on which compareBoundaryPoints is invoked. START_TO_END Compare start boundary-point of sourceRange to end boundary-point of Range on which compareBoundaryPoints is invoked. START_TO_START Compare start boundary-point of sourceRange to start boundary-point of Range on which compareBoundaryPoints is invoked. Attributes collapsed of type boolean, readonly TRUE if the Range is collapsed Exceptions on retrieval DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. commonAncestorContainer of type Node, readonly The deepest common ancestor container of the Range's two boundary-points. Exceptions on retrieval DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. endContainer of type Node, readonly Node within which the Range ends Exceptions on retrieval DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. endOffset of type long, readonly Offset within the ending node of the Range. Exceptions on retrieval DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. startContainer of type Node, readonly Node within which the Range begins Exceptions on retrieval DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. startOffset of type long, readonly Offset within the starting node of the Range. Exceptions on retrieval DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. Methods cloneContents Duplicates the contents of a Range Return Value DocumentFragment A DocumentFragment that contains content equivalent to this Range. Exceptions DOMException HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be extracted into the new DocumentFragment. INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Parameters cloneRange Produces a new Range whose boundary-points are equal to the boundary-points of the Range. Return Value Range The duplicated Range. Exceptions DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Parameters collapse Collapse a Range onto one of its boundary-points Parameters toStart of type boolean If TRUE, collapses the Range onto its start; if FALSE, collapses it onto its end. Exceptions DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Return Value compareBoundaryPoints Compare the boundary-points of two Ranges in a document. Parameters how of type unsigned short A code representing the type of comparison, as defined above. sourceRange of type Range The Range on which this current Range is compared to. Return Value short -1, 0 or 1 depending on whether the corresponding boundary-point of the Range is respectively before, equal to, or after the corresponding boundary-point of sourceRange. Exceptions DOMException WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same Document or DocumentFragment. INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. deleteContents Removes the contents of a Range from the containing document or document fragment without returning a reference to the removed content. Exceptions DOMException NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of the Range is read-only or any of the nodes that contain any of the content of the Range are read-only. INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Parameters No Return Value detach Called to indicate that the Range is no longer in use and that the implementation may relinquish any resources associated with this Range. Subsequent calls to any methods or attribute getters on this Range will result in a DOMException being thrown with an error code of INVALID_STATE_ERR. Exceptions DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Parameters No Return Value extractContents Moves the contents of a Range from the containing document or document fragment to a new DocumentFragment. Return Value DocumentFragment A DocumentFragment containing the extracted contents. Exceptions DOMException NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of the Range is read-only or any of the nodes which contain any of the content of the Range are read-only. HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be extracted into the new DocumentFragment. INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Parameters insertNode Inserts a node into the Document or DocumentFragment at the start of the Range. If the container is a Text node, this will be split at the start of the Range (as if the Text node's splitText method was performed at the insertion point) and the insertion will occur between the two resulting Text nodes. Adjacent Text nodes will not be automatically merged. If the node to be inserted is a DocumentFragment node, the children will be inserted rather than the DocumentFragment node itself. Parameters newNode of type Node The node to insert at the start of the Range Exceptions DOMException NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the start of the Range is read-only. WRONG_DOCUMENT_ERR: Raised if newNode and the container of the start of the Range were not created from the same document. HIERARCHY_REQUEST_ERR: Raised if the container of the start of the Range is of a type that does not allow children of the type of newNode or if newNode is an ancestor of the container. INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. RangeException INVALID_NODE_TYPE_ERR: Raised if newNode is an Attr, Entity, Notation, or Document node. No Return Value selectNode Select a node and its contents Parameters refNode of type Node The node to select. Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if an ancestor of refNode is an Entity, Notation or DocumentType node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node. DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Return Value selectNodeContents Select the contents within a node Parameters refNode of type Node Node to select from Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor of refNode is an Entity, Notation or DocumentType node. DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Return Value setEnd Sets the attributes describing the end of a Range. Parameters refNode of type Node The refNode value. This parameter must be different from null. offset of type long The endOffset value. Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor of refNode is an Entity, Notation, or DocumentType node. DOMException INDEX_SIZE_ERR: Raised if offset is negative or greater than the number of child units in refNode. Child units are 16-bit units if refNode is a type of CharacterData node (e.g., a Text or Comment node) or a ProcessingInstruction node. Child units are Nodes in all other cases. INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Return Value setEndAfter Sets the end of a Range to be after a node Parameters refNode of type Node Range ends after refNode. Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if the root container of refNode is not an Attr, Document or DocumentFragment node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node. DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Return Value setEndBefore Sets the end position to be before a node. Parameters refNode of type Node Range ends before refNode Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if the root container of refNode is not an Attr, Document, or DocumentFragment node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node. DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Return Value setStart Sets the attributes describing the start of the Range. Parameters refNode of type Node The refNode value. This parameter must be different from null. offset of type long The startOffset value. Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor of refNode is an Entity, Notation, or DocumentType node. DOMException INDEX_SIZE_ERR: Raised if offset is negative or greater than the number of child units in refNode. Child units are 16-bit units if refNode is a type of CharacterData node (e.g., a Text or Comment node) or a ProcessingInstruction node. Child units are Nodes in all other cases. INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Return Value setStartAfter Sets the start position to be after a node Parameters refNode of type Node Range starts after refNode Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if the root container of refNode is not an Attr, Document, or DocumentFragment node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node. DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Return Value setStartBefore Sets the start position to be before a node Parameters refNode of type Node Range starts before refNode Exceptions RangeException INVALID_NODE_TYPE_ERR: Raised if the root container of refNode is not an Attr, Document, or DocumentFragment node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node. DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Return Value surroundContents Reparents the contents of the Range to the given node and inserts the node at the position of the start of the Range. Parameters newParent of type Node The node to surround the contents with. Exceptions DOMException NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of either boundary-point of the Range is read-only. WRONG_DOCUMENT_ERR: Raised if newParent and the container of the start of the Range were not created from the same document. HIERARCHY_REQUEST_ERR: Raised if the container of the start of the Range is of a type that does not allow children of the type of newParent or if newParent is an ancestor of the container or if node would end up with a child node of a type not allowed by the type of node. INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. RangeException BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a non-text node. INVALID_NODE_TYPE_ERR: Raised if node is an Attr, Entity, DocumentType, Notation, Document, or DocumentFragment node. No Return Value toString Returns the contents of a Range as a string. This string contains only the data characters, not any markup. Return Value DOMString The contents of the Range. Exceptions DOMException INVALID_STATE_ERR: Raised if detach() has already been invoked on this object. No Parameters Interface DocumentRange (introduced in DOM Level 2) IDL Definition // Introduced in DOM Level 2: interface DocumentRange { Range createRange(); }; Methods createRange This interface can be obtained from the object implementing the Document interface using binding-specific casting methods. Return Value Range The initial state of the Range returned from this method is such that both of its boundary-points are positioned at the beginning of the corresponding Document, before any content. The Range returned can only be used to select content associated with this Document, or with DocumentFragments and Attrs for which this Document is the ownerDocument. No Parameters No Exceptions Exception RangeException introduced in DOM Level 2 Range operations may throw a RangeException as specified in their method descriptions. IDL Definition // Introduced in DOM Level 2: exception RangeException { unsigned short code; }; // RangeExceptionCode const unsigned short BAD_BOUNDARYPOINTS_ERR = 1; const unsigned short INVALID_NODE_TYPE_ERR = 2; Definition group RangeExceptionCode An integer indicating the type of error generated. Defined Constants BAD_BOUNDARYPOINTS_ERR If the boundary-points of a Range do not meet specific requirements. INVALID_NODE_TYPE_ERR If the container of an boundary-point of a Range is being set to either a node of an invalid type or a node with an ancestor of an invalid type. 13 November, 2000 Appendix A: IDL Definitions This appendix contains the complete OMG IDL [OMGIDL] for the Level 2 Document Object Model Traversal and Range definitions. The definitions are divided into Traversal, and Range. The IDL files are also available as: http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113/idl.zip A.1: Document Object Model Traversal traversal.idl: // File: traversal.idl #ifndef _TRAVERSAL_IDL_ #define _TRAVERSAL_IDL_ #include "dom.idl" #pragma prefix "dom.w3c.org" module traversal { typedef dom::Node Node; interface NodeFilter; // Introduced in DOM Level 2: interface NodeIterator { readonly attribute Node root; readonly attribute unsigned long whatToShow; readonly attribute NodeFilter filter; readonly attribute boolean expandEntityReferences; Node nextNode() raises(dom::DOMException); Node previousNode() raises(dom::DOMException); void detach(); }; // Introduced in DOM Level 2: interface NodeFilter { // Constants returned by acceptNode const short FILTER_ACCEPT = 1; const short FILTER_REJECT = 2; const short FILTER_SKIP = 3; // Constants for whatToShow const unsigned long SHOW_ALL = 0xFFFFFFFF; const unsigned long SHOW_ELEMENT = 0x00000001; const unsigned long SHOW_ATTRIBUTE = 0x00000002; const unsigned long SHOW_TEXT = 0x00000004; const unsigned long SHOW_CDATA_SECTION = 0x00000008; const unsigned long SHOW_ENTITY_REFERENCE = 0x00000010; const unsigned long SHOW_ENTITY = 0x00000020; const unsigned long SHOW_PROCESSING_INSTRUCTION = 0x00000040; const unsigned long SHOW_COMMENT = 0x00000080; const unsigned long SHOW_DOCUMENT = 0x00000100; const unsigned long SHOW_DOCUMENT_TYPE = 0x00000200; const unsigned long SHOW_DOCUMENT_FRAGMENT = 0x00000400; const unsigned long SHOW_NOTATION = 0x00000800; short acceptNode(in Node n); }; // Introduced in DOM Level 2: interface TreeWalker { readonly attribute Node root; readonly attribute unsigned long whatToShow; readonly attribute NodeFilter filter; readonly attribute boolean expandEntityReferences; attribute Node currentNode; // raises(dom::DOMException) on setting Node parentNode(); Node firstChild(); Node lastChild(); Node previousSibling(); Node nextSibling(); Node previousNode(); Node nextNode(); }; // Introduced in DOM Level 2: interface DocumentTraversal { NodeIterator createNodeIterator(in Node root, in unsigned long whatToShow, in NodeFilter filter, in boolean entityReferenceExpansion) raises(dom::DOMException); TreeWalker createTreeWalker(in Node root, in unsigned long whatToShow, in NodeFilter filter, in boolean entityReferenceExpansion) raises(dom::DOMException); }; }; #endif // _TRAVERSAL_IDL_ A.2: Document Object Model Range ranges.idl: // File: ranges.idl #ifndef _RANGES_IDL_ #define _RANGES_IDL_ #include "dom.idl" #pragma prefix "dom.w3c.org" module ranges { typedef dom::Node Node; typedef dom::DocumentFragment DocumentFragment; typedef dom::DOMString DOMString; // Introduced in DOM Level 2: exception RangeException { unsigned short code; }; // RangeExceptionCode const unsigned short BAD_BOUNDARYPOINTS_ERR = 1; const unsigned short INVALID_NODE_TYPE_ERR = 2; // Introduced in DOM Level 2: interface Range { readonly attribute Node startContainer; // raises(dom::DOMException) on retrieval readonly attribute long startOffset; // raises(dom::DOMException) on retrieval readonly attribute Node endContainer; // raises(dom::DOMException) on retrieval readonly attribute long endOffset; // raises(dom::DOMException) on retrieval readonly attribute boolean collapsed; // raises(dom::DOMException) on retrieval readonly attribute Node commonAncestorContainer; // raises(dom::DOMException) on retrieval void setStart(in Node refNode, in long offset) raises(RangeException, dom::DOMException); void setEnd(in Node refNode, in long offset) raises(RangeException, dom::DOMException); void setStartBefore(in Node refNode) raises(RangeException, dom::DOMException); void setStartAfter(in Node refNode) raises(RangeException, dom::DOMException); void setEndBefore(in Node refNode) raises(RangeException, dom::DOMException); void setEndAfter(in Node refNode) raises(RangeException, dom::DOMException); void collapse(in boolean toStart) raises(dom::DOMException); void selectNode(in Node refNode) raises(RangeException, dom::DOMException); void selectNodeContents(in Node refNode) raises(RangeException, dom::DOMException); // CompareHow const unsigned short START_TO_START = 0; const unsigned short START_TO_END = 1; const unsigned short END_TO_END = 2; const unsigned short END_TO_START = 3; short compareBoundaryPoints(in unsigned short how, in Range sourceRange) raises(dom::DOMException); void deleteContents() raises(dom::DOMException); DocumentFragment extractContents() raises(dom::DOMException); DocumentFragment cloneContents() raises(dom::DOMException); void insertNode(in Node newNode) raises(dom::DOMException, RangeException); void surroundContents(in Node newParent) raises(dom::DOMException, RangeException); Range cloneRange() raises(dom::DOMException); DOMString toString() raises(dom::DOMException); void detach() raises(dom::DOMException); }; // Introduced in DOM Level 2: interface DocumentRange { Range createRange(); }; }; #endif // _RANGES_IDL_ 13 November, 2000 Appendix B: Java Language Binding This appendix contains the complete Java Language [Java] binding for the Level 2 Document Object Model Traversal and Range. The definitions are divided into Traversal, and Range. The Java files are also available as http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113/java-binding.zip B.1: Document Object Model Traversal org/w3c/dom/traversal/NodeIterator.java: package org.w3c.dom.traversal; import org.w3c.dom.Node; import org.w3c.dom.DOMException; public interface NodeIterator { public Node getRoot(); public int getWhatToShow(); public NodeFilter getFilter(); public boolean getExpandEntityReferences(); public Node nextNode() throws DOMException; public Node previousNode() throws DOMException; public void detach(); } org/w3c/dom/traversal/NodeFilter.java: package org.w3c.dom.traversal; import org.w3c.dom.Node; public interface NodeFilter { // Constants returned by acceptNode public static final short FILTER_ACCEPT = 1; public static final short FILTER_REJECT = 2; public static final short FILTER_SKIP = 3; // Constants for whatToShow public static final int SHOW_ALL = 0xFFFFFFFF; public static final int SHOW_ELEMENT = 0x00000001; public static final int SHOW_ATTRIBUTE = 0x00000002; public static final int SHOW_TEXT = 0x00000004; public static final int SHOW_CDATA_SECTION = 0x00000008; public static final int SHOW_ENTITY_REFERENCE = 0x00000010; public static final int SHOW_ENTITY = 0x00000020; public static final int SHOW_PROCESSING_INSTRUCTION = 0x00000040; public static final int SHOW_COMMENT = 0x00000080; public static final int SHOW_DOCUMENT = 0x00000100; public static final int SHOW_DOCUMENT_TYPE = 0x00000200; public static final int SHOW_DOCUMENT_FRAGMENT = 0x00000400; public static final int SHOW_NOTATION = 0x00000800; public short acceptNode(Node n); } org/w3c/dom/traversal/TreeWalker.java: package org.w3c.dom.traversal; import org.w3c.dom.Node; import org.w3c.dom.DOMException; public interface TreeWalker { public Node getRoot(); public int getWhatToShow(); public NodeFilter getFilter(); public boolean getExpandEntityReferences(); public Node getCurrentNode(); public void setCurrentNode(Node currentNode) throws DOMException; public Node parentNode(); public Node firstChild(); public Node lastChild(); public Node previousSibling(); public Node nextSibling(); public Node previousNode(); public Node nextNode(); } org/w3c/dom/traversal/DocumentTraversal.java: package org.w3c.dom.traversal; import org.w3c.dom.Node; import org.w3c.dom.DOMException; public interface DocumentTraversal { public NodeIterator createNodeIterator(Node root, int whatToShow, NodeFilter filter, boolean entityReferenceExpansion) throws DOMException; public TreeWalker createTreeWalker(Node root, int whatToShow, NodeFilter filter, boolean entityReferenceExpansion) throws DOMException; } B.2: Document Object Model Range org/w3c/dom/ranges/RangeException.java: package org.w3c.dom.ranges; public class RangeException extends RuntimeException { public RangeException(short code, String message) { super(message); this.code = code; } public short code; // RangeExceptionCode public static final short BAD_BOUNDARYPOINTS_ERR = 1; public static final short INVALID_NODE_TYPE_ERR = 2; } org/w3c/dom/ranges/Range.java: package org.w3c.dom.ranges; import org.w3c.dom.Node; import org.w3c.dom.DocumentFragment; import org.w3c.dom.DOMException; public interface Range { public Node getStartContainer() throws DOMException; public int getStartOffset() throws DOMException; public Node getEndContainer() throws DOMException; public int getEndOffset() throws DOMException; public boolean getCollapsed() throws DOMException; public Node getCommonAncestorContainer() throws DOMException; public void setStart(Node refNode, int offset) throws RangeException, DOMException; public void setEnd(Node refNode, int offset) throws RangeException, DOMException; public void setStartBefore(Node refNode) throws RangeException, DOMException; public void setStartAfter(Node refNode) throws RangeException, DOMException; public void setEndBefore(Node refNode) throws RangeException, DOMException; public void setEndAfter(Node refNode) throws RangeException, DOMException; public void collapse(boolean toStart) throws DOMException; public void selectNode(Node refNode) throws RangeException, DOMException; public void selectNodeContents(Node refNode) throws RangeException, DOMException; // CompareHow public static final short START_TO_START = 0; public static final short START_TO_END = 1; public static final short END_TO_END = 2; public static final short END_TO_START = 3; public short compareBoundaryPoints(short how, Range sourceRange) throws DOMException; public void deleteContents() throws DOMException; public DocumentFragment extractContents() throws DOMException; public DocumentFragment cloneContents() throws DOMException; public void insertNode(Node newNode) throws DOMException, RangeException; public void surroundContents(Node newParent) throws DOMException, RangeException; public Range cloneRange() throws DOMException; public String toString() throws DOMException; public void detach() throws DOMException; } org/w3c/dom/ranges/DocumentRange.java: package org.w3c.dom.ranges; public interface DocumentRange { public Range createRange(); } 13 November, 2000 Appendix C: ECMAScript Language Binding This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 2 Document Object Model Traversal and Range definitions. The definitions are divided into Traversal, and Range. Note: Exceptions handling is only supported by ECMAScript implementation conformant with the Standard ECMA-262 3rd. Edition ([ECMAScript]). C.1: Document Object Model Traversal Object NodeIterator The NodeIterator object has the following properties: root This read-only property is a Node object. whatToShow This read-only property is of type Number. filter This read-only property is a NodeFilter object. expandEntityReferences This read-only property is of type Boolean. The NodeIterator object has the following methods: nextNode() This method returns a Node object. This method can raise a DOMException object. previousNode() This method returns a Node object. This method can raise a DOMException object. detach() This method has no return value. Prototype Object NodeFilter The NodeFilter class has the following constants: NodeFilter.FILTER_ACCEPT This constant is of type short and its value is 1. NodeFilter.FILTER_REJECT This constant is of type short and its value is 2. NodeFilter.FILTER_SKIP This constant is of type short and its value is 3. NodeFilter.SHOW_ALL This constant is of type Number and its value is 0xFFFFFFFF. NodeFilter.SHOW_ELEMENT This constant is of type Number and its value is 0x00000001. NodeFilter.SHOW_ATTRIBUTE This constant is of type Number and its value is 0x00000002. NodeFilter.SHOW_TEXT This constant is of type Number and its value is 0x00000004. NodeFilter.SHOW_CDATA_SECTION This constant is of type Number and its value is 0x00000008. NodeFilter.SHOW_ENTITY_REFERENCE This constant is of type Number and its value is 0x00000010. NodeFilter.SHOW_ENTITY This constant is of type Number and its value is 0x00000020. NodeFilter.SHOW_PROCESSING_INSTRUCTION This constant is of type Number and its value is 0x00000040. NodeFilter.SHOW_COMMENT This constant is of type Number and its value is 0x00000080. NodeFilter.SHOW_DOCUMENT This constant is of type Number and its value is 0x00000100. NodeFilter.SHOW_DOCUMENT_TYPE This constant is of type Number and its value is 0x00000200. NodeFilter.SHOW_DOCUMENT_FRAGMENT This constant is of type Number and its value is 0x00000400. NodeFilter.SHOW_NOTATION This constant is of type Number and its value is 0x00000800. Object NodeFilter This is an ECMAScript function reference. This method returns a Number. The parameter is a Node object. Object TreeWalker The TreeWalker object has the following properties: root This read-only property is a Node object. whatToShow This read-only property is of type Number. filter This read-only property is a NodeFilter object. expandEntityReferences This read-only property is of type Boolean. currentNode This property is a Node object and can raise a DOMException object on setting. The TreeWalker object has the following methods: parentNode() This method returns a Node object. firstChild() This method returns a Node object. lastChild() This method returns a Node object. previousSibling() This method returns a Node object. nextSibling() This method returns a Node object. previousNode() This method returns a Node object. nextNode() This method returns a Node object. Object DocumentTraversal The DocumentTraversal object has the following methods: createNodeIterator(root, whatToShow, filter, entityReferenceExpansion) This method returns a NodeIterator object. The root parameter is a Node object. The whatToShow parameter is of type Number. The filter parameter is a NodeFilter object. The entityReferenceExpansion parameter is of type Boolean. This method can raise a DOMException object. createTreeWalker(root, whatToShow, filter, entityReferenceExpansion) This method returns a TreeWalker object. The root parameter is a Node object. The whatToShow parameter is of type Number. The filter parameter is a NodeFilter object. The entityReferenceExpansion parameter is of type Boolean. This method can raise a DOMException object. C.2: Document Object Model Range Prototype Object Range The Range class has the following constants: Range.START_TO_START This constant is of type Number and its value is 0. Range.START_TO_END This constant is of type Number and its value is 1. Range.END_TO_END This constant is of type Number and its value is 2. Range.END_TO_START This constant is of type Number and its value is 3. Object Range The Range object has the following properties: startContainer This read-only property is a Node object and can raise a DOMException object on retrieval. startOffset This read-only property is a long object and can raise a DOMException object on retrieval. endContainer This read-only property is a Node object and can raise a DOMException object on retrieval. endOffset This read-only property is a long object and can raise a DOMException object on retrieval. collapsed This read-only property is of type Boolean and can raise a DOMException object on retrieval. commonAncestorContainer This read-only property is a Node object and can raise a DOMException object on retrieval. The Range object has the following methods: setStart(refNode, offset) This method has no return value. The refNode parameter is a Node object. The offset parameter is a long object. This method can raise a RangeException object or a DOMException object. setEnd(refNode, offset) This method has no return value. The refNode parameter is a Node object. The offset parameter is a long object. This method can raise a RangeException object or a DOMException object. setStartBefore(refNode) This method has no return value. The refNode parameter is a Node object. This method can raise a RangeException object or a DOMException object. setStartAfter(refNode) This method has no return value. The refNode parameter is a Node object. This method can raise a RangeException object or a DOMException object. setEndBefore(refNode) This method has no return value. The refNode parameter is a Node object. This method can raise a RangeException object or a DOMException object. setEndAfter(refNode) This method has no return value. The refNode parameter is a Node object. This method can raise a RangeException object or a DOMException object. collapse(toStart) This method has no return value. The toStart parameter is of type Boolean. This method can raise a DOMException object. selectNode(refNode) This method has no return value. The refNode parameter is a Node object. This method can raise a RangeException object or a DOMException object. selectNodeContents(refNode) This method has no return value. The refNode parameter is a Node object. This method can raise a RangeException object or a DOMException object. compareBoundaryPoints(how, sourceRange) This method returns a short object. The how parameter is of type Number. The sourceRange parameter is a Range object. This method can raise a DOMException object. deleteContents() This method has no return value. This method can raise a DOMException object. extractContents() This method returns a DocumentFragment object. This method can raise a DOMException object. cloneContents() This method returns a DocumentFragment object. This method can raise a DOMException object. insertNode(newNode) This method has no return value. The newNode parameter is a Node object. This method can raise a DOMException object or a RangeException object. surroundContents(newParent) This method has no return value. The newParent parameter is a Node object. This method can raise a DOMException object or a RangeException object. cloneRange() This method returns a Range object. This method can raise a DOMException object. toString() This method returns a String. This method can raise a DOMException object. detach() This method has no return value. This method can raise a DOMException object. Object DocumentRange The DocumentRange object has the following methods: createRange() This method returns a Range object. Prototype Object RangeException The RangeException class has the following constants: RangeException.BAD_BOUNDARYPOINTS_ERR This constant is of type Number and its value is 1. RangeException.INVALID_NODE_TYPE_ERR This constant is of type Number and its value is 2. Object RangeException The RangeException object has the following properties: code This property is of type Number. 13 November, 2000 Appendix D: Acknowledgements Many people contributed to this specification, including members of the DOM Working Group and the DOM Interest Group. We especially thank the following: Lauren Wood (SoftQuad Software Inc., chair), Andrew Watson (Object Management Group), Andy Heninger (IBM), Arnaud Le Hors (W3C and IBM), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Singer (IBM), Don Park (invited), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C team contact), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home and Netscape), Rich Rollman (Microsoft), Rick Gessner (Netscape), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tom Pixley (Netscape), Vidur Apparao (Netscape), Vinod Anupam (Lucent). Thanks to all those who have helped to improve this specification by sending suggestions and corrections. D.1: Production Systems This specification was written in XML. The HTML, OMG IDL, Java and ECMA Script bindings were all produced automatically. Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts. For DOM Level 2, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application. Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification. 13 November, 2000 Glossary Editors Arnaud Le Hors, IBM Lauren Wood, SoftQuad Software Inc. Robert S. Sutor, IBM (for DOM Level 1) Several of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information. 16-bit unit The base unit of a DOMString. This indicates that indexing on a DOMString occurs in units of 16 bits. This must not be misunderstood to mean that a DOMString can store arbitrary 16-bit units. A DOMString is a character string encoded in UTF-16; this means that the restrictions of UTF-16 as well as the other relevant restrictions on character strings must be maintained. A single character, for example in the form of a numeric character reference, may correspond to one or two 16-bit units. For more information, see [Unicode] and [ISO/IEC 10646]. ancestor An ancestor node of any node A is any node above A in a tree model of a document, where "above" means "toward the root." child A child is an immediate descendant node of a node. deepest The deepest element is that element which is furthest from the root or document element in a tree model of the document. document order The term document order has the same meaning as depth first, pre-order traversal, which is equivalent to the order in which the start tags occur in the text representation of the document. descendant A descendant node of any node A is any node below A in a tree model of a document, where "above" means "toward the root." parent A parent is an immediate ancestor node of a node. sibling Two nodes are siblings if and only if they have the same parent node. tokenized The description given to various information items (for example, attribute values of various types, but not including the StringType CDATA) after having been processed by the XML processor. The process includes stripping leading and trailing white space, and replacing multiple space characters by one. See the definition of tokenized type. 13 November, 2000 References For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR. F.1: Normative references DOM Level 2 Core W3C (World Wide Web Consortium) Document Object Model Level 2 Core Specification, November 2000. Available at http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113 ECMAScript ECMA (European Computer Manufacturers Association) ECMAScript Language Specification. Available at http://www.ecma.ch/ecma1/STAND/ECMA-262.HTM ISO/IEC 10646 ISO (International Organization for Standardization). ISO/IEC 10646-1:2000 (E). Information technology - Universal Multiple-Octet Coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane. [Geneva]: International Organization for Standardization. Java Sun Microsystems Inc. The Java Language Specification, James Gosling, Bill Joy, and Guy Steele, September 1996. Available at http://java.sun.com/docs/books/jls OMGIDL OMG (Object Management Group) IDL (Interface Definition Language) defined in The Common Object Request Broker: Architecture and Specification, version 2.3.1, October 1999. Available from http://www.omg.org/ Unicode The Unicode Consortium. The Unicode Standard, Version 3.0., February 2000. Available at http://www.unicode.org/unicode/standard/versions/Unicode3.0.html. 13 November, 2000 Index 16-bit unit 1, 2, 3, 4, 5 acceptNode ancestor 1, 2, 3, 4 ancestor container 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 BAD_BOUNDARYPOINTS_ERR before/after/equal to boundary-point 1, 2, 3, 4, 5, 6, 7, 8, 9 child 1, 2, 3, 4 cloneContents cloneRange collapse collapsed 1, 2, 3, 4, commonAncestorContainer 5 container 1, 2, 3, 4, compareBoundaryPoints 5, 6, 7, 8, 9, 10, 11, context tree 1, 2, 3, 4, 5, 12 6, 7 createNodeIterator createRange createTreeWalker currentNode deepest 1, 2 deleteContents descendant 1, 2, 3, 4, 5 detach 1, 2 document order 1, 2 DocumentRange DocumentTraversal DOM Level 2 Core 1, 2, 3, 4 ECMAScript END_TO_END END_TO_START endContainer endOffset expandEntityReferences 1, 2 extractContents filter 1, 2 FILTER_ACCEPT FILTER_REJECT FILTER_SKIP firstChild insertNode INVALID_NODE_TYPE_ERR ISO/IEC 10646 1, 2 Java lastChild nextNode 1, 2 nextSibling NodeFilter NodeIterator offset 1, 2, 3, 4, 5, 6OMGIDL parent 1, 2, 3, 4, 5, 6parentNode partially selected 1, 2, 3, 4, 5, 6 previousNode 1, 2 previousSibling Range RangeException root 1, 2 root container 1, 2, 3, 4, 5 selected 1, 2, 3 selectNode selectNodeContents setEnd setEndAfter setEndBefore setStart setStartAfter setStartBefore SHOW_ALL SHOW_ATTRIBUTE SHOW_CDATA_SECTION SHOW_COMMENT SHOW_DOCUMENT SHOW_DOCUMENT_FRAGMENT SHOW_DOCUMENT_TYPE SHOW_ELEMENT SHOW_ENTITY SHOW_ENTITY_REFERENCE SHOW_NOTATION SHOW_PROCESSING_INSTRUCTION SHOW_TEXT sibling 1, 2, 3, 4, 5, START_TO_END 6 START_TO_START startContainer startOffset surroundContents tokenized toString TreeWalker Unicode 1, 2 whatToShow 1, 2