| Frames | No Frames |
1: /* 2: * Copyright (c) 2000 World Wide Web Consortium, 3: * (Massachusetts Institute of Technology, Institut National de 4: * Recherche en Informatique et en Automatique, Keio University). All 5: * Rights Reserved. This program is distributed under the W3C's Software 6: * Intellectual Property License. This program is distributed in the 7: * hope that it will be useful, but WITHOUT ANY WARRANTY; without even 8: * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 9: * PURPOSE. 10: * See W3C License http://www.w3.org/Consortium/Legal/ for more details. 11: */ 12: 13: package org.w3c.dom.traversal; 14: 15: import org.w3c.dom.Node; 16: import org.w3c.dom.DOMException; 17: 18: /** 19: * <code>TreeWalker</code> objects are used to navigate a document tree or 20: * subtree using the view of the document defined by their 21: * <code>whatToShow</code> flags and filter (if any). Any function which 22: * performs navigation using a <code>TreeWalker</code> will automatically 23: * support any view defined by a <code>TreeWalker</code>. 24: * <p>Omitting nodes from the logical view of a subtree can result in a 25: * structure that is substantially different from the same subtree in the 26: * complete, unfiltered document. Nodes that are siblings in the 27: * <code>TreeWalker</code> view may be children of different, widely 28: * separated nodes in the original view. For instance, consider a 29: * <code>NodeFilter</code> that skips all nodes except for Text nodes and 30: * the root node of a document. In the logical view that results, all text 31: * nodes will be siblings and appear as direct children of the root node, no 32: * matter how deeply nested the structure of the original document. 33: * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>. 34: * @since DOM Level 2 35: */ 36: public interface TreeWalker { 37: /** 38: * The <code>root</code> node of the <code>TreeWalker</code>, as specified 39: * when it was created. 40: */ 41: public Node getRoot(); 42: 43: /** 44: * This attribute determines which node types are presented via the 45: * <code>TreeWalker</code>. The available set of constants is defined in 46: * the <code>NodeFilter</code> interface. Nodes not accepted by 47: * <code>whatToShow</code> will be skipped, but their children may still 48: * be considered. Note that this skip takes precedence over the filter, 49: * if any. 50: */ 51: public int getWhatToShow(); 52: 53: /** 54: * The filter used to screen nodes. 55: */ 56: public NodeFilter getFilter(); 57: 58: /** 59: * The value of this flag determines whether the children of entity 60: * reference nodes are visible to the <code>TreeWalker</code>. If false, 61: * these children and their descendants will be rejected. Note that 62: * this rejection takes precedence over <code>whatToShow</code> and the 63: * filter, if any. 64: * <br> To produce a view of the document that has entity references 65: * expanded and does not expose the entity reference node itself, use 66: * the <code>whatToShow</code> flags to hide the entity reference node 67: * and set <code>expandEntityReferences</code> to true when creating the 68: * <code>TreeWalker</code>. To produce a view of the document that has 69: * entity reference nodes but no entity expansion, use the 70: * <code>whatToShow</code> flags to show the entity reference node and 71: * set <code>expandEntityReferences</code> to false. 72: */ 73: public boolean getExpandEntityReferences(); 74: 75: /** 76: * The node at which the <code>TreeWalker</code> is currently positioned. 77: * <br>Alterations to the DOM tree may cause the current node to no longer 78: * be accepted by the <code>TreeWalker</code>'s associated filter. 79: * <code>currentNode</code> may also be explicitly set to any node, 80: * whether or not it is within the subtree specified by the 81: * <code>root</code> node or would be accepted by the filter and 82: * <code>whatToShow</code> flags. Further traversal occurs relative to 83: * <code>currentNode</code> even if it is not part of the current view, 84: * by applying the filters in the requested direction; if no traversal 85: * is possible, <code>currentNode</code> is not changed. 86: */ 87: public Node getCurrentNode(); 88: /** 89: * The node at which the <code>TreeWalker</code> is currently positioned. 90: * <br>Alterations to the DOM tree may cause the current node to no longer 91: * be accepted by the <code>TreeWalker</code>'s associated filter. 92: * <code>currentNode</code> may also be explicitly set to any node, 93: * whether or not it is within the subtree specified by the 94: * <code>root</code> node or would be accepted by the filter and 95: * <code>whatToShow</code> flags. Further traversal occurs relative to 96: * <code>currentNode</code> even if it is not part of the current view, 97: * by applying the filters in the requested direction; if no traversal 98: * is possible, <code>currentNode</code> is not changed. 99: * @exception DOMException 100: * NOT_SUPPORTED_ERR: Raised if an attempt is made to set 101: * <code>currentNode</code> to <code>null</code>. 102: */ 103: public void setCurrentNode(Node currentNode) 104: throws DOMException; 105: 106: /** 107: * Moves to and returns the closest visible ancestor node of the current 108: * node. If the search for <code>parentNode</code> attempts to step 109: * upward from the <code>TreeWalker</code>'s <code>root</code> node, or 110: * if it fails to find a visible ancestor node, this method retains the 111: * current position and returns <code>null</code>. 112: * @return The new parent node, or <code>null</code> if the current node 113: * has no parent in the <code>TreeWalker</code>'s logical view. 114: */ 115: public Node parentNode(); 116: 117: /** 118: * Moves the <code>TreeWalker</code> to the first visible child of the 119: * current node, and returns the new node. If the current node has no 120: * visible children, returns <code>null</code>, and retains the current 121: * node. 122: * @return The new node, or <code>null</code> if the current node has no 123: * visible children in the <code>TreeWalker</code>'s logical view. 124: */ 125: public Node firstChild(); 126: 127: /** 128: * Moves the <code>TreeWalker</code> to the last visible child of the 129: * current node, and returns the new node. If the current node has no 130: * visible children, returns <code>null</code>, and retains the current 131: * node. 132: * @return The new node, or <code>null</code> if the current node has no 133: * children in the <code>TreeWalker</code>'s logical view. 134: */ 135: public Node lastChild(); 136: 137: /** 138: * Moves the <code>TreeWalker</code> to the previous sibling of the 139: * current node, and returns the new node. If the current node has no 140: * visible previous sibling, returns <code>null</code>, and retains the 141: * current node. 142: * @return The new node, or <code>null</code> if the current node has no 143: * previous sibling. in the <code>TreeWalker</code>'s logical view. 144: */ 145: public Node previousSibling(); 146: 147: /** 148: * Moves the <code>TreeWalker</code> to the next sibling of the current 149: * node, and returns the new node. If the current node has no visible 150: * next sibling, returns <code>null</code>, and retains the current node. 151: * @return The new node, or <code>null</code> if the current node has no 152: * next sibling. in the <code>TreeWalker</code>'s logical view. 153: */ 154: public Node nextSibling(); 155: 156: /** 157: * Moves the <code>TreeWalker</code> to the previous visible node in 158: * document order relative to the current node, and returns the new 159: * node. If the current node has no previous node, or if the search for 160: * <code>previousNode</code> attempts to step upward from the 161: * <code>TreeWalker</code>'s <code>root</code> node, returns 162: * <code>null</code>, and retains the current node. 163: * @return The new node, or <code>null</code> if the current node has no 164: * previous node in the <code>TreeWalker</code>'s logical view. 165: */ 166: public Node previousNode(); 167: 168: /** 169: * Moves the <code>TreeWalker</code> to the next visible node in document 170: * order relative to the current node, and returns the new node. If the 171: * current node has no next node, or if the search for nextNode attempts 172: * to step upward from the <code>TreeWalker</code>'s <code>root</code> 173: * node, returns <code>null</code>, and retains the current node. 174: * @return The new node, or <code>null</code> if the current node has no 175: * next node in the <code>TreeWalker</code>'s logical view. 176: */ 177: public Node nextNode(); 178: 179: }