Document Object Model (DOM) Level 2 Traversal and Range Specification

Document Object Model (DOM) Level 2 Traversal andRange Specification
Version 1.0
W3C Recommendation 13 November, 2000
This version:
http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113(PostScript file , PDF file , plain text , ZIP file)
Latest version:
http://www.w3.org/TR/DOM-Level-2-Traversal-Range
Previous version:
http://www.w3.org/TR/2000/PR-DOM-Level-2-Traversal-Range-20000927
Editors:
Joe Kesselman, IBM
Jonathan Robie, Texcel Research and Software AG
Mike Champion, Arbortext and Software AG
Peter Sharpe, SoftQuad Software Inc.
Vidur Apparao, Netscape Communications Corp.
Lauren Wood, SoftQuad Software Inc., WG Chair
Copyright © 2000 W3C ® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document
use and software licensing rules apply.

Abstract
This specification defines the Document Object Model Level 2 Traversal and Range, platform- andlanguage-neutral interfaces that allow programs and scripts to dynamically traverse and identify a range ofcontent in a document. The Document Object Model Level 2 Traversal and Range build on the Document
Object Model Level 2 Core [DOM Level 2 Core].
The DOM Level 2 Traversal and Range specification is composed of two modules. The two modules
contain specialized interfaces dedicated to traversing the document structure and identifying andmanipulating a range in a document.

1

Status of this document

Status of this document
This section describes the status of this document at the time of its publication. Other documents may
supersede this document. The latest status of this document series is maintained at the W3C.
This document has been reviewed by W3C Members and other interested parties and has been endorsedby the Director as a W3C Recommendation. It is a stable document and may be used as reference materialor cited as a normative reference from another document. W3C’s role in making the Recommendation isto draw attention to the specification and to promote its widespread deployment. This enhances thefunctionality and interoperability of the Web.
This document has been produced as part of the W3C DOM Activity. The authors of this document are
the DOM Working Group members. Different modules of the Document Object Model have different
editors.
Please send general comments about this document to the public mailing list www-dom@w3.org. An
archive is available at http://lists.w3.org/Archives/Public/www-dom/.
The English version of this specification is the only normative version. Information about translations of
this document is available at http://www.w3.org/2000/11/DOM-Level-2-translations.
The list of known errors in this document is available at http://www.w3.org/2000/11/DOM-Level-2-errata
A list of current W3C Recommendations and other technical documents can be found at
http://www.w3.org/TR.

Table of contents
Expanded Table of Contents
Copyright Notice .
.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.3
.5

Chapter 1: Document Object Model Traversal
Chapter 2: Document Object Model Range .

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.
.

.9
31
.

Appendix A: IDL Definitions .
.
.
.
Appendix B: Java Language Binding.
.
Appendix C: ECMAScript Language Binding
Appendix D: Acknowledgements .
.
.
Glossary
.
.
.
.
.
.
.
.
References .
.
.
.
.
.
.
.
Index
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

.
.
.
.
.
.
.

55
.
59
.
65
.
71
.
73
.
75
.
77
.

2

Expanded Table of Contents

Expanded Table of Contents
Expanded Table of Contents .
.
.
.
.
Copyright Notice .
.
.
.
.
.
.
.
W3C Document Copyright Notice and License
W3C Software Copyright Notice and License

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.3
.5
.5
.6

Chapter 1: Document Object Model Traversal.
.
1.1. Overview
.
.
.
.
.
.
.
.
1.1.1. NodeIterators .
.
.
.
.
.
1.1.2. NodeFilters
.
.
.
.
.
.
1.1.3. TreeWalker
.
.
.
.
.
.
1.2. Formal Interface Definition.
.
.
.
Chapter 2: Document Object Model Range .
.
.
2.1. Introduction .
.
.
.
.
.
.
.
2.2. Definitions and Notation .
.
.
.
.
2.2.1. Position .
.
.
.
.
.
.
2.2.2. Selection and Partial Selection .
.
2.2.3. Notation .
.
.
.
.
.
.
2.3. Creating a Range
.
.
.
.
.
.
2.4. Changing a Range’s Position .
.
.
.
2.5. Comparing Range Boundary-Points.
.
2.6. Deleting Content with a Range.
.
.
2.7. Extracting Content
.
.
.
.
.
.
2.8. Cloning Content .
.
.
.
.
.
.
2.9. Inserting Content
.
.
.
.
.
.
2.10. Surrounding Content
.
.
.
.
.
2.11. Miscellaneous Members .
.
.
.
.
2.12. Range modification under document mutation
2.12.1. Insertions
.
.
.
.
.
.
2.12.2. Deletions .
.
.
.
.
.
.
2.13. Formal Description of the Range Interface .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.9
.9
10
.
13
.
16
.
19
.
31
.
31
.
31
.
31
.
34
.
34
.
34
.
35
.
36
.
37
.
37
.
38
.
38
.
39
.
39
.
40
.
40
.
41
.
42
.

Appendix A: IDL Definitions .
.
.
.
A.1. Document Object Model Traversal
A.2. Document Object Model Range.
Appendix B: Java Language Binding.
.
B.1. Document Object Model Traversal
B.2. Document Object Model Range.
Appendix C: ECMAScript Language Binding
C.1. Document Object Model Traversal
C.2. Document Object Model Range.
Appendix D: Acknowledgements .
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.

55
.
55
.
56
.
59
.
59
.
61
.
65
.
65
.
67
.
71
.

.
.
.
.
.
.
.
.
.
.

3

.
.
.
.
.
.
.
.
.
.

Expanded Table of Contents

D.1. Production Systems
Glossary.
.
.
.
References .
.
.
.
1. Normative references
Index
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

4

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

71
.
73
.
75
.
75
.
77
.

Copyright Notice

Copyright Notice
Copyright © 2000 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut
National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.
This document is published under the W3C Document Copyright Notice and License [p.5] . The bindings
within this document are published under the W3C Software Copyright Notice and License [p.6] . The
software license requires "Notice of any changes or modifications to the W3C files, including the datechanges were made." Consequently, modified versions of the DOM bindings must document that they do
not conform to the W3C standard; in the case of the IDL definitions, the pragma prefix can no longer be’w3c.org’; in the case of the Java Language binding, the package names can no longer be in the ’org.w3c’
package.

W3C Document Copyright Notice and License
Note: This section is a copy of the W3C Document Notice and License and could be found at
http://www.w3.org/Consortium/Legal/copyright-documents-19990405.
Copyright © 1994-2000 World Wide Web Consortium, (Massachusetts Institute of Technology,
Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights
Reserved.
http://www.w3.org/Consortium/Legal/
Public documents on the W3C site are provided by the copyright holders under the following license. The
software or Document Type Definitions (DTDs) associated with W3C specifications are governed by the
Software Notice. By using and/or copying this document, or the W3C document from which thisstatement is linked, you (the licensee) agree that you have read, understood, and will comply with thefollowing terms and conditions:
Permission to use, copy, and distribute the contents of this document, or the W3C document from which
this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted,
provided that you include the following on ALL copies of the document, or portions thereof, that you use:
1. A link or URL to the original W3C document.
2. The pre-existing copyright notice of the original author, or if it doesn’t exist, a notice of the form:"Copyright © [$date-of-document] World Wide Web Consortium, (Massachusetts Institute ofTechnology, Institut National de Recherche en Informatique et en Automatique, Keio University).
All Rights Reserved. http://www.w3.org/Consortium/Legal/" (Hypertext is preferred, but a textual
representation is permitted.)
3. If it exists, the STATUS of the W3C document.
When space permits, inclusion of the full text of this NOTICE should be provided. We request that
authorship attribution be provided in any software, documents, or other items or products that you create
pursuant to the implementation of the contents of this document, or any portion thereof.

5

W3C Software Copyright Notice and License

No right to create modifications or derivatives of W3C documents is granted pursuant to this license.
However, if additional requirements (documented in the Copyright FAQ) are satisfied, the right to create
modifications or derivatives is sometimes granted by the W3C to individuals complying with thoserequirements.
THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO
REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULARPURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE
SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTSWILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR
OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE
PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining tothis document or its contents without specific, written prior permission. Title to copyright in thisdocument will at all times remain with copyright holders.

