source: icXML/icXML-devel/src/xercesc/dom/DOMDocumentTraversal.hpp @ 2722

Last change on this file since 2722 was 2722, checked in by cameron, 6 years ago

Original Xerces files with import mods for icxercesc

File size: 7.3 KB
Line 
1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *      http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18/*
19 * $Id: DOMDocumentTraversal.hpp 671894 2008-06-26 13:29:21Z borisk $
20*/
21
22#if !defined(XERCESC_INCLUDE_GUARD_DOMDOCUMENTTRAVERSAL_HPP)
23#define XERCESC_INCLUDE_GUARD_DOMDOCUMENTTRAVERSAL_HPP
24
25#include <xercesc/util/XercesDefs.hpp>
26#include <xercesc/dom/DOMNodeFilter.hpp>
27
28XERCES_CPP_NAMESPACE_BEGIN
29
30
31class DOMNode;
32class DOMNodeIterator;
33class DOMTreeWalker;
34
35
36/**
37 * <code>DOMDocumentTraversal</code> contains methods that create
38 * <code>DOMNodeIterators</code> and <code>DOMTreeWalkers</code> to traverse a
39 * node and its children in document order (depth first, pre-order
40 * traversal, which is equivalent to the order in which the start tags occur
41 * in the text representation of the document). In DOMs which support the
42 * Traversal feature, <code>DOMDocumentTraversal</code> will be implemented by
43 * the same objects that implement the DOMDocument interface.
44 * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>.
45 * @since DOM Level 2
46 */
47class CDOM_EXPORT DOMDocumentTraversal {
48
49protected:
50    // -----------------------------------------------------------------------
51    //  Hidden constructors
52    // -----------------------------------------------------------------------
53    /** @name Hidden constructors */
54    //@{
55    DOMDocumentTraversal() {};
56    //@}
57
58private:
59    // -----------------------------------------------------------------------
60    // Unimplemented constructors and operators
61    // -----------------------------------------------------------------------
62    /** @name Unimplemented constructors and operators */
63    //@{
64    DOMDocumentTraversal(const DOMDocumentTraversal &);
65    DOMDocumentTraversal & operator = (const DOMDocumentTraversal &);
66    //@}
67
68public:
69    // -----------------------------------------------------------------------
70    //  All constructors are hidden, just the destructor is available
71    // -----------------------------------------------------------------------
72    /** @name Destructor */
73    //@{
74    /**
75     * Destructor
76     *
77     */
78    virtual ~DOMDocumentTraversal() {};
79    //@}
80
81    // -----------------------------------------------------------------------
82    //  Virtual DOMDocumentRange interface
83    // -----------------------------------------------------------------------
84    /** @name Functions introduced in DOM Level 2 */
85    //@{
86    /**
87     * Creates a NodeIterator object.   (DOM2)
88     *
89     * NodeIterators are used to step through a set of nodes, e.g. the set of nodes in a NodeList, the
90     * document subtree governed by a particular node, the results of a query, or any other set of nodes.
91     * The set of nodes to be iterated is determined by the implementation of the NodeIterator. DOM Level 2
92     * specifies a single NodeIterator implementation for document-order traversal of a document subtree.
93     * Instances of these iterators are created by calling <code>DOMDocumentTraversal.createNodeIterator()</code>.
94     *
95     * To produce a view of the document that has entity references expanded and does not
96     * expose the entity reference node itself, use the <code>whatToShow</code> flags to hide the entity
97     * reference node and set expandEntityReferences to true when creating the iterator. To
98     * produce a view of the document that has entity reference nodes but no entity expansion,
99     * use the <code>whatToShow</code> flags to show the entity reference node and set
100     * expandEntityReferences to false.
101     *
102     * @param root The root node of the DOM tree
103     * @param whatToShow This attribute determines which node types are presented via the iterator.
104     * @param filter The filter used to screen nodes
105     * @param entityReferenceExpansion The value of this flag determines whether the children of entity reference nodes are
106     *                   visible to the iterator. If false, they will be skipped over.
107     * @since DOM Level 2
108     */
109
110    virtual DOMNodeIterator *createNodeIterator(DOMNode* root,
111                                                DOMNodeFilter::ShowType whatToShow,
112                                                DOMNodeFilter* filter,
113                                                bool entityReferenceExpansion) = 0;
114    /**
115     * Creates a TreeWalker object.   (DOM2)
116     *
117     * TreeWalker objects are used to navigate a document tree or subtree using the view of the document defined
118     * by its whatToShow flags and any filters that are defined for the TreeWalker. Any function which performs
119     * navigation using a TreeWalker will automatically support any view defined by a TreeWalker.
120     *
121     * Omitting nodes from the logical view of a subtree can result in a structure that is substantially different from
122     * the same subtree in the complete, unfiltered document. Nodes that are siblings in the TreeWalker view may
123     * be children of different, widely separated nodes in the original view. For instance, consider a Filter that skips
124     * all nodes except for DOMText nodes and the root node of a document. In the logical view that results, all text
125     * nodes will be siblings and appear as direct children of the root node, no matter how deeply nested the
126     * structure of the original document.
127     *
128     * To produce a view of the document that has entity references expanded
129     * and does not expose the entity reference node itself, use the whatToShow
130     * flags to hide the entity reference node and set <code>expandEntityReferences</code> to
131     * true when creating the TreeWalker. To produce a view of the document
132     * that has entity reference nodes but no entity expansion, use the
133     * <code>whatToShow</code> flags to show the entity reference node and set
134     * <code>expandEntityReferences</code> to false
135     *
136     * @param root The root node of the DOM tree
137     * @param whatToShow This attribute determines which node types are presented via the tree-walker.
138     * @param filter The filter used to screen nodes
139     * @param entityReferenceExpansion The value of this flag determines whether the children of entity reference nodes are
140     *                   visible to the tree-walker. If false, they will be skipped over.
141     * @since DOM Level 2
142     */
143
144    virtual DOMTreeWalker  *createTreeWalker(DOMNode* root,
145                                             DOMNodeFilter::ShowType whatToShow,
146                                             DOMNodeFilter* filter,
147                                             bool entityReferenceExpansion) = 0;
148
149    //@}
150};
151
152
153XERCES_CPP_NAMESPACE_END
154
155#endif
Note: See TracBrowser for help on using the repository browser.