source: icXML/icXML-devel/src/xercesc/dom/DOMTreeWalker.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: 11.4 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: DOMTreeWalker.hpp 671894 2008-06-26 13:29:21Z borisk $
20 */
21
22#if !defined(XERCESC_INCLUDE_GUARD_DOMTREEWALKER_HPP)
23#define XERCESC_INCLUDE_GUARD_DOMTREEWALKER_HPP
24
25#include <xercesc/dom/DOMNode.hpp>
26#include <xercesc/dom/DOMNodeFilter.hpp>
27
28XERCES_CPP_NAMESPACE_BEGIN
29
30
31/**
32 * <code>DOMTreeWalker</code> objects are used to navigate a document tree or
33 * subtree using the view of the document defined by their
34 * <code>whatToShow</code> flags and filter (if any). Any function which
35 * performs navigation using a <code>DOMTreeWalker</code> will automatically
36 * support any view defined by a <code>DOMTreeWalker</code>.
37 * <p>Omitting nodes from the logical view of a subtree can result in a
38 * structure that is substantially different from the same subtree in the
39 * complete, unfiltered document. Nodes that are siblings in the
40 * <code>DOMTreeWalker</code> view may be children of different, widely
41 * separated nodes in the original view. For instance, consider a
42 * <code>DOMNodeFilter</code> that skips all nodes except for DOMText nodes and
43 * the root node of a document. In the logical view that results, all text
44 * nodes will be siblings and appear as direct children of the root node, no
45 * matter how deeply nested the structure of the original document.
46 * <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>.
47 *
48 * @since DOM Level 2
49 */
50class CDOM_EXPORT DOMTreeWalker {
51protected:
52    // -----------------------------------------------------------------------
53    //  Hidden constructors
54    // -----------------------------------------------------------------------
55    /** @name Hidden constructors */
56    //@{
57    DOMTreeWalker() {}
58    DOMTreeWalker(const DOMTreeWalker &) {}
59    //@}
60
61private:
62    // -----------------------------------------------------------------------
63    // Unimplemented constructors and operators
64    // -----------------------------------------------------------------------
65    /** @name Unimplemented constructors and operators */
66    //@{
67    DOMTreeWalker & operator = (const DOMTreeWalker &);
68    //@}
69
70public:
71    // -----------------------------------------------------------------------
72    //  All constructors are hidden, just the destructor is available
73    // -----------------------------------------------------------------------
74    /** @name Destructor */
75    //@{
76    /**
77     * Destructor
78     *
79     */
80    virtual ~DOMTreeWalker() {};
81    //@}
82
83    // -----------------------------------------------------------------------
84    //  Virtual DOMTreeWalker interface
85    // -----------------------------------------------------------------------
86    /** @name Functions introduced in DOM Level 2 */
87    //@{
88    // -----------------------------------------------------------------------
89    //  Getter methods
90    // -----------------------------------------------------------------------
91
92    /**
93     * The <code>root</code> node of the <code>DOMTreeWalker</code>, as specified
94     * when it was created.
95     *
96     * @since DOM Level 2
97     */
98    virtual DOMNode*          getRoot() = 0;
99    /**
100     * This attribute determines which node types are presented via the
101     * <code>DOMTreeWalker</code>. The available set of constants is defined in
102     * the <code>DOMNodeFilter</code> interface.  Nodes not accepted by
103     * <code>whatToShow</code> will be skipped, but their children may still
104     * be considered. Note that this skip takes precedence over the filter,
105     * if any.
106     *
107     * @since DOM Level 2
108     */
109    virtual DOMNodeFilter::ShowType getWhatToShow()= 0;
110
111    /**
112     * Return The filter used to screen nodes.
113     *
114     * @since DOM Level 2
115     */
116    virtual DOMNodeFilter*         getFilter()= 0;
117
118    /**
119     * The value of this flag determines whether the children of entity
120     * reference nodes are visible to the <code>DOMTreeWalker</code>. If false,
121     * these children  and their descendants will be rejected. Note that
122     * this rejection takes precedence over <code>whatToShow</code> and the
123     * filter, if any.
124     * <br> To produce a view of the document that has entity references
125     * expanded and does not expose the entity reference node itself, use
126     * the <code>whatToShow</code> flags to hide the entity reference node
127     * and set <code>expandEntityReferences</code> to true when creating the
128     * <code>DOMTreeWalker</code>. To produce a view of the document that has
129     * entity reference nodes but no entity expansion, use the
130     * <code>whatToShow</code> flags to show the entity reference node and
131     * set <code>expandEntityReferences</code> to false.
132     *
133     * @since DOM Level 2
134     */
135    virtual bool              getExpandEntityReferences()= 0;
136
137    /**
138     * Return the node at which the DOMTreeWalker is currently positioned.
139     *
140     * @since DOM Level 2
141     */
142    virtual DOMNode*          getCurrentNode()= 0;
143
144    // -----------------------------------------------------------------------
145    //  Query methods
146    // -----------------------------------------------------------------------
147    /**
148     * Moves to and returns the closest visible ancestor node of the current
149     * node. If the search for <code>parentNode</code> attempts to step
150     * upward from the <code>DOMTreeWalker</code>'s <code>root</code> node, or
151     * if it fails to find a visible ancestor node, this method retains the
152     * current position and returns <code>null</code>.
153     * @return The new parent node, or <code>null</code> if the current node
154     *   has no parent  in the <code>DOMTreeWalker</code>'s logical view.
155     *
156     * @since DOM Level 2
157     */
158    virtual DOMNode*          parentNode()= 0;
159
160    /**
161     * Moves the <code>DOMTreeWalker</code> to the first visible child of the
162     * current node, and returns the new node. If the current node has no
163     * visible children, returns <code>null</code>, and retains the current
164     * node.
165     * @return The new node, or <code>null</code> if the current node has no
166     *   visible children  in the <code>DOMTreeWalker</code>'s logical view.
167     *
168     * @since DOM Level 2
169     */
170    virtual DOMNode*          firstChild()= 0;
171
172    /**
173     * Moves the <code>DOMTreeWalker</code> to the last visible child of the
174     * current node, and returns the new node. If the current node has no
175     * visible children, returns <code>null</code>, and retains the current
176     * node.
177     * @return The new node, or <code>null</code> if the current node has no
178     *   children  in the <code>DOMTreeWalker</code>'s logical view.
179     *
180     * @since DOM Level 2
181     */
182    virtual DOMNode*          lastChild()= 0;
183
184    /**
185     * Moves the <code>DOMTreeWalker</code> to the previous sibling of the
186     * current node, and returns the new node. If the current node has no
187     * visible previous sibling, returns <code>null</code>, and retains the
188     * current node.
189     * @return The new node, or <code>null</code> if the current node has no
190     *   previous sibling.  in the <code>DOMTreeWalker</code>'s logical view.
191     *
192     * @since DOM Level 2
193     */
194    virtual DOMNode*          previousSibling()= 0;
195
196    /**
197     * Moves the <code>DOMTreeWalker</code> to the next sibling of the current
198     * node, and returns the new node. If the current node has no visible
199     * next sibling, returns <code>null</code>, and retains the current node.
200     * @return The new node, or <code>null</code> if the current node has no
201     *   next sibling.  in the <code>DOMTreeWalker</code>'s logical view.
202     *
203     * @since DOM Level 2
204     */
205    virtual DOMNode*          nextSibling()= 0;
206
207    /**
208     * Moves the <code>DOMTreeWalker</code> to the previous visible node in
209     * document order relative to the current node, and returns the new
210     * node. If the current node has no previous node,  or if the search for
211     * <code>previousNode</code> attempts to step upward from the
212     * <code>DOMTreeWalker</code>'s <code>root</code> node,  returns
213     * <code>null</code>, and retains the current node.
214     * @return The new node, or <code>null</code> if the current node has no
215     *   previous node  in the <code>DOMTreeWalker</code>'s logical view.
216     *
217     * @since DOM Level 2
218     */
219    virtual DOMNode*          previousNode()= 0;
220
221    /**
222     * Moves the <code>DOMTreeWalker</code> to the next visible node in document
223     * order relative to the current node, and returns the new node. If the
224     * current node has no next node, or if the search for nextNode attempts
225     * to step upward from the <code>DOMTreeWalker</code>'s <code>root</code>
226     * node, returns <code>null</code>, and retains the current node.
227     * @return The new node, or <code>null</code> if the current node has no
228     *   next node  in the <code>DOMTreeWalker</code>'s logical view.
229     *
230     * @since DOM Level 2
231     */
232    virtual DOMNode*          nextNode()= 0;
233
234    // -----------------------------------------------------------------------
235    //  Setter methods
236    // -----------------------------------------------------------------------
237    /**
238     * The node at which the <code>DOMTreeWalker</code> is currently positioned.
239     * <br>Alterations to the DOM tree may cause the current node to no longer
240     * be accepted by the <code>DOMTreeWalker</code>'s associated filter.
241     * <code>currentNode</code> may also be explicitly set to any node,
242     * whether or not it is within the subtree specified by the
243     * <code>root</code> node or would be accepted by the filter and
244     * <code>whatToShow</code> flags. Further traversal occurs relative to
245     * <code>currentNode</code> even if it is not part of the current view,
246     * by applying the filters in the requested direction; if no traversal
247     * is possible, <code>currentNode</code> is not changed.
248     * @exception DOMException
249     *   NOT_SUPPORTED_ERR: Raised if an attempt is made to set
250     *   <code>currentNode</code> to <code>null</code>.
251     *
252     * @since DOM Level 2
253     */
254    virtual void              setCurrentNode(DOMNode* currentNode)= 0;
255    //@}
256
257    // -----------------------------------------------------------------------
258    //  Non-standard Extension
259    // -----------------------------------------------------------------------
260    /** @name Non-standard Extension */
261    //@{
262    /**
263     * Called to indicate that this TreeWalker is no longer in use
264     * and that the implementation may relinquish any resources associated with it.
265     *
266     * Access to a released object will lead to unexpected result.
267     */
268    virtual void              release() = 0;
269    //@}
270};
271
272#define GetDOMTreeWalkerMemoryManager GET_INDIRECT_MM(fCurrentNode)
273
274XERCES_CPP_NAMESPACE_END
275
276#endif
Note: See TracBrowser for help on using the repository browser.