W3C Software Copyright Notice and License
Note: This section is a copy of the W3C Software Copyright Notice and License and could be found at
http://www.w3.org/Consortium/Legal/copyright-software-19980720
Copyright © 1994-2000 World Wide Web Consortium, (Massachusetts Institute of Technology,
Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights
Reserved.
http://www.w3.org/Consortium/Legal/
This W3C work (including software, documents, or other related items) is being provided by the copyrightholders under the following license. By obtaining, using and/or copying this work, you (the licensee)
agree that you have read, understood, and will comply with the following terms and conditions:
Permission to use, copy, and modify this software and its documentation, with or without modification,
for any purpose and without fee or royalty is hereby granted, provided that you include the following on
ALL copies of the software and documentation or portions thereof, including modifications, that you
make:
1. The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
2. Any pre-existing intellectual property disclaimers. If none exist, then a notice of the following form:"Copyright © [$date-of-software] World Wide Web Consortium, (Massachusetts Institute ofTechnology, Institut National de Recherche en Informatique et en Automatique, Keio University).
All Rights Reserved. http://www.w3.org/Consortium/Legal/."6

W3C Software Copyright Notice and License

3. Notice of any changes or modifications to the W3C files, including the date changes were made. (Werecommend you provide URIs to the location from which the code is derived.)
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHTHOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED,INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR
ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATIONWILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR
OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR
DOCUMENTATION.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to
the software without specific, written prior permission. Title to copyright in this software and any
associated documentation will at all times remain with copyright holders.

7

W3C Software Copyright Notice and License

8

1. Document Object Model Traversal

1. Document Object Model Traversal
Editors
Joe Kesselman, IBM
Jonathan Robie, Software AG
Mike Champion, Software AG

1.1. Overview
This chapter describes the optional DOM Level 2 Traversal feature. Its TreeWalker [p.24] ,NodeIterator [p.19] , and NodeFilter [p.21] interfaces provide easy-to-use, robust, selective
traversal of a document’s contents.
The interfaces found within this section are not mandatory. A DOM application may use the
hasFeature(feature, version) method of the DOMImplementation interface withparameter values "Traversal" and "2.0" (respectively) to determine whether or not this module issupported by the implementation. In order to fully support this module, an implementation must also
support the "Core" feature defined defined in the DOM Level 2 Core specification [DOM Level 2 Core].
Please refer to additional information about conformance in the DOM Level 2 Core specification [DOM
Level 2 Core].
NodeIterators [p.19] and TreeWalkers [p.24] are two different ways of representing the nodes ofa document subtree and a position within the nodes they present. A NodeIterator [p.19] presents aflattened view of the subtree as an ordered sequence of nodes, presented in document order. Because thisview is presented without respect to hierarchy, iterators have methods to move forward and backward, but
not to move up and down. Conversely, a TreeWalker [p.24] maintains the hierarchical relationships ofthe subtree, allowing navigation of this hierarchy. In general, TreeWalkers are better for tasks in which
the structure of the document around selected nodes will be manipulated, while NodeIterators are
better for tasks that focus on the content of each selected node.
NodeIterators [p.19] and TreeWalkers [p.24] each present a view of a document subtree that may
not contain all nodes found in the subtree. In this specification, we refer to this as the logical view to
distinguish it from the physical view, which corresponds to the document subtree per se. When an iterator
or TreeWalker [p.24] is created, it may be associated with a NodeFilter [p.21] , which examines
each node and determines whether it should appear in the logical view. In addition, flags may be used to
specify which node types should occur in the logical view.
NodeIterators [p.19] and TreeWalkers [p.24] are dynamic - the logical view changes to reflectchanges made to the underlying document. However, they differ in how they respond to those changes.
NodeIterators [p.19] , which present the nodes sequentially, attempt to maintain their location
relative to a position in that sequence when the sequence’s contents change. TreeWalkers [p.24] ,which present the nodes as a filtered tree, maintain their location relative to their current node and remain
attached to that node if it is moved to a new context. We will discuss these behaviors in greater detailbelow.

9

1.1.1. NodeIterators

1.1.1. NodeIterators
A NodeIterator [p.19] allows the members of a list of nodes to be returned sequentially. In thecurrent DOM interfaces, this list will always consist of the nodes of a subtree, presented in document
order [p.73] . When an iterator is first created, calling its nextNode() method returns the first node in
the logical view of the subtree; in most cases, this is the root of the subtree. Each successive call advances
the NodeIterator through the list, returning the next node available in the logical view. When no
more nodes are visible, nextNode() returns null.
NodeIterators [p.19] are created using the createNodeIterator method found in theDocumentTraversal [p.27] interface. When a NodeIterator [p.19] is created, flags can be used
to determine which node types will be "visible" and which nodes will be "invisible" while traversing thetree; these flags can be combined using the OR operator. Nodes that are "invisible" are skipped over by theiterator as though they did not exist.
The following code creates an iterator, then calls a function to print the name of each element:
NodeIterator iter=((DocumentTraversal)document).createNodeIterator(root, NodeFilter.SHOW_ELEMENT, null);while (Node n = iter.nextNode())
printMe(n);1.1.1.1. Moving Forward and Backward
NodeIterators [p.19] present nodes as an ordered list, and move forward and backward within thislist. The iterator’s position is always either between two nodes, before the first node, or after the last node.
When an iterator is first created, the position is set before the first item. The following diagram shows thelist view that an iterator might provide for a particular subtree, with the position indicated by an asterisk’*’ :* A B C D E F G H I

Each call to nextNode() returns the next node and advances the position. For instance, if we start withthe above position, the first call to nextNode() returns "A" and advances the iterator:[A] * B C D E F G H I

The position of a NodeIterator [p.19] can best be described with respect to the last node returned,
which we will call the reference node. When an iterator is created, the first node is the reference node, andthe iterator is positioned before the reference node. In these diagrams, we use square brackets to indicate
the reference node.
A call to previousNode() returns the previous node and moves the position backward. For instance, if
we start with the NodeIterator [p.19] between "A" and "B", it would return "A" and move to theposition shown below:

101.1.1. NodeIterators* [A] B C D E F G H I

If nextNode() is called at the end of a list, or previousNode() is called at the beginning of a list, it
returns null and does not change the position of the iterator. When a NodeIterator [p.19] is firstcreated, the reference node is the first node:* [A] B C D E F G H I

1.1.1.2. Robustness
A NodeIterator [p.19] may be active while the data structure it navigates is being edited, so an
iterator must behave gracefully in the face of change. Additions and removals in the underlying data
structure do not invalidate a NodeIterator; in fact, a NodeIterator is never invalidated unless its
detach() method is invoked. To make this possible, the iterator uses the reference node to maintain its
position. The state of an iterator also depends on whether the iterator is positioned before or after thereference node.
If changes to the iterated list do not remove the reference node, they do not affect the state of the
NodeIterator [p.19] . For instance, the iterator’s state is not affected by inserting new nodes in thevicinity of the iterator or removing nodes other than the reference node. Suppose we start from thefollowing position:A B C [D] * E F G H I

Now let’s remove "E". The resulting state is:
A B C [D] * F G H I

If a new node is inserted, the NodeIterator [p.19] stays close to the reference node, so if a node isinserted between "D" and "F", it will occur between the iterator and "F":A B C [D] * X F G H I

Moving a node is equivalent to a removal followed by an insertion. If we move "I" to the position before"X" the result is:
A B C [D] * I X F G H

If the reference node is removed from the list being iterated over, a different node is selected as thereference node. If the reference node’s position is before that of the NodeIterator [p.19] , which isusually the case after nextNode() has been called, the nearest node before the iterator is chosen as the
new reference node. Suppose we remove the "D" node, starting from the following state:
A B C [D] * F G H I

The "C" node becomes the new reference node, since it is the nearest node to the NodeIterator [p.19]
that is before the iterator:

11

1.1.1. NodeIterators

A B [C] * F G H I

If the reference node is after the NodeIterator [p.19] , which is usually the case after
previousNode() has been called, the nearest node after the iterator is chosen as the new reference
node. Suppose we remove "E", starting from the following state:
A B C D * [E] F G H I

The "F" node becomes the new reference node, since it is the nearest node to the NodeIterator [p.19]
that is after the iterator:A B C D * [F] G H I

As noted above, moving a node is equivalent to a removal followed by an insertion. Suppose we wish tomove the "D" node to the end of the list, starting from the following state:
A B C [D] * F G H I C

The resulting state is as follows:
A B [C] * F G H I D

One special case arises when the reference node is the last node in the list and the reference node isremoved. Suppose we remove node "C", starting from the following state:A B * [C]

According to the rules we have given, the new reference node should be the nearest node after the
NodeIterator [p.19] , but there are no further nodes after "C". The same situation can arise whenpreviousNode() has just returned the first node in the list, which is then removed. Hence: If there isno node in the original direction of the reference node, the nearest node in the opposite direction is
selected as the reference node:
A [B] *

If the NodeIterator [p.19] is positioned within a block of nodes that is removed, the above rules
clearly indicate what is to be done. For instance, suppose "C" is the parent [p.73] node of "D", "E", and"F", and we remove "C", starting with the following state:
A B C [D] * E F G H I D

The resulting state is as follows:
A [B] * G H I DFinally, note that removing a NodeIterator [p.19] ’s root node from its parent [p.73] does not alter
the list being iterated over, and thus does not change the iterator’s state.

121.1.2. NodeFilters

1.1.1.3. Visibility of Nodes
The underlying data structure that is being iterated may contain nodes that are not part of the logical view,and therefore will not be returned by the NodeIterator [p.19] . If nodes that are to be excluded
because of the value of the whatToShow flag, nextNode() returns the next visible node, skipping
over the excluded "invisible" nodes. If a NodeFilter [p.21] is present, it is applied before returning anode; if the filter does not accept the node, the process is repeated until a node is accepted by the filter andis returned. If no visible nodes are encountered, a null is returned and the iterator is positioned at the endof the list. In this case, the reference node is the last node in the list, whether or not it is visible. The same
approach is taken, in the opposite direction, for previousNode().
In the following examples, we will use lowercase letters to represent nodes that are in the data structure,
but which are not in the logical view. For instance, consider the following list:
A [B] * c d E F G

A call to nextNode() returns E and advances to the following position:
A B c d [E] * F G

Nodes that are not visible may nevertheless be used as reference nodes if a reference node is removed.
Suppose node "E" is removed, started from the state given above. The resulting state is:
A B c [d] * F GSuppose a new node "X", which is visible, is inserted before "d". The resulting state is:
A B c X [d] * F G

Note that a call to previousNode() now returns node X. It is important not to skip over invisible
nodes when the reference node is removed, because there are cases, like the one just given above, where
the wrong results will be returned. When "E" was removed, if the new reference node had been "B" rather
than "d", calling previousNode() would not return "X".

1.1.2. NodeFilters
NodeFilters [p.21] allow the user to create objects that "filter out" nodes. Each filter contains auser-written function that looks at a node and determines whether or not it should be presented as part of
the traversal’s logical view of the document. To use a NodeFilter [p.21] , you create a
NodeIterator [p.19] or a TreeWalker [p.24] that uses the filter. The traversal engine applies thefilter to each node, and if the filter does not accept the node, traversal skips over the node as though it
were not present in the document. NodeFilters need not know how to navigate the structure that
contains the nodes on which they operate.
Filters will be consulted when a traversal operation is performed, or when a NodeIterator [p.19] ’sreference node is removed from the subtree being iterated over and it must select a new one. However, theexact timing of these filter calls may vary from one DOM implementation to another. For that reason,
NodeFilters [p.21] should not attempt to maintain state based on the history of past invocations; theresulting behavior may not be portable.

131.1.2. NodeFilters

Similarly, TreeWalkers [p.24] and NodeIterators [p.19] should behave as if they have nomemory of past filter results, and no anticipation of future results. If the conditions a NodeFilter[p.21] is examining have changed (e.g., an attribute which it tests has been added or removed) since thelast time the traversal logic examined this node, this change in visibility will be discovered only when thenext traversal operation is performed. For example: if the filtering for the current node changes fromFILTER_SHOW to FILTER_SKIP, a TreeWalker [p.24] will be able to navigate off that node in any
direction, but not back to it unless the filtering conditions change again. NodeFilters which change
during a traversal can be written, but their behavior may be confusing and they should be avoided whenpossible.

1.1.2.1. Using NodeFilters
A NodeFilter [p.21] contains one method named acceptNode(), which allows a NodeIterator[p.19] or TreeWalker [p.24] to pass a Node to a filter and ask whether it should be present in the
logical view. The acceptNode() function returns one of three values to state how the Node should betreated. If acceptNode() returns FILTER_ACCEPT, the Node will be present in the logical view; if it
returns FILTER_SKIP, the Node will not be present in the logical view, but the children of the Nodemay; if it returns FILTER_REJECT, neither the Node nor its descendants [p.73] will be present in the
logical view. Since iterators present nodes as an ordered list, without hierarchy, FILTER_REJECT andFILTER_SKIP are synonyms for NodeIterators, skipping only the single current node.
Consider a filter that accepts the named anchors in an HTML document. In HTML, an HREF can refer to
any A element that has a NAME attribute. Here is a NodeFilter [p.21] in Java that looks at a node anddetermines whether it is a named anchor:class NamedAnchorFilter implements NodeFilter{
short acceptNode(Node n) {if (n.getNodeType()==Node.ELEMENT_NODE) {Element e = (Element)n;if (! e.getNodeName().equals("A"))return FILTER_SKIP;
if (e.getAttributeNode("NAME") != null)
return FILTER_ACCEPT;}
return FILTER_SKIP;}}

If the above NodeFilter [p.21] were to be used only with NodeIterators [p.19] , it could haveused FILTER_REJECT wherever FILTER_SKIP is used, and the behavior would not change. For
TreeWalker [p.24] , though, FILTER_REJECT would reject the children of any element that is not a
named anchor, and since named anchors are always contained within other elements, this would havemeant that no named anchors would be found. FILTER_SKIP rejects the given node, but continues to
examine the children; therefore, the above filter will work with either a NodeIterator [p.19] or a
TreeWalker.

141.1.2. NodeFilters

To use this filter, the user would create an instance of the NodeFilter [p.21] and create a
NodeIterator [p.19] using it:
NamedAnchorFilter myFilter = new NamedAnchorFilter();
NodeIterator iter=((DocumentTraversal)document).createNodeIterator(node, NodeFilter.SHOW_ELEMENT, myFilter);

Note that the use of the SHOW_ELEMENT flag is not strictly necessary in this example, since our sample
NodeFilter [p.21] tests the nodeType. However, some implementations of the Traversal interfaces
may be able to improve whatToShow performance by taking advantage of knowledge of the document’s
structure, which makes the use of SHOW_ELEMENT worthwhile. Conversely, while we could remove thenodeType test from our filter, that would make it dependent upon whatToShow to distinguish between
Elements, Attr’s, and ProcessingInstructions.

1.1.2.2. NodeFilters and Exceptions
When writing a NodeFilter [p.21] , users should avoid writing code that can throw an exception.
However, because a DOM implementation can not prevent exceptions from being thrown, it is importantthat the behavior of filters that throw an exception be well-defined. A TreeWalker [p.24] or
NodeIterator [p.19] does not catch or alter an exception thrown by a filter, but lets it propagate up to
the user’s code. The following functions may invoke a NodeFilter, and may therefore propagate an
exception if one is thrown by a filter:
1. NodeIterator [p.19] .nextNode()
2. NodeIterator [p.19] .previousNode()
3. TreeWalker [p.24] .firstChild()
4. TreeWalker [p.24] .lastChild()
5. TreeWalker [p.24] .nextSibling()
6. TreeWalker [p.24] .previousSibling()
7. TreeWalker [p.24] .nextNode()
8. TreeWalker [p.24] .previousNode()
9. TreeWalker [p.24] .parentNode()

1.1.2.3. NodeFilters and Document Mutation
Well-designed NodeFilters [p.21] should not have to modify the underlying structure of the
document. But a DOM implementation can not prevent a user from writing filter code that does alter the
document structure. Traversal does not provide any special processing to handle this case. For instance, if
a NodeFilter [p.21] removes a node from a document, it can still accept the node, which means thatthe node may be returned by the NodeIterator [p.19] or TreeWalker [p.24] even though it is nolonger in the subtree being traversed. In general, this may lead to inconsistent, confusing results, so weencourage users to write NodeFilters that make no changes to document structures. Instead, do yourediting in the loop controlled by the traversal object.

15

1.1.3. TreeWalker

1.1.2.4. NodeFilters and whatToShow flags
NodeIterator [p.19] and TreeWalker [p.24] apply their whatToShow flags before applying
filters. If a node is skipped by the active whatToShow flags, a NodeFilter [p.21] will not be called toevaluate that node. Please note that this behavior is similar to that of FILTER_SKIP; children of that
node will be considered, and filters may be called to evaluate them. Also note that it will in fact be a"skip" even if the NodeFilter would have preferred to reject the entire subtree; if this would cause aproblem in your application, consider setting whatToShow to SHOW_ALL and performing thenodeType test inside your filter.

1.1.3. TreeWalker
The TreeWalker [p.24] interface provides many of the same benefits as the NodeIterator [p.19]
interface. The main difference between these two interfaces is that the TreeWalker presents atree-oriented view of the nodes in a subtree, rather than the iterator’s list-oriented view. In other words, aniterator allows you to move forward or back, but a TreeWalker allows you to also move to the parent[p.73] of a node, to one of its children, or to a sibling [p.73] .
Using a TreeWalker [p.24] is quite similar to navigation using the Node directly, and the navigation
methods for the two interfaces are analogous. For instance, here is a function that recursively walks over atree of nodes in document order, taking separate actions when first entering a node and after processing
any children:
processMe(Node n) {nodeStartActions(n);for (Node child=n.firstChild();
child != null;child=child.nextSibling()) {processMe(child);}
nodeEndActions(n);}Doing the same thing using a TreeWalker [p.24] is quite similar. There is one difference: sincenavigation on the TreeWalker changes the current position, the position at the end of the function haschanged. A read/write attribute named currentNode allows the current node for a TreeWalker to beboth queried and set. We will use this to ensure that the position of the TreeWalker is restored when
this function is completed:processMe(TreeWalker tw) {Node n = tw.getCurrentNode();nodeStartActions(tw);for (Node child=tw.firstChild();
child!=null;child=tw.nextSibling()) {processMe(tw);}tw.setCurrentNode(n);nodeEndActions(tw);}161.1.3. TreeWalker

The advantage of using a TreeWalker [p.24] instead of direct Node navigation is that the
TreeWalker allows the user to choose an appropriate view of the tree. Flags may be used to show or
hide Comments or ProcessingInstructions; entities may be expanded or shown as
EntityReference nodes. In addition, NodeFilters [p.21] may be used to present a custom viewof the tree. Suppose a program needs a view of a document that shows which tables occur in each chapter,
listed by chapter. In this view, only the chapter elements and the tables that they contain are seen. The firststep is to write an appropriate filter:class TablesInChapters implements NodeFilter {short acceptNode(Node n) {if (n.getNodeType()==Node.ELEMENT_NODE) {if (n.getNodeName().equals("CHAPTER"))return FILTER_ACCEPT;
if (n.getNodeName().equals("TABLE"))
return FILTER_ACCEPT;
if (n.getNodeName().equals("SECT1")|| n.getNodeName().equals("SECT2")|| n.getNodeName().equals("SECT3")|| n.getNodeName().equals("SECT4")|| n.getNodeName().equals("SECT5")|| n.getNodeName().equals("SECT6")|| n.getNodeName().equals("SECT7"))
return FILTER_SKIP;}
return FILTER_REJECT;}}

This filter assumes that TABLE elements are contained directly in CHAPTER or SECTn elements. If
another kind of element is encountered, it and its children are rejected. If a SECTn element is encountered,
it is skipped, but its children are explored to see if they contain any TABLE elements.
Now the program can create an instance of this NodeFilter [p.21] , create a TreeWalker [p.24] thatuses it, and pass this TreeWalker to our ProcessMe() function:
TablesInChapters tablesInChapters = new TablesInChapters();
TreeWalker tw =((DocumentTraversal)document).createTreeWalker(
root, NodeFilter.SHOW_ELEMENT, tablesInChapters);
processMe(tw);(Again, we’ve chosen to both test the nodeType in the filter’s logic and use SHOW_ELEMENT, for thereasons discussed in the earlier NodeIterator [p.19] example.)
Without making any changes to the above ProcessMe() function, it now processes only the CHAPTER
and TABLE elements. The programmer can write other filters or set other flags to choose different sets ofnodes; if functions use TreeWalker [p.24] to navigate, they will support any view of the document17

1.1.3. TreeWalker

defined with a TreeWalker.
Note that the structure of a TreeWalker [p.24] ’s filtered view of a document may differ significantly
from that of the document itself. For example, a TreeWalker with only SHOW_TEXT specified in its
whatToShow parameter would present all the Text nodes as if they were siblings [p.73] of each otheryet had no parent [p.73] .

1.1.3.1. Robustness
As with NodeIterators [p.19] , a TreeWalker [p.24] may be active while the data structure it
navigates is being edited, and must behave gracefully in the face of change. Additions and removals in theunderlying data structure do not invalidate a TreeWalker; in fact, a TreeWalker is never invalidated.
But a TreeWalker [p.24] ’s response to these changes is quite different from that of a NodeIterator[p.19] . While NodeIterators respond to editing by maintaining their position within the list that they
are iterating over, TreeWalkers will instead remain attached to their currentNode. All the
TreeWalker’s navigation methods operate in terms of the context of the currentNode at the timethey are invoked, no matter what has happened to, or around, that node since the last time the
TreeWalker was accessed. This remains true even if the currentNode is moved out of its original
subtree.
As an example, consider the following document fragment:...
<subtree><twRoot><currentNode/><anotherNode/></twRoot></subtree>...

Let’s say we have created a TreeWalker [p.24] whose root node is the <twRoot/> element and whose
currentNode is the <currentNode/> element. For this illustration, we will assume that all the nodes
shown above are accepted by the TreeWalker’s whatToShow and filter settings.
If we use removeChild() to remove the <currentNode/> element from its parent [p.73] , that element
remains the TreeWalker [p.24] ’s currentNode, even though it is no longer within the root node’s
subtree. We can still use the TreeWalker to navigate through any children that the orphaned
currentNode may have, but are no longer able to navigate outward from the currentNode since
there is no parent [p.73] available.
If we use insertBefore() or appendChild() to give the <currentNode/> a new parent [p.73] ,then TreeWalker [p.24] navigation will operate from the currentNode’s new location. For example,
if we inserted the <currentNode/> immediately after the <anotherNode/> element, the TreeWalker’s
previousSibling() operation would move it back to the <anotherNode/>, and callingparentNode() would move it up to the <twRoot/>.

18

1.2. Formal Interface Definition

If we instead insert the currentNode into the <subtree/> element, like so:...
<subtree><currentNode/><twRoot><anotherNode/></twRoot></subtree>...

we have moved the currentNode out from under the TreeWalker [p.24] ’s root node. This does
not invalidate the TreeWalker; it may still be used to navigate relative to the currentNode. Callingits parentNode() operation, for example, would move it to the <subtree/> element, even though that
too is outside the original root node. However, if the TreeWalker’s navigation should take it backinto the original root node’s subtree -- for example, if rather than calling parentNode() we called
nextNode(), moving the TreeWalker to the <twRoot/> element -- the root node will "recapture"
the TreeWalker, and prevent it from traversing back out.
This becomes a bit more complicated when filters are in use. Relocation of the currentNode -- or
explicit selection of a new currentNode, or changes in the conditions that the NodeFilter [p.21] isbasing its decisions on -- can result in a TreeWalker [p.24] having a currentNode which would nototherwise be visible in the filtered (logical) view of the document. This node can be thought of as a"transient member" of that view. When you ask the TreeWalker to navigate off this node the result will
be just as if it had been visible, but you may be unable to navigate back to it unless conditions change tomake it visible again.
In particular: If the currentNode becomes part of a subtree that would otherwise have been Rejectedby the filter, that entire subtree may be added as transient members of the logical view. You will be able tonavigate within that subtree (subject to all the usual filtering) until you move upward past the Rejected
ancestor [p.73] . The behavior is as if the Rejected node had only been Skipped (since we somehow
wound up inside its subtree) until we leave it; thereafter, standard filtering applies.

1.2. Formal Interface Definition
Interface NodeIterator (introduced in DOM Level 2)
Iterators are used to step through a set of nodes, e.g. the set of nodes in a NodeList, thedocument subtree governed by a particular Node, the results of a query, or any other set of nodes.
The set of nodes to be iterated is determined by the implementation of the NodeIterator. DOM
Level 2 specifies a single NodeIterator implementation for document-order traversal of adocument subtree. Instances of these iterators are created by calling DocumentTraversal [p.27].createNodeIterator().
IDL Definition191.2. Formal Interface Definition// Introduced in DOM Level 2:interface NodeIterator {readonly attribute Nodereadonly attribute unsigned longreadonly attribute NodeFilter
readonly attribute boolean
NodenextNode()root;
whatToShow;filter;expandEntityReferences;raises(DOMException);NodepreviousNode()void

detach();raises(DOMException);};

