You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdelibs/khtml/dom/dom2_traversal.h

618 lines
20 KiB

/*
* This file is part of the DOM implementation for KDE.
*
* (C) 1999 Lars Knoll (knoll@kde.org)
* (C) 2000 Frederik Holljen (frederik.holljen@hig.no)
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public License
* along with this library; see the file COPYING.LIB. If not, write to
* the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301, USA.
*
* This file includes excerpts from the Document Object Model (DOM)
* Level 2 Specification (Candidate Recommendation)
* http://www.w3.org/TR/2000/CR-DOM-Level-2-20000510/
* Copyright <EFBFBD> 2000 W3C<EFBFBD> (MIT, INRIA, Keio), All Rights Reserved.
*
*/
#ifndef _dom2_traversal_h_
#define _dom2_traversal_h_
#include <dom/dom_node.h>
#include <dom/dom_misc.h>
#include <kdelibs_export.h>
namespace DOM {
class Node;
class NodeFilter;
class NodeImpl;
class NodeIteratorImpl;
class NodeFilterImpl;
class TreeWalkerImpl;
class CustomNodeFilter;
class CustomNodeFilterImpl;
/**
* 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
* DocumentTraversal.createNodeIterator().
*
* Any Iterator that returns nodes may implement the
* \c NodeIterator interface. Users and vendor libraries may also
* choose to create Iterators that implement the \c NodeIterator
* interface.
*
*/
class KHTML_EXPORT NodeIterator
{
friend class NodeIteratorImpl;
friend class Document;
public:
NodeIterator();
NodeIterator(const NodeIterator &other);
NodeIterator & operator = (const NodeIterator &other);
~NodeIterator();
/**
* The root node of the NodeIterator, as specified when it was created.
*/
Node root();
/**
* This attribute determines which node types are presented via the
* iterator. The available set of constants is defined in the NodeFilter
* 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.
*/
unsigned long whatToShow();
/**
* The NodeFilter used to screen nodes.
*/
NodeFilter filter();
/**
* The value of this flag determines whether the children of entity
* reference nodes are visible to the iterator. If false, they and
* their descendents will be rejected. Note that this rejection takes
* precedence over whatToShow and the filter. Also note that this is
* currently 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.
*/
bool expandEntityReferences();
/**
* 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 The next \c Node in the set being iterated
* over, or \c null if there are no more members in
* that set.
*
* @exception Exceptions from user code
* Any exceptions raised by a user-written Filter will propagate
* through.
*
*/
Node nextNode();
/**
* Returns the previous node in the set and moves the position of
* the Iterator backwards in the set.
*
* @return The previous \c Node in the set being
* iterated over, or \c null if there are no more
* members in that set.
*
* @exception Exceptions from user code
* Any exceptions raised by a user-written Filter will propagate
* through.
*
*/
Node previousNode();
/**
* Detaches 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.
*/
void detach();
/**
* @internal
* not part of the DOM
*/
NodeIteratorImpl *handle() const;
bool isNull() const;
protected:
NodeIteratorImpl *impl;
NodeIterator(NodeIteratorImpl *i);
};
/**
* Filters are objects that know how to "filter out" nodes. If an
* Iterator or \c TreeWalker is given a filter, before it
* returns the next node, it applies the filter. If the filter says to
* accept the node, the Iterator returns it; otherwise, the Iterator
* looks for the next node and pretends that the node that was
* rejected was not there.
*
* The DOM does not provide any filters. Filter is just an interface
* that users can implement to provide their own filters.
*
* Filters do not need to know how to iterate, nor do they need to
* know anything about the data structure that is being iterated. 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 a number of different kinds of Iterators, encouraging code
* reuse.
*
* To create your own custom NodeFilter, define a subclass of
* CustomNodeFilter which overrides the acceptNode() method and assign
* an instance of it to the NodeFilter. For more details see the
* CustomNodeFilter class
*/
class KHTML_EXPORT NodeFilter
{
friend class NodeIterator;
friend class NodeIteratorImpl;
friend class TreeWalker;
friend class TreeWalkerImpl;
friend class NodeFilterImpl;
public:
NodeFilter();
NodeFilter(const NodeFilter &other);
NodeFilter(NodeFilterImpl *i);
virtual NodeFilter & operator = (const NodeFilter &other);
virtual ~NodeFilter();
/**
* The following constants are returned by the acceptNode()
* method:
*
*/
enum AcceptCode {
FILTER_ACCEPT = 1,
FILTER_REJECT = 2,
FILTER_SKIP = 3
};
/**
* These are the available values for the whatToShow parameter.
* They are the same as the set of possible types for Node, and
* their values are derived by using a bit position corresponding
* to the value of NodeType for the equivalent node type.
*
*/
enum ShowCode {
SHOW_ALL = 0xFFFFFFFF,
SHOW_ELEMENT = 0x00000001,
SHOW_ATTRIBUTE = 0x00000002,
SHOW_TEXT = 0x00000004,
SHOW_CDATA_SECTION = 0x00000008,
SHOW_ENTITY_REFERENCE = 0x00000010,
SHOW_ENTITY = 0x00000020,
SHOW_PROCESSING_INSTRUCTION = 0x00000040,
SHOW_COMMENT = 0x00000080,
SHOW_DOCUMENT = 0x00000100,
SHOW_DOCUMENT_TYPE = 0x00000200,
SHOW_DOCUMENT_FRAGMENT = 0x00000400,
SHOW_NOTATION = 0x00000800
};
/**
* Test whether a specified node is visible in the logical view of
* a TreeWalker or NodeIterator. This function will be called by
* the implementation of TreeWalker and NodeIterator; it is not
* intended to be called directly from user code.
*
* @param n The node to check to see if it passes the filter or
* not.
*
* @return a constant to determine whether the node is accepted,
* rejected, or skipped, as defined <a
* href="#Traversal-NodeFilter-acceptNode-constants"> above </a> .
*
*/
virtual short acceptNode (const Node &n);
/**
* @internal
* not part of the DOM
*/
virtual NodeFilterImpl *handle() const;
virtual bool isNull() const;
void setCustomNodeFilter(CustomNodeFilter *custom);
CustomNodeFilter *customNodeFilter();
static NodeFilter createCustom(CustomNodeFilter *custom);
protected:
NodeFilterImpl *impl;
};
/**
* CustomNodeFilter can be used to define your own NodeFilter for use
* with NodeIterators and TreeWalkers. You can create a custom filter
* by doing the following:
*
* class MyCustomNodeFilter {
* .....
* virtual short acceptNode (const Node &n);
* .....
* }
*
* Then in your program:
*
* short MyCustomNodeFilter::acceptNode (const Node &n)
* {
* if (condition)
* return NodeFilter::FILTER_ACCEPT;
* else
* ....
* }
*
*
* MyCustomFilter *filter = new MyCustomFilter();
* NodeFilter nf = NodeFilter::createCustom(filter);
* NodeIterator ni = document.createNodeIterator(document,NodeFilter.SHOW_ALL,nf,false);
*
* The default implementation of acceptNode() returns NodeFilter::FILTER_ACCEPT
* for all nodes.
*
*/
class KHTML_EXPORT CustomNodeFilter : public DomShared {
public:
CustomNodeFilter();
virtual ~CustomNodeFilter();
virtual short acceptNode (const Node &n);
virtual bool isNull();
/**
* @internal
* not part of the DOM
*
* Returns a name specifying the type of custom node filter. Useful for checking
* if an custom node filter is of a particular sublass.
*
*/
virtual DOMString customNodeFilterType();
protected:
/**
* @internal
* Reserved. Do not use in your subclasses.
*/
CustomNodeFilterImpl *impl;
};
/**
* \c TreeWalker objects are used to navigate a document
* tree or subtree using the view of the document defined by its
* \c whatToShow flags and any filters that are defined
* for the \c TreeWalker . Any function which performs
* navigation using a \c TreeWalker will automatically
* support any view defined by a \c 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 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.
*
*/
class KHTML_EXPORT TreeWalker
{
friend class Document;
friend class TreeWalkerImpl;
public:
TreeWalker();
TreeWalker(const TreeWalker &other);
TreeWalker & operator = (const TreeWalker &other);
~TreeWalker();
/**
* The root node of the TreeWalker, as specified when it was created.
*/
Node root();
/**
* This attribute determines which node types are presented via the
* TreeWalker. The available set of constants is defined in the NodeFilter
* 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.
*/
unsigned long whatToShow();
/**
* The filter used to screen nodes.
*/
NodeFilter filter();
/**
* The value of this flag determines whether the children of entity
* reference nodes are visible to the TreeWalker. If false, they and their
* descendents 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 no entity expansion, use the
* whatToShow flags to show the entity reference node and set
* expandEntityReferences to false.
*/
bool expandEntityReferences();
/**
* 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 currentNode even
* if it is not part of the current view, by applying the filters in the
* requested direction; if no traversal is possible, currentNode is not changed.
*
* @exception DOMException
* NOT_SUPPORTED_ERR: Raised if an attempt is made to set currentNode to null.
*/
Node currentNode();
/**
* see currentNode
*/
void setCurrentNode(const Node &_currentNode);
/**
* Moves to and returns the parent node of the current node. If
* there is no parent node, or if the current node is the root
* node from which this TreeWalker was created, retains the
* current position and returns null.
*
* @return The new parent node, or null if the current node has no
* parent in the TreeWalker's logical view.
*
* @exception Exceptions from user code
* Any exceptions raised by a user-written Filter will propagate
* through.
*
*/
Node parentNode();
/**
* Moves the \c TreeWalker to the first child of the
* current node, and returns the new node. If the current node has
* no children, returns \c null , and retains the
* current node.
*
* @return The new node, or \c null if the current
* node has no children.
*
* @exception Exceptions from user code
* Any exceptions raised by a user-written Filter will propagate
* through.
*
*/
Node firstChild();
/**
* Moves the \c TreeWalker to the last child of the
* current node, and returns the new node. If the current node has
* no children, returns \c null , and retains the
* current node.
*
* @return The new node, or \c null if the current
* node has no children.
*
* @exception Exceptions from user code
* Any exceptions raised by a user-written Filter will propagate
* through.
*
*/
Node lastChild();
/**
* Moves the \c TreeWalker to the previous sibling of
* the current node, and returns the new node. If the current node
* has no previous sibling, returns \c null , and
* retains the current node.
*
* @return The new node, or \c null if the current
* node has no previous sibling.
*
* @exception Exceptions from user code
* Any exceptions raised by a user-written Filter will propagate
* through.
*
*/
Node previousSibling();
/**
* Moves the \c TreeWalker to the next sibling of the
* current node, and returns the new node. If the current node has
* no next sibling, returns \c null , and retains the
* current node.
*
* @return The new node, or \c null if the current
* node has no next sibling.
*
* @exception Exceptions from user code
* Any exceptions raised by a user-written Filter will propagate
* through.
*
*/
Node nextSibling();
/**
* Moves the \c TreeWalker to the previous node in
* document order relative to the current node, and returns the
* new node. If the current node has no previous node, returns
* \c null , and retains the current node.
*
* @return The new node, or \c null if the current
* node has no previous node.
*
* @exception Exceptions from user code
* Any exceptions raised by a user-written Filter will propagate
* through.
*
*/
Node previousNode();
/**
* Moves the \c TreeWalker to the next node in
* document order relative to the current node, and returns the
* new node. If the current node has no next node, returns
* \c null , and retains the current node.
*
* @return The new node, or \c null if the current
* node has no next node.
*
* @exception Exceptions from user code
* Any exceptions raised by a user-written Filter will propagate
* through.
*
*/
Node nextNode();
/**
* @internal
* not part of the DOM
*/
TreeWalkerImpl *handle() const;
bool isNull() const;
protected:
TreeWalker(TreeWalkerImpl *i);
TreeWalkerImpl *impl;
};
// ### not sure if this this class is really needed - both methods are in
// Document
/**
* \c DocumentTraversal tqcontains methods that creates
* Iterators 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).
*
*
class DocumentTraversal // : public Document ?
{
public:
DocumentTraversal();
DocumentTraversal(const DocumentTraversal &other);
DocumentTraversal & operator = (const DocumentTraversal &other);
~DocumentTraversal();
**
*
*
* @param root 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 not
* considered when setting this position.
*
* @param whatToShow This flag specifies which node types may
* appear in the logical view of the tree presented by the
* Iterator. See the description of Iterator for the set of
* possible values. These flags can be combined using OR.
*
* These flags can be combined using \c OR .
*
* @param filter The Filter to be used with this TreeWalker, or
* null to indicate no filter.
*
* @param entityReferenceExpansion The value of this flag
* determines whether entity reference nodes are expanded.
*
* @return The newly created \c NodeIterator .
*
*
NodeIterator createNodeIterator ( const Node &root, long whatToShow,
const NodeFilter &filter, bool entityReferenceExpansion );
**
* Create a new TreeWalker over the subtree rooted by the
* specified node.
*
* @param root The node which will serve as the root for the
* \c TreeWalker . The currentNode of the TreeWalker
* is set to this node. The whatToShow flags and the NodeFilter
* are not considered when setting this value; any node type will
* be accepted as the root. The root must not be null.
*
* @param whatToShow This flag specifies which node types may
* appear in the logical view of the tree presented by the
* Iterator. See the description of TreeWalker for the set of
* possible values. These flags can be combined using OR.
*
* These flags can be combined using \c OR .
*
* @param filter The Filter to be used with this TreeWalker, or
* null to indicate no filter.
*
* @param entityReferenceExpansion The value of this flag
* determines whether entity reference nodes are expanded.
*
* @return The newly created \c TreeWalker .
*
* @exception DOMException
* Raises the exception NOT_SUPPORTED_ERR if the specified root
* node is null.
*
*
TreeWalker createTreeWalker ( const Node &root, long whatToShow,
const NodeFilter &filter, bool entityReferenceExpansion );
};
*/
} // namespace
#endif