Interface TreeWalker
public interface TreeWalker
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 substantially different from the same subtree in the
complete, unfiltered document. Nodes that are siblings in the
TreeWalker view may be children of different, widely
separated nodes in the original view. For instance, consider a
NodeFilter 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 and appear as direct children of the root node, no
matter how deeply nested the structure of the original document.
See also the Document Object Model (DOM) Level 2 Traversal and Range Specification.
- Since:
- 9, DOM Level 2
-
Method Summary
Modifier and TypeMethodDescriptionMoves theTreeWalkerto the first visible child of the current node, and returns the new node.The node at which theTreeWalkeris currently positioned.booleanThe value of this flag determines whether the children of entity reference nodes are visible to theTreeWalker.The filter used to screen nodes.getRoot()Therootnode of theTreeWalker, as specified when it was created.intThis attribute determines which node types are presented via theTreeWalker.Moves theTreeWalkerto the last visible child of the current node, and returns the new node.nextNode()Moves theTreeWalkerto the next visible node in document order relative to the current node, and returns the new node.Moves theTreeWalkerto the next sibling of the current node, and returns the new node.Moves to and returns the closest visible ancestor node of the current node.Moves theTreeWalkerto the previous visible node in document order relative to the current node, and returns the new node.Moves theTreeWalkerto the previous sibling of the current node, and returns the new node.voidsetCurrentNode(Node currentNode) The node at which theTreeWalkeris currently positioned.
-
Method Details
-
getRoot
Node getRoot()Therootnode of theTreeWalker, as specified when it was created. -
getWhatToShow
int getWhatToShow()This attribute determines which node types are presented via theTreeWalker. The available set of constants is defined in theNodeFilterinterface. Nodes not accepted bywhatToShowwill be skipped, but their children may still be considered. Note that this skip takes precedence over the filter, if any. -
getFilter
NodeFilter getFilter()The filter used to screen nodes. -
getExpandEntityReferences
boolean getExpandEntityReferences()The value of this flag determines whether the children of entity reference nodes are visible to theTreeWalker. If false, these children and their descendants will be rejected. Note that this rejection takes precedence overwhatToShowand 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 thewhatToShowflags to hide the entity reference node and setexpandEntityReferencesto true when creating theTreeWalker. To produce a view of the document that has entity reference nodes but no entity expansion, use thewhatToShowflags to show the entity reference node and setexpandEntityReferencesto false. -
getCurrentNode
Node getCurrentNode()The node at which theTreeWalkeris currently positioned.
Alterations to the DOM tree may cause the current node to no longer be accepted by theTreeWalker's associated filter.currentNodemay also be explicitly set to any node, whether or not it is within the subtree specified by therootnode or would be accepted by the filter andwhatToShowflags. Further traversal occurs relative tocurrentNodeeven if it is not part of the current view, by applying the filters in the requested direction; if no traversal is possible,currentNodeis not changed. -
setCurrentNode
The node at which theTreeWalkeris currently positioned.
Alterations to the DOM tree may cause the current node to no longer be accepted by theTreeWalker's associated filter.currentNodemay also be explicitly set to any node, whether or not it is within the subtree specified by therootnode or would be accepted by the filter andwhatToShowflags. Further traversal occurs relative tocurrentNodeeven if it is not part of the current view, by applying the filters in the requested direction; if no traversal is possible,currentNodeis not changed.- Throws:
DOMException- NOT_SUPPORTED_ERR: Raised if an attempt is made to setcurrentNodetonull.
-
parentNode
Node parentNode()Moves to and returns the closest visible ancestor node of the current node. If the search forparentNodeattempts to step upward from theTreeWalker'srootnode, or if it fails to find a visible ancestor node, this method retains the current position and returnsnull.- Returns:
- The new parent node, or
nullif the current node has no parent in theTreeWalker's logical view.
-
firstChild
Node firstChild()Moves theTreeWalkerto the first visible child of the current node, and returns the new node. If the current node has no visible children, returnsnull, and retains the current node.- Returns:
- The new node, or
nullif the current node has no visible children in theTreeWalker's logical view.
-
lastChild
Node lastChild()Moves theTreeWalkerto the last visible child of the current node, and returns the new node. If the current node has no visible children, returnsnull, and retains the current node.- Returns:
- The new node, or
nullif the current node has no children in theTreeWalker's logical view.
-
previousSibling
Node previousSibling()Moves theTreeWalkerto the previous sibling of the current node, and returns the new node. If the current node has no visible previous sibling, returnsnull, and retains the current node.- Returns:
- The new node, or
nullif the current node has no previous sibling. in theTreeWalker's logical view.
-
nextSibling
Node nextSibling()Moves theTreeWalkerto the next sibling of the current node, and returns the new node. If the current node has no visible next sibling, returnsnull, and retains the current node.- Returns:
- The new node, or
nullif the current node has no next sibling. in theTreeWalker's logical view.
-
previousNode
Node previousNode()Moves theTreeWalkerto the previous visible node in document order relative to the current node, and returns the new node. If the current node has no previous node, or if the search forpreviousNodeattempts to step upward from theTreeWalker'srootnode, returnsnull, and retains the current node.- Returns:
- The new node, or
nullif the current node has no previous node in theTreeWalker's logical view.
-
nextNode
Node nextNode()Moves theTreeWalkerto 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 theTreeWalker'srootnode, returnsnull, and retains the current node.- Returns:
- The new node, or
nullif the current node has no next node in theTreeWalker's logical view.
-