Attributes
expandEntityReferences of type boolean, readonly
The value of this flag determines whether the children of entity reference nodes are visible
to the iterator. If false, they and their descendants [p.73] will be rejected. Note that thisrejection takes precedence over whatToShow and the filter. Also note that this iscurrently the only situation where NodeIterators may reject a complete subtree rather
than skipping individual nodes.
To produce a view of the document that has entity references expanded and does not
expose the entity reference node itself, use the whatToShow flags to hide the entity
reference node and set expandEntityReferences to true when creating the iterator.
To produce a view of the document that has entity reference nodes but no entity expansion,
use the whatToShow flags to show the entity reference node and set
expandEntityReferences to false.
filter of type NodeFilter [p.21] , readonly
The NodeFilter [p.21] used to screen nodes.
root of type Node, readonly
The root node of the NodeIterator, as specified when it was created.
whatToShow of type unsigned long, readonlyThis attribute determines which node types are presented via the iterator. The available setof constants is defined in the NodeFilter [p.21] interface. Nodes not accepted by
whatToShow will be skipped, but their children may still be considered. Note that thisskip takes precedence over the filter, if any.
Methods
detachDetaches the NodeIterator from the set which it iterated over, releasing any
computational resources and placing the iterator in the INVALID state. After detach has
been invoked, calls to nextNode or previousNode will raise the exception
INVALID_STATE_ERR.
No Parameters
No Return ValueNo Exceptions
nextNode
Returns the next node in the set and advances the position of the iterator in the set. After a
NodeIterator is created, the first call to nextNode() returns the first node in the set.
Return Value

