DOMDocumentTraversal contains methods that create
* DOMNodeIterators and DOMTreeWalkers to traverse a
* node and its children in document order (depth first, pre-order
* traversal, which is equivalent to the order in which the start tags occur
* in the text representation of the document). In DOMs which support the
* Traversal feature, DOMDocumentTraversal will be implemented by
* the same objects that implement the DOMDocument interface.
* See also the Document Object Model (DOM) Level 2 Traversal and Range Specification.
* @since DOM Level 2
*/
class CDOM_EXPORT DOMDocumentTraversal {
protected:
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
/** @name Hidden constructors */
//@{
DOMDocumentTraversal() {};
DOMDocumentTraversal(const DOMDocumentTraversal &) {};
DOMDocumentTraversal & operator = (const DOMDocumentTraversal &) {return *this;};
//@}
public:
// -----------------------------------------------------------------------
// All constructors are hidden, just the destructor is available
// -----------------------------------------------------------------------
/** @name Destructor */
//@{
/**
* Destructor
*
*/
virtual ~DOMDocumentTraversal() {};
//@}
// -----------------------------------------------------------------------
// Virtual DOMDocumentRange interface
// -----------------------------------------------------------------------
/** @name Functions introduced in DOM Level 2 */
//@{
/**
* Creates a NodeIterator object. (DOM2)
*
* NodeIterators are used to step through a set of nodes, e.g. the set of nodes in a NodeList, the
* document 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 a document subtree.
* Instances of these iterators are created by calling DOMDocumentTraversal.createNodeIterator().
*
* 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.
*
* @param root The root node of the DOM tree
* @param whatToShow This attribute determines which node types are presented via the iterator.
* @param filter The filter used to screen nodes
* @param entityReferenceExpansion The value of this flag determines whether the children of entity reference nodes are
* visible to the iterator. If false, they will be skipped over.
* @since DOM Level 2
*/
virtual DOMNodeIterator *createNodeIterator(DOMNode *root,
unsigned long whatToShow,
DOMNodeFilter* filter,
bool entityReferenceExpansion) = 0;
/**
* Creates a TreeWalker object. (DOM2)
*
* TreeWalker objects are used to navigate a document tree or subtree using the view of the document defined
* by its whatToShow flags and any filters that are defined for the TreeWalker. 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 Filter that skips
* all nodes except for DOMText 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.
*
* 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 no entity expansion, use the
* whatToShow flags to show the entity reference node and set
* expandEntityReferences to false
*
* @param root The root node of the DOM tree
* @param whatToShow This attribute determines which node types are presented via the tree-walker.
* @param filter The filter used to screen nodes
* @param entityReferenceExpansion The value of this flag determines whether the children of entity reference nodes are
* visible to the tree-walker. If false, they will be skipped over.
* @since DOM Level 2
*/
virtual DOMTreeWalker *createTreeWalker(DOMNode *root,
unsigned long whatToShow,
DOMNodeFilter *filter,
bool entityReferenceExpansion) = 0;
//@}
};
XERCES_CPP_NAMESPACE_END
#endif