source: NonGTP/Xerces/xerces/include/xercesc/dom/DOMTreeWalker.hpp @ 358

Revision 358, 11.5 KB checked in by bittner, 19 years ago (diff)

xerces added

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