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
TreeWalker objects are used to navigate a document tree or subtree using the view of the document def...
AcceptCode
The following constants are returned by the acceptNode() method:
This library provides a full-featured HTML parser and widget.
NodeIterators are used to step through a set of nodes, e.g.
The Document interface represents the entire HTML or XML document.
Definition: dom_doc.h:246
ShowCode
These are the available values for the whatToShow parameter.
This class implements the basic string we use in the DOM.
Definition: dom_string.h:44
CustomNodeFilterImpl * impl
The Node interface is the primary datatype for the entire Document Object Model.
Definition: dom_node.h:278
Filters are objects that know how to "filter out" nodes.
CustomNodeFilter can be used to define your own NodeFilter for use with NodeIterators and TreeWalkers...
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Dec 11 2023 04:06:47 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.