201.2. Formal Interface Definition

Node

The next Node in the set being iterated over, or null if there are no moremembers in that set.

Exceptions
DOMException

INVALID_STATE_ERR: Raised if this method is called after thedetach method was invoked.

No Parameters
previousNode
Returns the previous node in the set and moves the position of the NodeIterator
backwards in the set.
Return Value
Node

The previous Node in the set being iterated over, or null if there are no
more members in that set.

Exceptions
DOMException

INVALID_STATE_ERR: Raised if this method is called after thedetach method was invoked.

No Parameters
Interface NodeFilter (introduced in DOM Level 2)
Filters are objects that know how to "filter out" nodes. If a NodeIterator [p.19] or
TreeWalker [p.24] is given a NodeFilter, it applies the filter before it returns the next node. If
the filter says to accept the node, the traversal logic returns it; otherwise, traversal looks for the next
node and pretends that the node that was rejected was not there.
The DOM does not provide any filters. NodeFilter is just an interface that users can implement toprovide their own filters.
NodeFilters do not need to know how to traverse from node to node, nor do they need to know
anything about the data structure that is being traversed. This makes it very easy to write filters, since
the only thing they have to know how to do is evaluate a single node. One filter may be used with anumber of different kinds of traversals, encouraging code reuse.
IDL Definition// Introduced in DOM Level 2:interface NodeFilter {// Constants returned by acceptNode
const short
FILTER_ACCEPT
const short
FILTER_REJECT

21

= 1;
= 2;

1.2. Formal Interface Definition

const short

FILTER_SKIP// Constants for whatToShow
const unsigned long
SHOW_ALL
const unsigned long
SHOW_ELEMENT
const unsigned long
SHOW_ATTRIBUTE
const unsigned long
SHOW_TEXT
const unsigned long
SHOW_CDATA_SECTION
const unsigned long
SHOW_ENTITY_REFERENCE
const unsigned long
SHOW_ENTITY
const unsigned long
SHOW_PROCESSING_INSTRUCTION
const unsigned long
SHOW_COMMENT
const unsigned long
SHOW_DOCUMENT
const unsigned long
SHOW_DOCUMENT_TYPE
const unsigned long
SHOW_DOCUMENT_FRAGMENT
const unsigned long
SHOW_NOTATION
short

= 3;

= 0xFFFFFFFF;= 0x00000001;= 0x00000002;= 0x00000004;= 0x00000008;= 0x00000010;= 0x00000020;= 0x00000040;= 0x00000080;= 0x00000100;= 0x00000200;= 0x00000400;= 0x00000800;

acceptNode(in Node n);};

Definition group Constants returned by acceptNode
The following constants are returned by the acceptNode() method:
Defined Constants
FILTER_ACCEPT
Accept the node. Navigation methods defined for NodeIterator [p.19] or
TreeWalker [p.24] will return this node.
FILTER_REJECT
Reject the node. Navigation methods defined for NodeIterator [p.19] or
TreeWalker [p.24] will not return this node. For TreeWalker, the children of thisnode will also be rejected. NodeIterators treat this as a synonym for
FILTER_SKIP.
FILTER_SKIP
Skip this single node. Navigation methods defined for NodeIterator [p.19] or
TreeWalker [p.24] will not return this node. For both NodeIterator and
TreeWalker, the children of this node will still be considered.
Definition group Constants for whatToShow
These are the available values for the whatToShow parameter used in TreeWalkers [p.24]
and NodeIterators [p.19] . They are the same as the set of possible types for Node, andtheir values are derived by using a bit position corresponding to the value of nodeType for theequivalent node type. If a bit in whatToShow is set false, that will be taken as a request to skip
over this type of node; the behavior in that case is similar to that of FILTER_SKIP.
Note that if node types greater than 32 are ever introduced, they may not be individually testable
via whatToShow. If that need should arise, it can be handled by selecting SHOW_ALL together
with an appropriate NodeFilter.

221.2. Formal Interface Definition

Defined Constants
SHOW_ALLShow all Nodes.
SHOW_ATTRIBUTE
Show Attr nodes. This is meaningful only when creating an iterator or tree-walker
with an attribute node as its root; in this case, it means that the attribute node willappear in the first position of the iteration or traversal. Since attributes are neverchildren of other nodes, they do not appear when traversing over the document tree.
SHOW_CDATA_SECTIONShow CDATASection nodes.
SHOW_COMMENTShow Comment nodes.
SHOW_DOCUMENT
Show Document nodes.
SHOW_DOCUMENT_FRAGMENT
Show DocumentFragment nodes.
SHOW_DOCUMENT_TYPEShow DocumentType nodes.
SHOW_ELEMENTShow Element nodes.
SHOW_ENTITYShow Entity nodes. This is meaningful only when creating an iterator ortree-walker with an Entity node as its root; in this case, it means that the Entity
node will appear in the first position of the traversal. Since entities are not part of the
document tree, they do not appear when traversing over the document tree.
SHOW_ENTITY_REFERENCE
Show EntityReference nodes.
SHOW_NOTATIONShow Notation nodes. This is meaningful only when creating an iterator ortree-walker with a Notation node as its root; in this case, it means that the
Notation node will appear in the first position of the traversal. Since notations are
not part of the document tree, they do not appear when traversing over the documenttree.
SHOW_PROCESSING_INSTRUCTIONShow ProcessingInstruction nodes.
SHOW_TEXTShow Text nodes.
Methods
acceptNode
Test whether a specified node is visible in the logical view of a TreeWalker [p.24] or
NodeIterator [p.19] . This function will be called by the implementation of
TreeWalker and NodeIterator; it is not normally called directly from user code.
(Though you could do so if you wanted to use the same filter to guide your own application
logic.)
Parameters231.2. Formal Interface Definitionn of type Node
The node to check to see if it passes the filter or not.
Return Value
shorta constant to determine whether the node is accepted, rejected, or skipped, as
defined above [p.22] .

No Exceptions
Interface TreeWalker (introduced in DOM Level 2)
TreeWalker objects are used to navigate a document tree or subtree using the view of the
document defined by their whatToShow flags and filter (if any). Any function which performs
navigation using a TreeWalker will automatically support any view defined by a TreeWalker.
Omitting nodes from the logical view of a subtree can result in a structure that is substantiallydifferent from the same subtree in the complete, unfiltered document. Nodes that are siblings [p.73]
in the TreeWalker view may be children of different, widely separated nodes in the original view.
For instance, consider a NodeFilter [p.21] that skips all nodes except for Text nodes and the root
node of a document. In the logical view that results, all text nodes will be siblings [p.73] and appear
as direct children of the root node, no matter how deeply nested the structure of the original
document.
IDL Definition// Introduced in DOM Level 2:interface TreeWalker {readonly attribute Nodereadonly attribute unsigned longreadonly attribute NodeFilter
readonly attribute boolean
attribute Node

Node
Node
Node
Node
Node
Node
Node

root;
whatToShow;filter;expandEntityReferences;currentNode;// raises(DOMException) on setting

parentNode();firstChild();
lastChild();
previousSibling();
nextSibling();previousNode();nextNode();};Attributes
currentNode of type Node
The node at which the TreeWalker is currently positioned.
Alterations to the DOM tree may cause the current node to no longer be accepted by the
TreeWalker’s associated filter. currentNode may also be explicitly set to any node,
whether or not it is within the subtree specified by the root node or would be accepted by
the filter and whatToShow flags. Further traversal occurs relative to currentNodeeven if it is not part of the current view, by applying the filters in the requested direction; if24

1.2. Formal Interface Definition

no traversal is possible, currentNode is not changed.
Exceptions on setting
DOMException

NOT_SUPPORTED_ERR: Raised if an attempt is made to set
currentNode to null.

expandEntityReferences of type boolean, readonly
The value of this flag determines whether the children of entity reference nodes are visible
to the TreeWalker. If false, they and their descendants [p.73] will be rejected. Note that
this rejection takes precedence over whatToShow and the filter, if any.
To produce a view of the document that has entity references expanded and does not
expose the entity reference node itself, use the whatToShow flags to hide the entity
reference node and set expandEntityReferences to true when creating the
TreeWalker. To produce a view of the document that has entity reference nodes but noentity expansion, use the whatToShow flags to show the entity reference node and set
expandEntityReferences to false.
filter of type NodeFilter [p.21] , readonly
The filter used to screen nodes.
root of type Node, readonly
The root node of the TreeWalker, as specified when it was created.
whatToShow of type unsigned long, readonlyThis attribute determines which node types are presented via the TreeWalker. The
available set of constants is defined in the NodeFilter [p.21] interface. Nodes not
accepted by whatToShow will be skipped, but their children may still be considered. Notethat this skip takes precedence over the filter, if any.
Methods
firstChild
Moves the TreeWalker to the first visible child [p.73] of the current node, and returns
the new node. If the current node has no visible children, returns null, and retains thecurrent node.
Return Value
Node

The new node, or null if the current node has no visible children in the
TreeWalker’s logical view.

No Parameters
No Exceptions
lastChildMoves the TreeWalker to the last visible child [p.73] of the current node, and returns the
new node. If the current node has no visible children, returns null, and retains the current
node.
Return Value
Node

The new node, or null if the current node has no children in the
TreeWalker’s logical view.

25

1.2. Formal Interface Definition

