DOMNodeIterators are used to step through a set of nodes, e.g.
* the set of nodes in a DOMNodeList, the document subtree
* governed by a particular DOMNode, 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 DOMNodeIterator. DOM Level 2
* specifies a single DOMNodeIterator implementation for
* document-order traversal of a document subtree. Instances of these
* DOMNodeIterators are created by calling
* DOMDocumentTraversal.createNodeIterator().
* See also the Document Object Model (DOM) Level 2 Traversal and Range Specification.
* @since DOM Level 2
*/
class CDOM_EXPORT DOMNodeIterator
{
protected:
// -----------------------------------------------------------------------
// Hidden constructors
// -----------------------------------------------------------------------
/** @name Hidden constructors */
//@{
DOMNodeIterator() {};
//@}
private:
// -----------------------------------------------------------------------
// Unimplemented constructors and operators
// -----------------------------------------------------------------------
/** @name Unimplemented constructors and operators */
//@{
DOMNodeIterator(const DOMNodeIterator &);
DOMNodeIterator & operator = (const DOMNodeIterator &);
//@}
public:
// -----------------------------------------------------------------------
// All constructors are hidden, just the destructor is available
// -----------------------------------------------------------------------
/** @name Destructor */
//@{
/**
* Destructor
*
*/
virtual ~DOMNodeIterator() {};
//@}
// -----------------------------------------------------------------------
// Virtual DOMNodeFilter interface
// -----------------------------------------------------------------------
/** @name Functions introduced in DOM Level 2 */
//@{
// -----------------------------------------------------------------------
// Getter methods
// -----------------------------------------------------------------------
/**
* The root node of the DOMNodeIterator, as specified
* when it was created.
* @since DOM Level 2
*/
virtual DOMNode* getRoot() = 0;
/**
* Return which node types are presented via the iterator.
* This attribute determines which node types are presented via the
* DOMNodeIterator. The available set of constants is defined
* in the DOMNodeFilter interface. Nodes not accepted by
* whatToShow will be skipped, but their children may still
* be considered. Note that this skip takes precedence over the filter,
* if any.
* @since DOM Level 2
*
*/
virtual unsigned long getWhatToShow() = 0;
/**
* The DOMNodeFilter used to screen nodes.
*
* @since DOM Level 2
*/
virtual DOMNodeFilter* getFilter() = 0;
/**
* Return the expandEntityReferences flag.
* The value of this flag determines whether the children of entity
* reference nodes are visible to the DOMNodeIterator. If
* false, these children and their descendants will be rejected. Note
* that this rejection takes precedence over whatToShow and
* the filter. Also note that this is currently the only situation where
* DOMNodeIterators 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
* DOMNodeIterator. 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.
*
* @since DOM Level 2
*/
virtual bool getExpandEntityReferences() = 0;
// -----------------------------------------------------------------------
// Query methods
// -----------------------------------------------------------------------
/**
* Returns the next node in the set and advances the position of the
* DOMNodeIterator in the set. After a
* DOMNodeIterator is created, the first call to
* nextNode() returns the first node in the set.
* @return The next DOMNode in the set being iterated over, or
* null if there are no more members in that set.
* @exception DOMException
* INVALID_STATE_ERR: Raised if this method is called after the
* detach method was invoked.
* @since DOM Level 2
*/
virtual DOMNode* nextNode() = 0;
/**
* Returns the previous node in the set and moves the position of the
* DOMNodeIterator backwards in the set.
* @return The previous DOMNode in the set being iterated over,
* or null if there are no more members in that set.
* @exception DOMException
* INVALID_STATE_ERR: Raised if this method is called after the
* detach method was invoked.
* @since DOM Level 2
*/
virtual DOMNode* previousNode() = 0;
/**
* Detaches the DOMNodeIterator from the set which it iterated
* over, releasing any computational resources and placing the
* DOMNodeIterator in the INVALID state. After
* detach has been invoked, calls to nextNode
* or previousNode will raise the exception
* INVALID_STATE_ERR.
* @since DOM Level 2
*/
virtual void detach() = 0;
//@}
// -----------------------------------------------------------------------
// Non-standard Extension
// -----------------------------------------------------------------------
/** @name Non-standard Extension */
//@{
/**
* Called to indicate that this NodeIterator is no longer in use
* and that the implementation may relinquish any resources associated with it.
* (release() will call detach() where appropriate)
*
* Access to a released object will lead to unexpected result.
*/
virtual void release() = 0;
//@}
};
XERCES_CPP_NAMESPACE_END
#endif