diff options
Diffstat (limited to 'khtml/dom/dom2_traversal.h')
| -rw-r--r-- | khtml/dom/dom2_traversal.h | 617 |
1 files changed, 617 insertions, 0 deletions
diff --git a/khtml/dom/dom2_traversal.h b/khtml/dom/dom2_traversal.h new file mode 100644 index 000000000..d2d3abf48 --- /dev/null +++ b/khtml/dom/dom2_traversal.h @@ -0,0 +1,617 @@ +/* + * 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 © 2000 W3C® (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 contains 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 |