No Parameters
No Exceptions
nextNode
Moves the TreeWalker to the next visible node in document order relative to the current
node, and returns the new node. If the current node has no next node, or if the search for
nextNode attempts to step upward from the TreeWalker’s root node, returns null,and retains the current node.
Return Value
Node

The new node, or null if the current node has no next node in the
TreeWalker’s logical view.

No Parameters
No Exceptions
nextSibling
Moves the TreeWalker to the next sibling [p.73] of the current node, and returns the
new node. If the current node has no visible next sibling [p.73] , returns null, and retains
the current node.
Return Value
Node

The new node, or null if the current node has no next sibling [p.73] . in the
TreeWalker’s logical view.

No Parameters
No Exceptions
parentNode
Moves to and returns the closest visible ancestor [p.73] node of the current node. If thesearch for parentNode attempts to step upward from the TreeWalker’s root node,or if it fails to find a visible ancestor [p.73] node, this method retains the current position
and returns null.
Return Value
Node

The new parent [p.73] node, or null if the current node has no parent in the
TreeWalker’s logical view.

No Parameters
No Exceptions
previousNode
Moves the TreeWalker to the previous visible node in document order relative to thecurrent node, and returns the new node. If the current node has no previous node, or if thesearch for previousNode attempts to step upward from the TreeWalker’s root
node, returns null, and retains the current node.
Return Value

26

1.2. Formal Interface Definition

Node

The new node, or null if the current node has no previous node in the
TreeWalker’s logical view.

No Parameters
No Exceptions
previousSibling
Moves the TreeWalker to the previous sibling [p.73] of the current node, and returns the
new node. If the current node has no visible previous sibling [p.73] , returns null, andretains the current node.
Return Value
Node

The new node, or null if the current node has no previous sibling [p.73] . in
the TreeWalker’s logical view.

No Parameters
No Exceptions
Interface DocumentTraversal (introduced in DOM Level 2)DocumentTraversal contains methods that create iterators and tree-walkers to traverse a nodeand its children in document order (depth first, pre-order traversal, which is equivalent to the order inwhich the start tags occur in the text representation of the document). In DOMs which support theTraversal feature, DocumentTraversal will be implemented by the same objects that implement
the Document interface.
IDL Definition// Introduced in DOM Level 2:interface DocumentTraversal {NodeIterator
createNodeIterator(in Node root,in unsigned long whatToShow,in NodeFilter filter,in boolean entityReferenceExpansion)
raises(DOMException);
TreeWalker
createTreeWalker(in Node root,in unsigned long whatToShow,in NodeFilter filter,in boolean entityReferenceExpansion)
raises(DOMException);};

Methods
createNodeIterator
Create a new NodeIterator [p.19] over the subtree rooted at the specified node.
Parametersroot of type Node
The node which will be iterated together with its children. The iterator is initially
positioned just before this node. The whatToShow flags and the filter, if any, are notconsidered when setting this position. The root must not be null.

27

1.2. Formal Interface Definition

whatToShow of type unsigned longThis flag specifies which node types may appear in the logical view of the treepresented by the iterator. See the description of NodeFilter [p.21] for the set of
possible SHOW_ values.
These flags can be combined using OR.
filter of type NodeFilter [p.21]
The NodeFilter to be used with this TreeWalker [p.24] , or null to indicate nofilter.
entityReferenceExpansion of type boolean
The value of this flag determines whether entity reference nodes are expanded.
Return Value
NodeIterator [p.19]

The newly created NodeIterator.

Exceptions
DOMException

NOT_SUPPORTED_ERR: Raised if the specified root isnull.

createTreeWalker
Create a new TreeWalker [p.24] over the subtree rooted at the specified node.
Parametersroot of type Node
The node which will serve as the root for the TreeWalker [p.24] . The
whatToShow flags and the NodeFilter [p.21] are not considered when setting
this value; any node type will be accepted as the root. The currentNode of the
TreeWalker is initialized to this node, whether or not it is visible. The root
functions as a stopping point for traversal methods that look upward in the document
structure, such as parentNode and nextNode. The root must not be null.
whatToShow of type unsigned longThis flag specifies which node types may appear in the logical view of the treepresented by the tree-walker. See the description of NodeFilter [p.21] for the setof possible SHOW_ values.
These flags can be combined using OR.
filter of type NodeFilter [p.21]
The NodeFilter to be used with this TreeWalker [p.24] , or null to indicate nofilter.
entityReferenceExpansion of type boolean
If this flag is false, the contents of EntityReference nodes are not presented in
the logical view.
Return Value
TreeWalker [p.24]

The newly created TreeWalker.

28

1.2. Formal Interface Definition

Exceptions
DOMException

NOT_SUPPORTED_ERR: Raised if the specified root is
null.

29

1.2. Formal Interface Definition30

2. Document Object Model Range

2. Document Object Model Range
Editors
Peter Sharpe, SoftQuad Software Inc.
Vidur Apparao, Netscape Communications Corp.
Lauren Wood, SoftQuad Software Inc.

2.1. Introduction
A Range identifies a range of content in a Document, DocumentFragment or Attr. It is contiguous in thesense that it can be characterized as selecting all of the content between a pair of boundary-points.
Note: In a text editor or a word processor, a user can make a selection by pressing down the mouse at one
point in a document, moving the mouse to another point, and releasing the mouse. The resulting selection
is contiguous and consists of the content between the two points.
The term ’selecting’ does not mean that every Range corresponds to a selection made by a GUI user;
however, such a selection can be returned to a DOM user as a Range.
Note: In bidirectional writing (Arabic, Hebrew), a range may correspond to a logical selection that is notnecessarily contiguous when displayed. A visually contiguous selection, also used in some cases, may notcorrespond to a single logical selection, and may therefore have to be represented by more than one range.
The Range interface provides methods for accessing and manipulating the document tree at a higher level
than similar methods in the Node interface. The expectation is that each of the methods provided by the
Range interface for the insertion, deletion and copying of content can be directly mapped to a series ofNode editing operations enabled by DOM Core. In this sense, the Range operations can be viewed asconvenience methods that also enable the implementation to optimize common editing patterns.
This chapter describes the Range interface, including methods for creating and moving a Range andmethods for manipulating content with Ranges.
The interfaces found within this section are not mandatory. A DOM application may use the
hasFeature(feature, version) method of the DOMImplementation interface withparameter values "Range" and "2.0" (respectively) to determine whether or not this module is supportedby the implementation. In order to fully support this module, an implementation must also support the"Core" feature defined defined in the DOM Level 2 Core specification [DOM Level 2 Core]. Please referto additional information about conformance in the DOM Level 2 Core specification [DOM Level 2
Core].

2.2. Definitions and Notation31

2.2.1. Position

2.2.1. Position
This chapter refers to two different representations of a document: the text or source form that includes the
document markup and the tree representation similar to the one described in the introduction section of the
DOM Level 2 Core [DOM Level 2 Core].
A Range consists of two boundary-points corresponding to the start and the end of the Range. A
boundary-point’s position in a Document or DocumentFragment tree can be characterized by a node andan offset. The node is called the container of the boundary-point and of its position. The container and its
ancestors are the ancestor containers of the boundary-point and of its position. The offset within the nodeis called the offset of the boundary-point and its position. If the container is an Attr, Document,
DocumentFragment, Element or EntityReference node, the offset is between its child [p.73] nodes. If thecontainer is a CharacterData, Comment or ProcessingInstruction node, the offset is between the 16-bit
units [p.73] of the UTF-16 encoded string contained by it.
The boundary-points [p.32] of a Range must have a common ancestor container [p.32] which is either aDocument, DocumentFragment or Attr node. That is, the content of a Range must be entirely within thesubtree rooted by a single Document, DocumentFragment or Attr Node. This common ancestor container[p.32] is known as the root container of the Range. The tree rooted by the root container [p.32] is known
as the Range’s context tree.
The container [p.32] of a boundary-point [p.32] of a Range must be an Element, Comment,
ProcessingInstruction, EntityReference, CDATASection, Document, DocumentFragment, Attr, or Text
node. None of the ancestor container [p.32] s of the boundary-point [p.32] of a Range can be aDocumentType, Entity or Notation node.
In terms of the text representation of a document, the boundary-points [p.32] of a Range can only be on
token boundaries. That is, the boundary-point [p.32] of the text range cannot be in the middle of a start- or
end-tag of an element or within the name of an entity or character reference. A Range locates a contiguous
portion of the content of the structure model.
The relationship between locations in a text representation of the document and in the Node tree interfaceof the DOM is illustrated in the following diagram:

32

2.2.1. Position

Range Example
In this diagram, four different Ranges are illustrated. The boundary-points [p.32] of each Range arelabelled with s# (the start of the Range) and e# (the end of the Range), where # is the number of theRange. For Range 2, the start is in the BODY element and is immediately after the H1 element andimmediately before the P element, so its position is between the H1 and P children of BODY. The offset[p.32] of a boundary-point [p.32] whose container [p.32] is not a CharacterData node is 0 if it is before
the first child, 1 if between the first and second child, and so on. So, for the start of the Range 2, thecontainer [p.32] is BODY and the offset [p.32] is 1. The offset [p.32] of a boundary-point [p.32] whose
container [p.32] is a CharacterData node is obtained similarly but using 16-bit unit [p.73] positions
instead. For example, the boundary-point [p.32] labelled s1 of the Range 1 has a Text node (the one
containing "Title") as its container [p.32] and an offset [p.32] of 2 since it is between the second and third
16-bit unit [p.73] .
Notice that the boundary-point [p.32] s of Ranges 3 and 4 correspond to the same location in the text
representation. An important feature of the Range is that a boundary-point [p.32] of a Range canunambiguously represent every position within the document tree.
The container [p.32] s and offset [p.32] s of the boundary-point [p.32] s can be obtained through thefollowing read-only Range attributes:

33

2.3. Creating a Range

readonly attribute Node startContainer;
readonly attribute long startOffset;
readonly attribute Node endContainer;
readonly attribute long endOffset;

If the boundary-point [p.32] s of a Range have the same container [p.32] s and offset [p.32] s, the Range issaid to be a collapsed Range. (This is often referred to as an insertion point in a user agent.)

2.2.2. Selection and Partial Selection
A node or 16-bit unit [p.73] unit is said to be selected by a Range if it is between the two boundary-point[p.32] s of the Range, that is, if the position immediately before the node or 16-bit unit is before the end of
the Range and the position immediately after the node or 16-bit unit is after the start of the range. For
example, in terms of a text representation of the document, an element would be selected [p.34] by aRange if its corresponding start-tag was located after the start of the Range and its end-tag was locatedbefore the end of the Range. In the examples in the above diagram, the Range 2 selects [p.34] the P nodeand the Range 3 selects [p.34] the text node containing the text "Blah xyz."
A node is said to be partially selected by a Range if it is an ancestor container [p.32] of exactly one
boundary-point [p.32] of the Range. For example, consider Range 1 in the above diagram. The element
H1 is partially selected [p.34] by that Range since the start of the Range is within one of its children.

