2 * This file is part of the DOM implementation for KDE.
4 * Copyright 1999 Lars Knoll (knoll@kde.org)
5 * Copyright 2000 Frederik Holljen (frederik.holljen@hig.no)
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
16 * You should have received a copy of the GNU Library General Public License
17 * along with this library; see the file COPYING.LIB. If not, write to
18 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
21 * This file includes excerpts from the Document Object Model (DOM)
22 * Level 2 Specification (Candidate Recommendation)
23 * http://www.w3.org/TR/2000/CR-DOM-Level-2-20000510/
24 * Copyright © 2000 W3C® (MIT, INRIA, Keio), All Rights Reserved.
27 #ifndef _dom2_traversal_h_
28 #define _dom2_traversal_h_
30 #include <khtml_export.h>
31 #include <dom/dom_node.h>
32 #include <dom/dom_misc.h>
37 class NodeIteratorImpl
;
40 class CustomNodeFilter
;
41 class CustomNodeFilterImpl
;
44 * NodeIterators are used to step through a set of nodes, e.g. the set
45 * of nodes in a NodeList, the document subtree governed by a
46 * particular node, the results of a query, or any other set of nodes.
47 * The set of nodes to be iterated is determined by the implementation
48 * of the NodeIterator. DOM Level 2 specifies a single NodeIterator
49 * implementation for document-order traversal of a document subtree.
50 * Instances of these iterators are created by calling
51 * DocumentTraversal.createNodeIterator().
53 * Any Iterator that returns nodes may implement the
54 * \c NodeIterator interface. Users and vendor libraries may also
55 * choose to create Iterators that implement the \c NodeIterator
59 class KHTML_EXPORT NodeIterator
61 friend class NodeIteratorImpl
;
62 friend class Document
;
65 NodeIterator(const NodeIterator
&other
);
67 NodeIterator
& operator = (const NodeIterator
&other
);
72 * The root node of the NodeIterator, as specified when it was created.
77 * This attribute determines which node types are presented via the
78 * iterator. The available set of constants is defined in the NodeFilter
79 * interface. Nodes not accepted by whatToShow will be skipped, but their
80 * children may still be considered. Note that this skip takes precedence
81 * over the filter, if any.
83 unsigned long whatToShow();
86 * The NodeFilter used to screen nodes.
91 * The value of this flag determines whether the children of entity
92 * reference nodes are visible to the iterator. If false, they and
93 * their descendents will be rejected. Note that this rejection takes
94 * precedence over whatToShow and the filter. Also note that this is
95 * currently the only situation where NodeIterators may reject a complete
96 * subtree rather than skipping individual nodes.
98 * To produce a view of the document that has entity references expanded
99 * and does not expose the entity reference node itself, use the whatToShow
100 * flags to hide the entity reference node and set expandEntityReferences to
101 * true when creating the iterator. To produce a view of the document that
102 * has entity reference nodes but no entity expansion, use the whatToShow
103 * flags to show the entity reference node and set expandEntityReferences to
106 bool expandEntityReferences();
109 * Returns the next node in the set and advances the position of
110 * the Iterator in the set. After a NodeIterator is created, the
111 * first call to nextNode() returns the first node in the set.
113 * @return The next \c Node in the set being iterated
114 * over, or \c null if there are no more members in
117 * @exception Exceptions from user code
118 * Any exceptions raised by a user-written Filter will propagate
125 * Returns the previous node in the set and moves the position of
126 * the Iterator backwards in the set.
128 * @return The previous \c Node in the set being
129 * iterated over, or \c null if there are no more
130 * members in that set.
132 * @exception Exceptions from user code
133 * Any exceptions raised by a user-written Filter will propagate
140 * Detaches the NodeIterator from the set which it iterated over,
141 * releasing any computational resources and placing the iterator in the
142 * INVALID state. After detach has been invoked, calls to nextNode or
143 * previousNode will raise the exception INVALID_STATE_ERR.
149 * not part of the DOM
151 NodeIteratorImpl
*handle() const;
155 NodeIteratorImpl
*impl
;
156 NodeIterator(NodeIteratorImpl
*i
);
161 * Filters are objects that know how to "filter out" nodes. If an
162 * Iterator or \c TreeWalker is given a filter, before it
163 * returns the next node, it applies the filter. If the filter says to
164 * accept the node, the Iterator returns it; otherwise, the Iterator
165 * looks for the next node and pretends that the node that was
166 * rejected was not there.
168 * The DOM does not provide any filters. Filter is just an interface
169 * that users can implement to provide their own filters.
171 * Filters do not need to know how to iterate, nor do they need to
172 * know anything about the data structure that is being iterated. This
173 * makes it very easy to write filters, since the only thing they have
174 * to know how to do is evaluate a single node. One filter may be used
175 * with a number of different kinds of Iterators, encouraging code
178 * To create your own custom NodeFilter, define a subclass of
179 * CustomNodeFilter which overrides the acceptNode() method and assign
180 * an instance of it to the NodeFilter. For more details see the
181 * CustomNodeFilter class
183 class KHTML_EXPORT NodeFilter
185 friend class NodeIterator
;
186 friend class NodeIteratorImpl
;
187 friend class TreeWalker
;
188 friend class TreeWalkerImpl
;
189 friend class NodeFilterImpl
;
192 NodeFilter(const NodeFilter
&other
);
193 NodeFilter(NodeFilterImpl
*i
);
195 virtual NodeFilter
& operator = (const NodeFilter
&other
);
197 virtual ~NodeFilter();
199 * The following constants are returned by the acceptNode()
210 * These are the available values for the whatToShow parameter.
211 * They are the same as the set of possible types for Node, and
212 * their values are derived by using a bit position corresponding
213 * to the value of NodeType for the equivalent node type.
217 SHOW_ALL
= 0xFFFFFFFF,
218 SHOW_ELEMENT
= 0x00000001,
219 SHOW_ATTRIBUTE
= 0x00000002,
220 SHOW_TEXT
= 0x00000004,
221 SHOW_CDATA_SECTION
= 0x00000008,
222 SHOW_ENTITY_REFERENCE
= 0x00000010,
223 SHOW_ENTITY
= 0x00000020,
224 SHOW_PROCESSING_INSTRUCTION
= 0x00000040,
225 SHOW_COMMENT
= 0x00000080,
226 SHOW_DOCUMENT
= 0x00000100,
227 SHOW_DOCUMENT_TYPE
= 0x00000200,
228 SHOW_DOCUMENT_FRAGMENT
= 0x00000400,
229 SHOW_NOTATION
= 0x00000800
233 * Test whether a specified node is visible in the logical view of
234 * a TreeWalker or NodeIterator. This function will be called by
235 * the implementation of TreeWalker and NodeIterator; it is not
236 * intended to be called directly from user code.
238 * @param n The node to check to see if it passes the filter or
241 * @return a constant to determine whether the node is accepted,
242 * rejected, or skipped, as defined <a
243 * href="#Traversal-NodeFilter-acceptNode-constants"> above </a> .
246 virtual short acceptNode (const Node
&n
);
250 * not part of the DOM
252 virtual NodeFilterImpl
*handle() const;
253 virtual bool isNull() const;
255 void setCustomNodeFilter(CustomNodeFilter
*custom
);
256 CustomNodeFilter
*customNodeFilter();
257 static NodeFilter
createCustom(CustomNodeFilter
*custom
);
260 NodeFilterImpl
*impl
;
264 * CustomNodeFilter can be used to define your own NodeFilter for use
265 * with NodeIterators and TreeWalkers. You can create a custom filter
266 * by doing the following:
268 * class MyCustomNodeFilter {
270 * virtual short acceptNode (const Node &n);
274 * Then in your program:
276 * short MyCustomNodeFilter::acceptNode (const Node &n)
279 * return NodeFilter::FILTER_ACCEPT;
285 * MyCustomFilter *filter = new MyCustomFilter();
286 * NodeFilter nf = NodeFilter::createCustom(filter);
287 * NodeIterator ni = document.createNodeIterator(document,NodeFilter.SHOW_ALL,nf,false);
289 * The default implementation of acceptNode() returns NodeFilter::FILTER_ACCEPT
294 class KHTML_EXPORT CustomNodeFilter
: public DomShared
{
297 virtual ~CustomNodeFilter();
298 virtual short acceptNode (const Node
&n
);
299 virtual bool isNull();
303 * not part of the DOM
305 * Returns a name specifying the type of custom node filter. Useful for checking
306 * if an custom node filter is of a particular sublass.
309 virtual DOMString
customNodeFilterType();
314 * Reserved. Do not use in your subclasses.
316 CustomNodeFilterImpl
*impl
;
320 * \c TreeWalker objects are used to navigate a document
321 * tree or subtree using the view of the document defined by its
322 * \c whatToShow flags and any filters that are defined
323 * for the \c TreeWalker . Any function which performs
324 * navigation using a \c TreeWalker will automatically
325 * support any view defined by a \c TreeWalker .
327 * Omitting nodes from the logical view of a subtree can result in a
328 * structure that is substantially different from the same subtree in
329 * the complete, unfiltered document. Nodes that are siblings in the
330 * TreeWalker view may be children of different, widely separated
331 * nodes in the original view. For instance, consider a Filter that
332 * skips all nodes except for Text nodes and the root node of a
333 * document. In the logical view that results, all text nodes will be
334 * siblings and appear as direct children of the root node, no matter
335 * how deeply nested the structure of the original document.
338 class KHTML_EXPORT TreeWalker
340 friend class Document
;
341 friend class TreeWalkerImpl
;
344 TreeWalker(const TreeWalker
&other
);
346 TreeWalker
& operator = (const TreeWalker
&other
);
352 * The root node of the TreeWalker, as specified when it was created.
357 * This attribute determines which node types are presented via the
358 * TreeWalker. The available set of constants is defined in the NodeFilter
359 * interface. Nodes not accepted by whatToShow will be skipped, but their
360 * children may still be considered. Note that this skip takes precedence
361 * over the filter, if any.
363 unsigned long whatToShow();
366 * The filter used to screen nodes.
371 * The value of this flag determines whether the children of entity
372 * reference nodes are visible to the TreeWalker. If false, they and their
373 * descendents will be rejected. Note that this rejection takes precedence
374 * over whatToShow and the filter, if any.
376 * To produce a view of the document that has entity references expanded
377 * and does not expose the entity reference node itself, use the whatToShow
378 * flags to hide the entity reference node and set expandEntityReferences
379 * to true when creating the TreeWalker. To produce a view of the document
380 * that has entity reference nodes but no entity expansion, use the
381 * whatToShow flags to show the entity reference node and set
382 * expandEntityReferences to false.
384 bool expandEntityReferences();
387 * The node at which the TreeWalker is currently positioned.
388 * Alterations to the DOM tree may cause the current node to no longer be
389 * accepted by the TreeWalker's associated filter. currentNode may also be
390 * explicitly set to any node, whether or not it is within the subtree
391 * specified by the root node or would be accepted by the filter and
392 * whatToShow flags. Further traversal occurs relative to currentNode even
393 * if it is not part of the current view, by applying the filters in the
394 * requested direction; if no traversal is possible, currentNode is not changed.
396 * @exception DOMException
397 * NOT_SUPPORTED_ERR: Raised if an attempt is made to set currentNode to null.
404 void setCurrentNode(const Node
&_currentNode
);
407 * Moves to and returns the parent node of the current node. If
408 * there is no parent node, or if the current node is the root
409 * node from which this TreeWalker was created, retains the
410 * current position and returns null.
412 * @return The new parent node, or null if the current node has no
413 * parent in the TreeWalker's logical view.
415 * @exception Exceptions from user code
416 * Any exceptions raised by a user-written Filter will propagate
423 * Moves the \c TreeWalker to the first child of the
424 * current node, and returns the new node. If the current node has
425 * no children, returns \c null , and retains the
428 * @return The new node, or \c null if the current
429 * node has no children.
431 * @exception Exceptions from user code
432 * Any exceptions raised by a user-written Filter will propagate
439 * Moves the \c TreeWalker to the last child of the
440 * current node, and returns the new node. If the current node has
441 * no children, returns \c null , and retains the
444 * @return The new node, or \c null if the current
445 * node has no children.
447 * @exception Exceptions from user code
448 * Any exceptions raised by a user-written Filter will propagate
455 * Moves the \c TreeWalker to the previous sibling of
456 * the current node, and returns the new node. If the current node
457 * has no previous sibling, returns \c null , and
458 * retains the current node.
460 * @return The new node, or \c null if the current
461 * node has no previous sibling.
463 * @exception Exceptions from user code
464 * Any exceptions raised by a user-written Filter will propagate
468 Node
previousSibling();
471 * Moves the \c TreeWalker to the next sibling of the
472 * current node, and returns the new node. If the current node has
473 * no next sibling, returns \c null , and retains the
476 * @return The new node, or \c null if the current
477 * node has no next sibling.
479 * @exception Exceptions from user code
480 * Any exceptions raised by a user-written Filter will propagate
487 * Moves the \c TreeWalker to the previous node in
488 * document order relative to the current node, and returns the
489 * new node. If the current node has no previous node, returns
490 * \c null , and retains the current node.
492 * @return The new node, or \c null if the current
493 * node has no previous node.
495 * @exception Exceptions from user code
496 * Any exceptions raised by a user-written Filter will propagate
503 * Moves the \c TreeWalker to the next node in
504 * document order relative to the current node, and returns the
505 * new node. If the current node has no next node, returns
506 * \c null , and retains the current node.
508 * @return The new node, or \c null if the current
509 * node has no next node.
511 * @exception Exceptions from user code
512 * Any exceptions raised by a user-written Filter will propagate
520 * not part of the DOM
522 TreeWalkerImpl
*handle() const;
526 TreeWalker(TreeWalkerImpl
*i
);
527 TreeWalkerImpl
*impl
;