KHtml

dom2_traversal.h
1 /*
2  * This file is part of the DOM implementation for KDE.
3  *
4  * Copyright 1999 Lars Knoll ([email protected])
5  * Copyright 2000 Frederik Holljen ([email protected])
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.
10  *
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.
15  *
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.
20  *
21  * This file includes excerpts from the Document Object Model (DOM)
22  * Level 2 Specification (Candidate Recommendation)
23  * https://www.w3.org/TR/2000/CR-DOM-Level-2-20000510/
24  * Copyright © 2000 W3C® (MIT, INRIA, Keio), All Rights Reserved.
25  *
26  */
27 #ifndef _dom2_traversal_h_
28 #define _dom2_traversal_h_
29 
30 #include <khtml_export.h>
31 #include <dom/dom_node.h>
32 #include <dom/dom_misc.h>
33 
34 namespace DOM
35 {
36 class Node;
37 class NodeFilter;
38 class NodeIteratorImpl;
39 class NodeFilterImpl;
40 class TreeWalkerImpl;
41 class CustomNodeFilter;
42 class CustomNodeFilterImpl;
43 
44 /**
45  * NodeIterators are used to step through a set of nodes, e.g. the set
46  * of nodes in a NodeList, the document subtree governed by a
47  * particular node, the results of a query, or any other set of nodes.
48  * The set of nodes to be iterated is determined by the implementation
49  * of the NodeIterator. DOM Level 2 specifies a single NodeIterator
50  * implementation for document-order traversal of a document subtree.
51  * Instances of these iterators are created by calling
52  * DocumentTraversal.createNodeIterator().
53  *
54  * Any Iterator that returns nodes may implement the
55  * \c NodeIterator interface. Users and vendor libraries may also
56  * choose to create Iterators that implement the \c NodeIterator
57  * interface.
58  *
59  */
60 class KHTML_EXPORT NodeIterator
61 {
62  friend class NodeIteratorImpl;
63  friend class Document;
64 public:
65  NodeIterator();
66  NodeIterator(const NodeIterator &other);
67 
68  NodeIterator &operator = (const NodeIterator &other);
69 
70  ~NodeIterator();
71 
72  /**
73  * The root node of the NodeIterator, as specified when it was created.
74  */
75  Node root();
76 
77  /**
78  * This attribute determines which node types are presented via the
79  * iterator. The available set of constants is defined in the NodeFilter
80  * interface. Nodes not accepted by whatToShow will be skipped, but their
81  * children may still be considered. Note that this skip takes precedence
82  * over the filter, if any.
83  */
84  unsigned long whatToShow();
85 
86  /**
87  * The NodeFilter used to screen nodes.
88  */
89  NodeFilter filter();
90 
91  /**
92  * The value of this flag determines whether the children of entity
93  * reference nodes are visible to the iterator. If false, they and
94  * their descendents will be rejected. Note that this rejection takes
95  * precedence over whatToShow and the filter. Also note that this is
96  * currently the only situation where NodeIterators may reject a complete
97  * subtree rather than skipping individual nodes.
98  *
99  * To produce a view of the document that has entity references expanded
100  * and does not expose the entity reference node itself, use the whatToShow
101  * flags to hide the entity reference node and set expandEntityReferences to
102  * true when creating the iterator. To produce a view of the document that
103  * has entity reference nodes but no entity expansion, use the whatToShow
104  * flags to show the entity reference node and set expandEntityReferences to
105  * false.
106  */
107  bool expandEntityReferences();
108 
109  /**
110  * Returns the next node in the set and advances the position of
111  * the Iterator in the set. After a NodeIterator is created, the
112  * first call to nextNode() returns the first node in the set.
113  *
114  * @return The next \c Node in the set being iterated
115  * over, or \c null if there are no more members in
116  * that set.
117  *
118  * @exception Exceptions from user code
119  * Any exceptions raised by a user-written Filter will propagate
120  * through.
121  *
122  */
123  Node nextNode();
124 
125  /**
126  * Returns the previous node in the set and moves the position of
127  * the Iterator backwards in the set.
128  *
129  * @return The previous \c Node in the set being
130  * iterated over, or \c null if there are no more
131  * members in that set.
132  *
133  * @exception Exceptions from user code
134  * Any exceptions raised by a user-written Filter will propagate
135  * through.
136  *
137  */
138  Node previousNode();
139 
140  /**
141  * Detaches the NodeIterator from the set which it iterated over,
142  * releasing any computational resources and placing the iterator in the
143  * INVALID state. After detach has been invoked, calls to nextNode or
144  * previousNode will raise the exception INVALID_STATE_ERR.
145  */
146  void detach();
147 
148  /**
149  * @internal
150  * not part of the DOM
151  */
152  NodeIteratorImpl *handle() const;
153  bool isNull() const;
154 
155 protected:
156  NodeIteratorImpl *impl;
157  NodeIterator(NodeIteratorImpl *i);
158 };
159 
160 /**
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.
167  *
168  * The DOM does not provide any filters. Filter is just an interface
169  * that users can implement to provide their own filters.
170  *
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
176  * reuse.
177  *
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
182  */
183 class KHTML_EXPORT NodeFilter
184 {
185  friend class NodeIterator;
186  friend class NodeIteratorImpl;
187  friend class TreeWalker;
188  friend class TreeWalkerImpl;
189  friend class NodeFilterImpl;
190 public:
191  NodeFilter();
192  NodeFilter(const NodeFilter &other);
193  NodeFilter(NodeFilterImpl *i);
194 
195  virtual NodeFilter &operator = (const NodeFilter &other);
196 
197  virtual ~NodeFilter();
198  /**
199  * The following constants are returned by the acceptNode()
200  * method:
201  *
202  */
203  enum AcceptCode {
204  FILTER_ACCEPT = 1,
205  FILTER_REJECT = 2,
206  FILTER_SKIP = 3
207  };
208 
209  /**
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.
214  *
215  */
216  enum ShowCode {
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
230  };
231 
232  /**
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.
237  *
238  * @param n The node to check to see if it passes the filter or
239  * not.
240  *
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> .
244  *
245  */
246  virtual short acceptNode(const Node &n);
247 
248  /**
249  * @internal
250  * not part of the DOM
251  */
252  virtual NodeFilterImpl *handle() const;
253  virtual bool isNull() const;
254 
255  void setCustomNodeFilter(CustomNodeFilter *custom);
256  CustomNodeFilter *customNodeFilter();
257  static NodeFilter createCustom(CustomNodeFilter *custom);
258 
259 protected:
260  NodeFilterImpl *impl;
261 };
262 
263 /**
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:
267  *
268  * class MyCustomNodeFilter {
269  * .....
270  * virtual short acceptNode (const Node &n);
271  * .....
272  * }
273  *
274  * Then in your program:
275  *
276  * short MyCustomNodeFilter::acceptNode (const Node &n)
277  * {
278  * if (condition)
279  * return NodeFilter::FILTER_ACCEPT;
280  * else
281  * ....
282  * }
283  *
284  *
285  * MyCustomFilter *filter = new MyCustomFilter();
286  * NodeFilter nf = NodeFilter::createCustom(filter);
287  * NodeIterator ni = document.createNodeIterator(document,NodeFilter.SHOW_ALL,nf,false);
288  *
289  * The default implementation of acceptNode() returns NodeFilter::FILTER_ACCEPT
290  * for all nodes.
291  *
292  */
293 
294 class KHTML_EXPORT CustomNodeFilter : public DomShared
295 {
296 public:
298  virtual ~CustomNodeFilter();
299  virtual short acceptNode(const Node &n);
300  virtual bool isNull();
301 
302  /**
303  * @internal
304  * not part of the DOM
305  *
306  * Returns a name specifying the type of custom node filter. Useful for checking
307  * if an custom node filter is of a particular sublass.
308  *
309  */
310  virtual DOMString customNodeFilterType();
311 
312 protected:
313  /**
314  * @internal
315  * Reserved. Do not use in your subclasses.
316  */
317  CustomNodeFilterImpl *impl;
318 };
319 
320 /**
321  * \c TreeWalker objects are used to navigate a document
322  * tree or subtree using the view of the document defined by its
323  * \c whatToShow flags and any filters that are defined
324  * for the \c TreeWalker . Any function which performs
325  * navigation using a \c TreeWalker will automatically
326  * support any view defined by a \c TreeWalker .
327  *
328  * Omitting nodes from the logical view of a subtree can result in a
329  * structure that is substantially different from the same subtree in
330  * the complete, unfiltered document. Nodes that are siblings in the
331  * TreeWalker view may be children of different, widely separated
332  * nodes in the original view. For instance, consider a Filter that
333  * skips all nodes except for Text nodes and the root node of a
334  * document. In the logical view that results, all text nodes will be
335  * siblings and appear as direct children of the root node, no matter
336  * how deeply nested the structure of the original document.
337  *
338  */
339 class KHTML_EXPORT TreeWalker
340 {
341  friend class Document;
342  friend class TreeWalkerImpl;
343 public:
344  TreeWalker();
345  TreeWalker(const TreeWalker &other);
346 
347  TreeWalker &operator = (const TreeWalker &other);
348 
349  ~TreeWalker();
350 
351  /**
352  * The root node of the TreeWalker, as specified when it was created.
353  */
354  Node root();
355 
356  /**
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.
362  */
363  unsigned long whatToShow();
364 
365  /**
366  * The filter used to screen nodes.
367  */
368  NodeFilter filter();
369 
370  /**
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.
375  *
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.
383  */
384  bool expandEntityReferences();
385 
386  /**
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.
395  *
396  * @exception DOMException
397  * NOT_SUPPORTED_ERR: Raised if an attempt is made to set currentNode to null.
398  */
399  Node currentNode();
400 
401  /**
402  * see currentNode
403  */
404  void setCurrentNode(const Node &_currentNode);
405 
406  /**
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.
411  *
412  * @return The new parent node, or null if the current node has no
413  * parent in the TreeWalker's logical view.
414  *
415  * @exception Exceptions from user code
416  * Any exceptions raised by a user-written Filter will propagate
417  * through.
418  *
419  */
420  Node parentNode();
421 
422  /**
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
426  * current node.
427  *
428  * @return The new node, or \c null if the current
429  * node has no children.
430  *
431  * @exception Exceptions from user code
432  * Any exceptions raised by a user-written Filter will propagate
433  * through.
434  *
435  */
436  Node firstChild();
437 
438  /**
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
442  * current node.
443  *
444  * @return The new node, or \c null if the current
445  * node has no children.
446  *
447  * @exception Exceptions from user code
448  * Any exceptions raised by a user-written Filter will propagate
449  * through.
450  *
451  */
452  Node lastChild();
453 
454  /**
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.
459  *
460  * @return The new node, or \c null if the current
461  * node has no previous sibling.
462  *
463  * @exception Exceptions from user code
464  * Any exceptions raised by a user-written Filter will propagate
465  * through.
466  *
467  */
468  Node previousSibling();
469 
470  /**
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
474  * current node.
475  *
476  * @return The new node, or \c null if the current
477  * node has no next sibling.
478  *
479  * @exception Exceptions from user code
480  * Any exceptions raised by a user-written Filter will propagate
481  * through.
482  *
483  */
484  Node nextSibling();
485 
486  /**
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.
491  *
492  * @return The new node, or \c null if the current
493  * node has no previous node.
494  *
495  * @exception Exceptions from user code
496  * Any exceptions raised by a user-written Filter will propagate
497  * through.
498  *
499  */
500  Node previousNode();
501 
502  /**
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.
507  *
508  * @return The new node, or \c null if the current
509  * node has no next node.
510  *
511  * @exception Exceptions from user code
512  * Any exceptions raised by a user-written Filter will propagate
513  * through.
514  *
515  */
516  Node nextNode();
517 
518  /**
519  * @internal
520  * not part of the DOM
521  */
522  TreeWalkerImpl *handle() const;
523  bool isNull() const;
524 
525 protected:
526  TreeWalker(TreeWalkerImpl *i);
527  TreeWalkerImpl *impl;
528 };
529 
530 } // namespace
531 
532 #endif
CustomNodeFilter can be used to define your own NodeFilter for use with NodeIterators and TreeWalkers...
The Node interface is the primary datatype for the entire Document Object Model.
Definition: dom_node.h:278
AcceptCode
The following constants are returned by the acceptNode() method:
ShowCode
These are the available values for the whatToShow parameter.
TreeWalker objects are used to navigate a document tree or subtree using the view of the document def...
This class implements the basic string we use in the DOM.
Definition: dom_string.h:44
The Document interface represents the entire HTML or XML document.
Definition: dom_doc.h:246
Filters are objects that know how to "filter out" nodes.
CustomNodeFilterImpl * impl
This library provides a full-featured HTML parser and widget.
NodeIterators are used to step through a set of nodes, e.g.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Oct 21 2021 22:48:04 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.