2.2.3. Notation
Many of the examples in this chapter are illustrated using a text representation of a document. The
boundary-point [p.32] s of a Range are indicated by displaying the characters (be they markup or datacharacters) between the two boundary-point [p.32] s in bold, as in<FOO>ABC<BAR>DEF</BAR></FOO>

When both boundary-point [p.32] s are at the same position, they are indicated with a bold caret (’^’), as
in<FOO>A^BC<BAR>DEF</BAR></FOO>

2.3. Creating a Range
A Range is created by calling the createRange() method on the DocumentRange [p.53] interface.
This interface can be obtained from the object implementing the Document interface usingbinding-specific casting methods.
interface DocumentRange {Range createRange();}

The initial state of the Range returned from this method is such that both of its boundary-point [p.32] s are
positioned at the beginning of the corresponding Document, before any content. In other words, thecontainer [p.32] of each boundary-point [p.32] is the Document node and the offset within that node is 0.

34

2.4. Changing a Range’s Position

Like some objects created using methods in the Document interface (such as Nodes andDocumentFragments), Ranges created via a particular document instance can select only content
associated with that Document, or with DocumentFragments and Attrs for which that Document is theownerDocument. Such Ranges, then, can not be used with other Document instances.

2.4. Changing a Range’s Position
A Range’s position can be specified by setting the container [p.32] and offset [p.32] of eachboundary-point with the setStart and setEnd methods.
void setStart(in Node parent, in long offset)
raises(RangeException);
void setEnd(in Node parent, in long offset)
raises(RangeException);

If one boundary-point of a Range is set to have a root container [p.32] other than the current one for theRange, the Range is collapsed [p.34] to the new position. This enforces the restriction that bothboundary-points of a Range must have the same root container [p.32] .
The start position of a Range is guaranteed to never be after the end position. To enforce this restriction, if
the start is set to be at a position after the end, the Range is collapsed [p.34] to that position. Similarly, if
the end is set to be at a position before the start, the Range is collapsed [p.34] to that position.
It is also possible to set a Range’s position relative to nodes in the tree:
void setStartBefore(in Node node);raises(RangeException);
void setStartAfter(in Node node);raises(RangeException);
void setEndBefore(in Node node);raises(RangeException);
void setEndAfter(in Node node);raises(RangeException);

The parent [p.73] of the node becomes the container [p.32] of the boundary-point [p.32] and the Range issubject to the same restrictions as given above in the description of setStart()and setEnd().
A Range can be collapsed [p.34] to either boundary-point:
void collapse(in boolean toStart);

Passing TRUE as the parameter toStart will collapse [p.34] the Range to its start, FALSE to its end.
Testing whether a Range is collapsed [p.34] can be done by examining the collapsed attribute:
readonly attribute boolean collapsed;

The following methods can be used to make a Range select the contents of a node or the node itself.

35

2.5. Comparing Range Boundary-Points

void selectNode(in Node n);void selectNodeContents(in Node n);

The following examples demonstrate the operation of the methods selectNode andselectNodeContents:
Before:^<BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>
After Range.selectNodeContents(FOO):<BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>(In this case, FOO is the parent of both boundary-points)
After Range.selectNode(FOO):<BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>

2.5. Comparing Range Boundary-Points
It is possible to compare two Ranges by comparing their boundary-points:
short compareBoundaryPoints(in CompareHow how, in Range sourceRange) raises(RangeException);where CompareHow is one of four values: START_TO_START, START_TO_END, END_TO_END and
END_TO_START. The return value is -1, 0 or 1 depending on whether the corresponding boundary-pointof the Range is before, equal to, or after the corresponding boundary-point of sourceRange. An
exception is thrown if the two Ranges have different root container [p.32] s.
The result of comparing two boundary-points (or positions) is specified below. An informal but notalways correct specification is that an boundary-point is before, equal to, or after another if it corresponds
to a location in a text representation before, equal to, or after the other’s corresponding location.
Let A and B be two boundary-points or positions. Then one of the following holds: A is before B, A isequal to B, or A is after B. Which one holds is specified in the following by examining four cases:
In the first case the boundary-points have the same container [p.32] . A is before B if its offset [p.32] isless than the offset [p.32] of B, A is equal to B if its offset [p.32] is equal to the offset [p.32] of B, and A isafter B if its offset [p.32] is greater than the offset [p.32] of B.
In the second case a child node C of the container [p.32] of A is an ancestor container [p.32] of B. In thiscase, A is before B if the offset [p.32] of A is less than or equal to the index of the child node C and A isafter B otherwise.
In the third case a child node C of the container [p.32] of B is an ancestor container [p.32] of A. In thiscase, A is before B if the index of the child node C is less than the offset [p.32] of B and A is after B
otherwise.
In the fourth case, none of three other cases hold: the containers of A and B are siblings [p.73] ordescendants [p.73] of sibling nodes. In this case, A is before B if the container [p.32] of A is before thecontainer [p.32] of B in a pre-order traversal of the Ranges’ context tree [p.32] and A is after B otherwise.

36

2.6. Deleting Content with a Range

Note that because the same location in a text representation of the document can correspond to two
different positions in the DOM tree, it is possible for two boundary-points to not compare equal eventhough they would be equal in the text representation. For this reason, the informal definition above cansometimes be incorrect.

2.6. Deleting Content with a Range
One can delete the contents selected by a Range with:void deleteContents();

deleteContents() deletes all nodes and characters selected by the Range. All other nodes andcharacters remain in the context tree [p.32] of the Range. Some examples of this deletion operation are:(1) <FOO>AB<MOO>CD</MOO>CD</FOO><FOO>A^CD</FOO>-->(2) <FOO>A<MOO>BC</MOO>DE</FOO><FOO>A<MOO>B</MOO>^E</FOO>-->(3) <FOO>XY<BAR>ZW</BAR>Q</FOO><FOO>X^<BAR>W</BAR>Q</FOO>-->(4) <FOO><BAR1>AB</BAR1><BAR2/><BAR3>CD</BAR3></FOO>--> <FOO><BAR1>A</BAR1>^<BAR3>D</BAR3>

After deleteContents() is invoked on a Range, the Range is collapsed [p.34] . If no node waspartially selected [p.34] by the Range, then it is collapsed [p.34] to its original start point, as in example(1). If a node was partially selected [p.34] by the Range and was an ancestor container [p.32] of the startof the Range and no ancestor [p.73] of the node satisfies these two conditions, then the Range is collapsed
to the position immediately after the node, as in examples (2) and (4). If a node was partially selected[p.34] by the Range and was an ancestor container [p.32] of the end of the Range and no ancestor of thenode satisfies these two conditions, then the Range is collapsed to the position immediately before thenode, as in examples (3) and (4).
Note that if deletion of a Range leaves adjacent Text nodes, they are not automatically merged, and empty
Text nodes are not automatically removed. Two Text nodes should be joined only if each is the containerof one of the boundary-points of a Range whose contents are deleted. To merge adjacent Text nodes, or
remove empty text nodes, the normalize() method on the Node interface should be used.

2.7. Extracting Content
If the contents of a Range need to be extracted rather than deleted, the following method may be used:
DocumentFragment extractContents();

The extractContents() method removes nodes from the Range’s context tree [p.32] similarly to thedeleteContents() method. In addition, it places the deleted contents in a new
DocumentFragment. The following examples illustrate the contents of the returned

372.8. Cloning Content

DocumentFragment:(1) <FOO>AB<MOO>CD</MOO>CD</FOO>
B<MOO>CD</MOO>-->(2) <FOO>A<MOO>BC</MOO>DE</FOO><MOO>C<MOO>D-->(3) <FOO>XY<BAR>ZW</BAR>Q</FOO>Y<BAR>Z</BAR>

-->

(4)
<FOO><BAR1>AB</BAR1><BAR2/><BAR3>CD</BAR3></FOO> --><BAR1>B</BAR1><BAR2/><BAR3>C</BAR3>

It is important to note that nodes that are partially selected [p.34] by the Range are cloned. Since part ofsuch a node’s contents must remain in the Range’s context tree [p.32] and part of the contents must be
moved to the new DocumentFragment, a clone of the partially selected [p.34] node is included in the newDocumentFragment. Note that cloning does not take place for selected [p.34] elements; these nodes are
moved to the new DocumentFragment.

2.8. Cloning Content
The contents of a Range may be duplicated using the following method:
DocumentFragment cloneContents();

This method returns a DocumentFragment that is similar to the one returned by the method
extractContents(). However, in this case, the original nodes and character data in the Range are
not removed from the Range’s context tree [p.32] . Instead, all of the nodes and text content within the
returned DocumentFragment are cloned.

2.9. Inserting Content
A node may be inserted into a Range using the following method:void insertNode(in Node n) raises(RangeException);

The insertNode() method inserts the specified node into the Range’s context tree [p.32] . The node isinserted at the start boundary-point [p.32] of the Range, without modifying it.
If the start boundary point of the Range is in a Text node, the insertNode operation splits the Text
node at the boundary point. If the node to be inserted is also a Text node, the resulting adjacent Text
nodes are not normalized automatically; this operation is left to the application.
The Node passed into this method can be a DocumentFragment. In that case, the contents of theDocumentFragment are inserted at the start boundary-point [p.32] of the Range, but theDocumentFragment itself is not. Note that if the Node represents the root of a sub-tree, the entire
sub-tree is inserted.

38

2.10. Surrounding Content

The same rules that apply to the insertBefore() method on the Node interface apply here.
Specifically, the Node passed in, if it already has a parent, will be removed from its existing position.

2.10. Surrounding Content
The insertion of a single node to subsume the content selected by a Range can be performed with:void surroundContents(in Node newParent);

The surroundContents() method causes all of the content selected by the Range to be rooted by the
specified node. The nodes may not be Attr, Entity, DocumentType, Notation, Document, orDocumentFragment nodes. Calling surroundContents() with the Element node FOO in thefollowing examples yields:
Before:<BAR>AB<MOO>C</MOO>DE</BAR>
After surroundContents(FOO):<BAR>A<FOO>B<MOO>C</MOO>D</FOO>E</BAR>

Another way of describing the effect of this method on the Range’s context tree [p.32] is to decompose it
in terms of other operations:
1. Remove the contents selected by the Range with a call to extractContents().
2. Insert the node newParent where the Range is collapsed (after the extraction) withinsertNode().
3. Insert the entire contents of the extracted DocumentFragment into newParent. Specifically, invoke
the appendChild() on newParent passing in the DocumentFragment returned as a result of thecall to extractContents()
4. Select newParent and all of its contents with selectNode().
The surroundContents() method raises an exception if the Range partially selects [p.34] a
non-Text node. An example of a Range for which surroundContents()raises an exception is:<FOO>AB<BAR>CD</BAR>E</FOO>

If the node newParent has any children, those children are removed before its insertion. Also, if thenode newParent already has a parent, it is removed from the original parent’s childNodes list.

2.11. Miscellaneous Members
One can clone a Range:
Range cloneRange();39

2.12. Range modification under document mutation

This creates a new Range which selects exactly the same content as that selected by the Range on which
the method cloneRange was invoked. No content is affected by this operation.
Because the boundary-points of a Range do not necessarily have the same container [p.32] s, use:
readonly attribute Node commonAncestorContainer;

to get the ancestor container [p.32] of both boundary-points that is furthest down from the Range’s root
container [p.32]
One can get a copy of all the character data selected or partially selected by a Range with:
DOMString toString();

This does nothing more than simply concatenate all the character data selected by the Range. This
includes character data in both Text and CDATASection nodes.

2.12. Range modification under document mutation
As a document is modified, the Ranges within the document need to be updated. For example, if one
boundary-point of a Range is within a node and that node is removed from the document, then the Range
would be invalid unless it is fixed up in some way. This section describes how Ranges are modified underdocument mutations so that they remain valid.
There are two general principles which apply to Ranges under document mutation: The first is that all
Ranges in a document will remain valid after any mutation operation and the second is that, as much as
possible, all Ranges will select the same portion of the document after any mutation operation.
Any mutation of the document tree which affect Ranges can be considered to be a combination of basic
deletion and insertion operations. In fact, it can be convenient to think of those operations as being
accomplished using the deleteContents() and insertNode() Range methods and, in the case of
Text mutations, the splitText() and normalize() methods.

2.12.1. Insertions
An insertion occurs at a single point, the insertion point, in the document. For any Range in the documenttree, consider each boundary-point. The only case in which the boundary-point will be changed after theinsertion is when the boundary-point and the insertion point have the same container [p.32] and the offset[p.32] of the insertion point is strictly less than the offset [p.32] of the Range’s boundary-point. In thatcase the offset [p.32] of the Range’s boundary-point will be increased so that it is between the same nodes
or characters as it was before the insertion.
Note that when content is inserted at a boundary-point, it is ambiguous as to where the boundary-pointshould be repositioned if its relative position is to be maintained. There are two possibilities: at the start orat the end of the newly inserted content. We have chosen that in this case neither the container [p.32] nor
offset [p.32] of the boundary-point is changed. As a result, the boundary-point will be positioned at thestart of the newly inserted content.

40

2.12.2. Deletions

Examples:Suppose the Range selects the following:<P>Abcd efgh XY blah ijkl</P>

Consider the insertion of the text "inserted text" at the following positions:
1. Before the ’X’:
<P>Abcd efgh inserted textXY blah ijkl</P>
2. After the ’X’:
<P>Abcd efgh Xinserted textY blah ijkl</P>
3. After the ’Y’:
<P>Abcd efgh XYinserted text blah ijkl</P>
4. After the ’h’ in "Y blah":<P>Abcd efgh XY blahinserted text ijkl</P>

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 underdeletions we need only consider what happens to a Range under a single deleteContents()operationof another Range. And, in fact, we need only consider what happens to a single boundary-point of theRange 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 [p.34] ) 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 [p.32] is also the container [p.32] of one of the boundary-points of the Range being deleted. If
there is such a common container [p.32] , then the index of the boundary-point is modified so that theboundary-point maintains its position relative to the content of the container [p.32] .
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.

41

2.12.2. Deletions

Before:<P>Abcd efgh The Range ijkl</P>

After:<P>Abcd Range ijkl</P>

Example 2.
Before:<p>Abcd efgh The Range ijkl</p>After:<p>Abcd ^kl</p>

Example 3.
Before:<P>ABCD efgh The <EM>Range</EM> ijkl</P>

After:<P>ABCD <EM>ange</EM> ijkl</P>

In this example, the container of the start boundary-point after the deletion is the Text node holding thestring "ange".
Example 4.
Before:<P>Abcd efgh The Range ijkl</P>

After:<P>Abcd he Range ijkl</P>

Example 5.
Before:<P>Abcd <EM>efgh The Range ij</EM>kl</P>

After:<P>Abcd ^kl</P>42

2.13. Formal Description of the Range Interface

2.13. Formal Description of the Range Interface
To summarize, the complete, formal description of the Range [p.43] interface is given below:
Interface Range (introduced in DOM Level 2)
IDL Definition// Introduced in DOM Level 2:interface Range {readonly attribute NodestartContainer;// raises(DOMException) on retrieval

readonly attribute longstartOffset;// raises(DOMException) on retrieval

readonly attribute NodeendContainer;// raises(DOMException) on retrieval

readonly attribute long

endOffset;// raises(DOMException) on retrieval

readonly attribute boolean

collapsed;// raises(DOMException) on retrieval

readonly attribute NodecommonAncestorContainer;// raises(DOMException) on retrieval

void

void

void

void

void

void

void
void

void

setStart(in Node refNode,in long offset)
raises(RangeException,
DOMException);
setEnd(in Node refNode,in long offset)
raises(RangeException,
DOMException);
setStartBefore(in Node refNode)raises(RangeException,
DOMException);
setStartAfter(in Node refNode)raises(RangeException,
DOMException);
setEndBefore(in Node refNode)raises(RangeException,
DOMException);
setEndAfter(in Node refNode)raises(RangeException,
DOMException);collapse(in boolean toStart)raises(DOMException);
selectNode(in Node refNode)raises(RangeException,
DOMException);
selectNodeContents(in Node refNode)raises(RangeException,
DOMException);43

2.13. Formal Description of the Range Interface// CompareHow
const unsigned short
const unsigned short
const unsigned short
const unsigned short
short

void
DocumentFragment
DocumentFragment
void

void

Range
DOMStringvoid

START_TO_START
START_TO_END
END_TO_END
END_TO_START

= 0;
= 1;
= 2;
= 3;

compareBoundaryPoints(in unsigned short how,in Range sourceRange)raises(DOMException);
deleteContents()
raises(DOMException);extractContents()
raises(DOMException);cloneContents()
raises(DOMException);
insertNode(in Node newNode)raises(DOMException,
RangeException);surroundContents(in Node newParent)
raises(DOMException,
RangeException);cloneRange()raises(DOMException);
toString()raises(DOMException);
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

44

2.13. Formal Description of the Range Interface

DOMException

INVALID_STATE_ERR: Raised if detach() has already been
invoked on this object.

commonAncestorContainer of type Node, readonly
The deepest [p.73] common ancestor container [p.32] 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 Value45

2.13. Formal Description of the Range Interface

DocumentFragment

A DocumentFragment that contains content equivalent tothis Range.

Exceptions
DOMException

HIERARCHY_REQUEST_ERR: Raised if a DocumentTypenode 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 theRange.
Return Value
Range [p.43]

The duplicated Range.

Exceptions
DOMException

INVALID_STATE_ERR: Raised if detach() has already been
invoked on this object.

No Parameterscollapse
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 ValuecompareBoundaryPoints
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 [p.43]
The Range on which this current Range is compared to.
Return Value46

2.13. Formal Description of the Range Interface

short-1, 0 or 1 depending on whether the corresponding boundary-point of theRange is respectively before, equal to, or after the corresponding
boundary-point of sourceRange.

Exceptions
DOMException

WRONG_DOCUMENT_ERR: Raised if the two Ranges are notin 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 portionof 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
detachCalled 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 orattribute 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 ValueextractContents
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.

47

2.13. Formal Description of the Range Interface

Exceptions
DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if any portionof the content of the Range is read-only or any of the nodes whichcontain any of the content of the Range are read-only.
HIERARCHY_REQUEST_ERR: Raised if a DocumentTypenode would be extracted into the new DocumentFragment.
INVALID_STATE_ERR: Raised if detach() has already been
invoked on this object.

No ParametersinsertNode
Inserts a node into the Document or DocumentFragment at the start of the Range. If thecontainer 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 thenode to be inserted is a DocumentFragment node, the children will be inserted rather thanthe 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 anancestor container [p.32] of the start of the Range isread-only.
WRONG_DOCUMENT_ERR: Raised if newNode and thecontainer [p.32] of the start of the Range were not createdfrom the same document.
HIERARCHY_REQUEST_ERR: Raised if the container[p.32] of the start of the Range is of a type that does not allow
children of the type of newNode or if newNode is anancestor of the container [p.32] .
INVALID_STATE_ERR: Raised if detach() has alreadybeen invoked on this object.

RangeException[p.53]INVALID_NODE_TYPE_ERR: Raised if newNode is an
Attr, Entity, Notation, or Document node.

No Return Value48

2.13. Formal Description of the Range Interface

selectNode
Select a node and its contents
Parameters
refNode of type Node
The node to select.
Exceptions
RangeException[p.53]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 alreadybeen invoked on this object.

No Return Value
selectNodeContents
Select the contents within a nodeParameters
refNode of type Node
Node to select from
Exceptions
RangeException[p.53]INVALID_NODE_TYPE_ERR: Raised if refNode or anancestor of refNode is an Entity, Notation orDocumentType node.

DOMException

INVALID_STATE_ERR: Raised if detach() has alreadybeen invoked on this object.

No Return Value
setEndSets the attributes describing the end of a Range.
Parameters
refNode of type NodeThe refNode value. This parameter must be different from null.
offset of type long
The endOffset value.
Exceptions49

2.13. Formal Description of the Range Interface

RangeException[p.53]INVALID_NODE_TYPE_ERR: Raised if refNode or anancestor of refNode is an Entity, Notation, orDocumentType node.

DOMException

INDEX_SIZE_ERR: Raised if offset is negative or greaterthan the number of child units in refNode. Child units are
16-bit units [p.73] 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 othercases.
INVALID_STATE_ERR: Raised if detach() has alreadybeen invoked on this object.

No Return Value
setEndAfter
Sets the end of a Range to be after a nodeParameters
refNode of type Node
Range ends after refNode.
Exceptions
RangeException[p.53]INVALID_NODE_TYPE_ERR: Raised if the root containerof 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 alreadybeen 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[p.53]INVALID_NODE_TYPE_ERR: Raised if the root containerof refNode is not an Attr, Document, orDocumentFragment node or if refNode is a Document,
DocumentFragment, Attr, Entity, or Notation node.

DOMException

INVALID_STATE_ERR: Raised if detach() has alreadybeen invoked on this object.

50

2.13. Formal Description of the Range Interface

No Return Value
setStart
Sets the attributes describing the start of the Range.
Parameters
refNode of type NodeThe refNode value. This parameter must be different from null.
offset of type long
The startOffset value.
Exceptions
RangeException[p.53]INVALID_NODE_TYPE_ERR: Raised if refNode or anancestor of refNode is an Entity, Notation, orDocumentType node.

DOMException

INDEX_SIZE_ERR: Raised if offset is negative or greaterthan the number of child units in refNode. Child units are
16-bit units [p.73] 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 othercases.
INVALID_STATE_ERR: Raised if detach() has alreadybeen invoked on this object.

No Return Value
setStartAfter
Sets the start position to be after a nodeParameters
refNode of type Node
Range starts after refNode
Exceptions
RangeException[p.53]INVALID_NODE_TYPE_ERR: Raised if the root containerof refNode is not an Attr, Document, orDocumentFragment node or if refNode is a Document,
DocumentFragment, Attr, Entity, or Notation node.

DOMException

INVALID_STATE_ERR: Raised if detach() has alreadybeen invoked on this object.

No Return Value
setStartBefore
Sets the start position to be before a nodeParameters512.13. Formal Description of the Range Interface

refNode of type Node
Range starts before refNode
Exceptions
RangeException[p.53]INVALID_NODE_TYPE_ERR: Raised if the root containerof refNode is not an Attr, Document, orDocumentFragment node or if refNode is a Document,
DocumentFragment, Attr, Entity, or Notation node.

DOMException

INVALID_STATE_ERR: Raised if detach() has alreadybeen invoked on this object.

No Return ValuesurroundContents
Reparents the contents of the Range to the given node and inserts the node at the positionof 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 anancestor container [p.32] of either boundary-point of theRange is read-only.
WRONG_DOCUMENT_ERR: Raised if newParent andthe container [p.32] of the start of the Range were not createdfrom the same document.
HIERARCHY_REQUEST_ERR: Raised if the container[p.32] of the start of the Range is of a type that does not allow
children of the type of newParent or if newParent is anancestor of the container [p.32] or if node would end up witha child node of a type not allowed by the type of node.
INVALID_STATE_ERR: Raised if detach() has alreadybeen invoked on this object.

RangeException[p.53]

BAD_BOUNDARYPOINTS_ERR: Raised if the Range
partially selects [p.34] a non-text node.
INVALID_NODE_TYPE_ERR: Raised if node is an Attr,
Entity, DocumentType, Notation, Document, orDocumentFragment node.

52

2.13. Formal Description of the Range Interface

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 {RangecreateRange();};

Methods
createRange
This interface can be obtained from the object implementing the Document interface
using binding-specific casting methods.
Return Value
Range[p.43]The initial state of the Range returned from this method is such that both ofits 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 [p.53] as specified in their method descriptions.
IDL Definition53

2.13. Formal Description of the Range Interface// Introduced in DOM Level 2:
exception RangeException {unsigned shortcode;};// RangeExceptionCode
const unsigned short
BAD_BOUNDARYPOINTS_ERR
const unsigned short
INVALID_NODE_TYPE_ERR

= 1;
= 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 [p.32] 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.

54

Appendix A: IDL Definitions

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 [p.55] , and Range [p.56] .
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 Nodereadonly attribute unsigned longreadonly attribute NodeFilter
readonly attribute boolean
NodenextNode()root;
whatToShow;filter;expandEntityReferences;raises(dom::DOMException);NodepreviousNode()void

detach();raises(dom::DOMException);};// Introduced in DOM Level 2:interface NodeFilter {// Constants returned by acceptNode
const short
FILTER_ACCEPT
const short
FILTER_REJECT
const short
FILTER_SKIP

= 1;
= 2;
= 3;

// Constants for whatToShow
const unsigned long
SHOW_ALL
const unsigned long
SHOW_ELEMENT
const unsigned long
SHOW_ATTRIBUTE= 0xFFFFFFFF;= 0x00000001;= 0x00000002;

55

A.2: Document Object Model Range

const unsigned long
const unsigned long
const unsigned long
const unsigned long
const unsigned long
const unsigned long
const unsigned long
const unsigned long
const unsigned long
const unsigned longshort

SHOW_TEXT
SHOW_CDATA_SECTION
SHOW_ENTITY_REFERENCE
SHOW_ENTITY
SHOW_PROCESSING_INSTRUCTION
SHOW_COMMENT
SHOW_DOCUMENT
SHOW_DOCUMENT_TYPE
SHOW_DOCUMENT_FRAGMENT
SHOW_NOTATION= 0x00000004;= 0x00000008;= 0x00000010;= 0x00000020;= 0x00000040;= 0x00000080;= 0x00000100;= 0x00000200;= 0x00000400;= 0x00000800;

acceptNode(in Node n);};// Introduced in DOM Level 2:interface TreeWalker {readonly attribute Nodereadonly attribute unsigned longreadonly attribute NodeFilter
readonly attribute boolean
attribute Node

Node
Node
Node
Node
Node
Node
Node

root;
whatToShow;filter;expandEntityReferences;currentNode;// raises(dom::DOMException) on setting

parentNode();firstChild();
lastChild();
previousSibling();
nextSibling();previousNode();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

56

ranges.idl:

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 shortcode;};// RangeExceptionCode
const unsigned short
BAD_BOUNDARYPOINTS_ERR
const unsigned short
INVALID_NODE_TYPE_ERR// Introduced in DOM Level 2:interface Range {readonly attribute Node

= 1;
= 2;

startContainer;// raises(dom::DOMException) on retrieval

readonly attribute longstartOffset;// raises(dom::DOMException) on retrieval

readonly attribute NodeendContainer;// 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 NodecommonAncestorContainer;// raises(dom::DOMException) on retrieval

void

void

void

setStart(in Node refNode,in long offset)
raises(RangeException,
dom::DOMException);
setEnd(in Node refNode,in long offset)
raises(RangeException,
dom::DOMException);
setStartBefore(in Node refNode)raises(RangeException,

57

ranges.idl:

void

void

void

void
void

void

dom::DOMException);
setStartAfter(in Node refNode)raises(RangeException,
dom::DOMException);
setEndBefore(in Node refNode)raises(RangeException,
dom::DOMException);
setEndAfter(in Node refNode)raises(RangeException,
dom::DOMException);collapse(in boolean toStart)raises(dom::DOMException);
selectNode(in Node refNode)raises(RangeException,
dom::DOMException);
selectNodeContents(in Node refNode)raises(RangeException,
dom::DOMException);// CompareHow
const unsigned short
const unsigned short
const unsigned short
const unsigned short
short

void
DocumentFragment
DocumentFragment
void

void

Range
DOMStringvoid

START_TO_START
START_TO_END
END_TO_END
END_TO_START

= 0;
= 1;
= 2;
= 3;

compareBoundaryPoints(in unsigned short how,in Range sourceRange)raises(dom::DOMException);
deleteContents()
raises(dom::DOMException);extractContents()
raises(dom::DOMException);cloneContents()
raises(dom::DOMException);
insertNode(in Node newNode)raises(dom::DOMException,
RangeException);surroundContents(in Node newParent)
raises(dom::DOMException,
RangeException);cloneRange()raises(dom::DOMException);
toString()raises(dom::DOMException);
detach()raises(dom::DOMException);};// Introduced in DOM Level 2:interface DocumentRange {RangecreateRange();};};#endif // _RANGES_IDL_58

Appendix B: Java Language Binding

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 [p.59] , and Range [p.61] .
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
public static final short FILTER_REJECT
public static final short FILTER_SKIP// Constants for whatToShow
public static final int SHOW_ALL
public static final int SHOW_ELEMENT
public static final int SHOW_ATTRIBUTE
public static final int SHOW_TEXT

= 1;
= 2;
= 3;

= 0xFFFFFFFF;= 0x00000001;= 0x00000002;= 0x00000004;

59

org/w3c/dom/traversal/TreeWalker.java:

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();}60

B.2: Document Object Model Rangeorg/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 Rangeorg/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 shortcode;// 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;61

org/w3c/dom/ranges/Range.java:

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
public static final short START_TO_END
public static final short END_TO_END
public static final short END_TO_START

= 0;
= 1;
= 2;
= 3;

public short compareBoundaryPoints(short how,Range sourceRange)
throws DOMException;
public void deleteContents()
throws DOMException;
public DocumentFragment extractContents()
throws DOMException;62

org/w3c/dom/ranges/DocumentRange.java:

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();}63

org/w3c/dom/ranges/DocumentRange.java:

64

Appendix C: ECMAScript Language Binding

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 [p.65] , andRange [p.67] .
Note: Exceptions handling is only supported by ECMAScript implementation conformant with theStandard 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.
filterThis 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_ACCEPTThis constant is of type short and its value is 1.
NodeFilter.FILTER_REJECTThis 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.

65

C.1: Document Object Model Traversal

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_NOTATIONThis 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 Nodeobject.
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.
filterThis 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.

66

C.2: Document Object Model Range

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 onretrieval.
startOffset
This read-only property is a long object and can raise a DOMException object onretrieval.
endContainer
This read-only property is a Node object and can raise a DOMException object onretrieval.

67C.2: Document Object Model Range

endOffset
This read-only property is a long object and can raise a DOMException object onretrieval.
collapsed
This read-only property is of type Boolean and can raise a DOMException object onretrieval.
commonAncestorContainer
This read-only property is a Node object and can raise a DOMException object onretrieval.
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.

68C.2: Document Object Model Range

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:69

C.2: Document Object Model Range

code
This property is of type Number.

70

Appendix D: Acknowledgements

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 (CromwellMedia), 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 thespecification.

71

D.1: Production Systems

72

Glossary

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, forexample 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.
deepestThe deepest element is that element which is furthest from the root or document element in a treemodel of the document.
document order
The term document order has the same meaning as depth first, pre-order traversal, which isequivalent 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."parentA 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 charactersby one. See the definition of tokenized type.

73

Glossary74References

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 BasicMultilingual 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
OMGIDLOMG (Object Management Group) IDL (Interface Definition Language) defined in The Common
Object Request Broker: Architecture and Specification, version 2.3.1, October 1999. Available fromhttp://www.omg.org/
UnicodeThe Unicode Consortium. The Unicode Standard, Version 3.0., February 2000. Available at
http://www.unicode.org/unicode/standard/versions/Unicode3.0.html.

75

F.1: Normative references

76IndexIndex
16-bit unit 31, 34, 51, 49, 73

acceptNodeancestor 18, 26, 37, 73

ancestor container 32, 31, 32, 34, 36, 37,
39, 45, 48, 52

BAD_BOUNDARYPOINTS_ERR

before/after/equal toboundary-point 32, 31, 34, 34, 34, 34, 34,
35, 38child 25, 25, 31, 73

cloneContentscloneRange

collapsecollapsed 44, 34, 35, 37, 41

commonAncestorContainer

compareBoundaryPoints

container 32, 31, 34, 34, 35, 36,
39, 40, 41, 48, 52, 54

context tree 32, 36, 37, 37, 38, 38, 39

createNodeIterator

createRange

createTreeWalker

deepest 45, 73

deleteContents

descendant 14, 20, 25, 36, 73

detach 20, 47

document order 10, 73

DocumentRange

DocumentTraversal

DOM Level 2 Core 9, 31, 31,75

ECMAScript

END_TO_END

END_TO_START

endContainer

endOffset

expandEntityReferences 20, 25

filter 20, 25

FILTER_ACCEPTFILTER_REJECTFILTER_SKIP

firstChildinsertNode

INVALID_NODE_TYPE_ERR

currentNode

extractContents

Java

77

ISO/IEC 10646 73, 75

IndexlastChild

nextNode 20, 26

nextSibling

NodeFilter

NodeIterator

offset 32, 31, 34, 35, 36, 40

OMGIDLparent 11, 16, 18, 26, 35, 73

parentNodepreviousNode 21, 26

previousSibling

Range

RangeException

root 20, 25

selected 34, 34, 37

selectNodeselectNodeContents

setEndsetEndAfter

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 16, 24, 27, 26, 36, 73

START_TO_END

START_TO_START

startContainer

startOffset

toString

TreeWalker

partially selected 34, 34, 37, 37, 39, 52

root container 32, 32, 35, 36, 39

surroundContents

tokenized

Unicode 73, 75

whatToShow 20, 25

78