source: NonGTP/Xerces/xercesc/dom/DOMTreeWalker.hpp @ 188

Revision 188, 13.4 KB checked in by mattausch, 19 years ago (diff)

added xercesc to support

Line 
1#ifndef DOMTreeWalker_HEADER_GUARD_
2#define DOMTreeWalker_HEADER_GUARD_
3
4/*
5 * The Apache Software License, Version 1.1
6 *
7 * Copyright (c) 2001-2002 The Apache Software Foundation.  All rights
8 * reserved.
9 *
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions
12 * are met:
13 *
14 * 1. Redistributions of source code must retain the above copyright
15 *    notice, this list of conditions and the following disclaimer.
16 *
17 * 2. Redistributions in binary form must reproduce the above copyright
18 *    notice, this list of conditions and the following disclaimer in
19 *    the documentation and/or other materials provided with the
20 *    distribution.
21 *
22 * 3. The end-user documentation included with the redistribution,
23 *    if any, must include the following acknowledgment:
24 *       "This product includes software developed by the
25 *        Apache Software Foundation (http://www.apache.org/)."
26 *    Alternately, this acknowledgment may appear in the software itself,
27 *    if and wherever such third-party acknowledgments normally appear.
28 *
29 * 4. The names "Xerces" and "Apache Software Foundation" must
30 *    not be used to endorse or promote products derived from this
31 *    software without prior written permission. For written
32 *    permission, please contact apache\@apache.org.
33 *
34 * 5. Products derived from this software may not be called "Apache",
35 *    nor may "Apache" appear in their name, without prior written
36 *    permission of the Apache Software Foundation.
37 *
38 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
39 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
40 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
41 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
42 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
44 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
45 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
46 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
47 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
48 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
49 * SUCH DAMAGE.
50 * ====================================================================
51 *
52 * This software consists of voluntary contributions made by many
53 * individuals on behalf of the Apache Software Foundation, and was
54 * originally based on software copyright (c) 2001, International
55 * Business Machines, Inc., http://www.ibm.com .  For more information
56 * on the Apache Software Foundation, please see
57 * <http://www.apache.org/>.
58 */
59
60/*
61 * $Id: DOMTreeWalker.hpp,v 1.7 2003/03/07 19:59:09 tng Exp $
62 */
63
64#include "DOMNode.hpp"
65#include "DOMNodeFilter.hpp"
66
67XERCES_CPP_NAMESPACE_BEGIN
68
69
70/**
71 * <code>DOMTreeWalker</code> objects are used to navigate a document tree or
72 * subtree using the view of the document defined by their
73 * <code>whatToShow</code> flags and filter (if any). Any function which
74 * performs navigation using a <code>DOMTreeWalker</code> will automatically
75 * support any view defined by a <code>DOMTreeWalker</code>.
76 * <p>Omitting nodes from the logical view of a subtree can result in a
77 * structure that is substantially different from the same subtree in the
78 * complete, unfiltered document. Nodes that are siblings in the
79 * <code>DOMTreeWalker</code> view may be children of different, widely
80 * separated nodes in the original view. For instance, consider a
81 * <code>DOMNodeFilter</code> that skips all nodes except for DOMText nodes and
82 * the root node of a document. In the logical view that results, all text
83 * nodes will be siblings and appear as direct children of the root node, no
84 * matter how deeply nested the structure of the original document.
85 * <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>.
86 *
87 * @since DOM Level 2
88 */
89class CDOM_EXPORT DOMTreeWalker {
90protected:
91    // -----------------------------------------------------------------------
92    //  Hidden constructors
93    // -----------------------------------------------------------------------
94    /** @name Hidden constructors */
95    //@{   
96    DOMTreeWalker() {};
97    //@}
98
99private:
100    // -----------------------------------------------------------------------
101    // Unimplemented constructors and operators
102    // -----------------------------------------------------------------------
103    /** @name Unimplemented constructors and operators */
104    //@{
105    DOMTreeWalker(const DOMTreeWalker &);
106    DOMTreeWalker & operator = (const DOMTreeWalker &);
107    //@}
108
109public:
110    // -----------------------------------------------------------------------
111    //  All constructors are hidden, just the destructor is available
112    // -----------------------------------------------------------------------
113    /** @name Destructor */
114    //@{
115    /**
116     * Destructor
117     *
118     */
119    virtual ~DOMTreeWalker() {};
120    //@}
121
122    // -----------------------------------------------------------------------
123    //  Virtual DOMTreeWalker interface
124    // -----------------------------------------------------------------------
125    /** @name Functions introduced in DOM Level 2 */
126    //@{
127    // -----------------------------------------------------------------------
128    //  Getter methods
129    // -----------------------------------------------------------------------
130
131    /**
132     * The <code>root</code> node of the <code>DOMTreeWalker</code>, as specified
133     * when it was created.
134     *
135     * @since DOM Level 2
136     */
137    virtual DOMNode*          getRoot() = 0;
138    /**
139     * This attribute determines which node types are presented via the
140     * <code>DOMTreeWalker</code>. The available set of constants is defined in
141     * the <code>DOMNodeFilter</code> interface.  Nodes not accepted by
142     * <code>whatToShow</code> will be skipped, but their children may still
143     * be considered. Note that this skip takes precedence over the filter,
144     * if any.
145     *
146     * @since DOM Level 2
147     */
148    virtual unsigned long       getWhatToShow()= 0;
149
150    /**
151     * Return The filter used to screen nodes.
152     *
153     * @since DOM Level 2
154     */
155    virtual DOMNodeFilter*         getFilter()= 0;
156
157    /**
158     * The value of this flag determines whether the children of entity
159     * reference nodes are visible to the <code>DOMTreeWalker</code>. If false,
160     * these children  and their descendants will be rejected. Note that
161     * this rejection takes precedence over <code>whatToShow</code> and the
162     * filter, if any.
163     * <br> To produce a view of the document that has entity references
164     * expanded and does not expose the entity reference node itself, use
165     * the <code>whatToShow</code> flags to hide the entity reference node
166     * and set <code>expandEntityReferences</code> to true when creating the
167     * <code>DOMTreeWalker</code>. To produce a view of the document that has
168     * entity reference nodes but no entity expansion, use the
169     * <code>whatToShow</code> flags to show the entity reference node and
170     * set <code>expandEntityReferences</code> to false.
171     *
172     * @since DOM Level 2
173     */
174    virtual bool              getExpandEntityReferences()= 0;
175
176    /**
177     * Return the node at which the DOMTreeWalker is currently positioned.
178     *
179     * @since DOM Level 2
180     */
181    virtual DOMNode*          getCurrentNode()= 0;
182
183    // -----------------------------------------------------------------------
184    //  Query methods
185    // -----------------------------------------------------------------------
186    /**
187     * Moves to and returns the closest visible ancestor node of the current
188     * node. If the search for <code>parentNode</code> attempts to step
189     * upward from the <code>DOMTreeWalker</code>'s <code>root</code> node, or
190     * if it fails to find a visible ancestor node, this method retains the
191     * current position and returns <code>null</code>.
192     * @return The new parent node, or <code>null</code> if the current node
193     *   has no parent  in the <code>DOMTreeWalker</code>'s logical view.
194     *
195     * @since DOM Level 2
196     */
197    virtual DOMNode*          parentNode()= 0;
198
199    /**
200     * Moves the <code>DOMTreeWalker</code> to the first visible child of the
201     * current node, and returns the new node. If the current node has no
202     * visible children, returns <code>null</code>, and retains the current
203     * node.
204     * @return The new node, or <code>null</code> if the current node has no
205     *   visible children  in the <code>DOMTreeWalker</code>'s logical view.
206     *
207     * @since DOM Level 2
208     */
209    virtual DOMNode*          firstChild()= 0;
210
211    /**
212     * Moves the <code>DOMTreeWalker</code> to the last visible child of the
213     * current node, and returns the new node. If the current node has no
214     * visible children, returns <code>null</code>, and retains the current
215     * node.
216     * @return The new node, or <code>null</code> if the current node has no
217     *   children  in the <code>DOMTreeWalker</code>'s logical view.
218     *
219     * @since DOM Level 2
220     */
221    virtual DOMNode*          lastChild()= 0;
222
223    /**
224     * Moves the <code>DOMTreeWalker</code> to the previous sibling of the
225     * current node, and returns the new node. If the current node has no
226     * visible previous sibling, returns <code>null</code>, and retains the
227     * current node.
228     * @return The new node, or <code>null</code> if the current node has no
229     *   previous sibling.  in the <code>DOMTreeWalker</code>'s logical view.
230     *
231     * @since DOM Level 2
232     */
233    virtual DOMNode*          previousSibling()= 0;
234
235    /**
236     * Moves the <code>DOMTreeWalker</code> to the next sibling of the current
237     * node, and returns the new node. If the current node has no visible
238     * next sibling, returns <code>null</code>, and retains the current node.
239     * @return The new node, or <code>null</code> if the current node has no
240     *   next sibling.  in the <code>DOMTreeWalker</code>'s logical view.
241     *
242     * @since DOM Level 2
243     */
244    virtual DOMNode*          nextSibling()= 0;
245
246    /**
247     * Moves the <code>DOMTreeWalker</code> to the previous visible node in
248     * document order relative to the current node, and returns the new
249     * node. If the current node has no previous node,  or if the search for
250     * <code>previousNode</code> attempts to step upward from the
251     * <code>DOMTreeWalker</code>'s <code>root</code> node,  returns
252     * <code>null</code>, and retains the current node.
253     * @return The new node, or <code>null</code> if the current node has no
254     *   previous node  in the <code>DOMTreeWalker</code>'s logical view.
255     *
256     * @since DOM Level 2
257     */
258    virtual DOMNode*          previousNode()= 0;
259
260    /**
261     * Moves the <code>DOMTreeWalker</code> to the next visible node in document
262     * order relative to the current node, and returns the new node. If the
263     * current node has no next node, or if the search for nextNode attempts
264     * to step upward from the <code>DOMTreeWalker</code>'s <code>root</code>
265     * node, returns <code>null</code>, and retains the current node.
266     * @return The new node, or <code>null</code> if the current node has no
267     *   next node  in the <code>DOMTreeWalker</code>'s logical view.
268     *
269     * @since DOM Level 2
270     */
271    virtual DOMNode*          nextNode()= 0;
272
273    // -----------------------------------------------------------------------
274    //  Setter methods
275    // -----------------------------------------------------------------------
276    /**
277     * The node at which the <code>DOMTreeWalker</code> is currently positioned.
278     * <br>Alterations to the DOM tree may cause the current node to no longer
279     * be accepted by the <code>DOMTreeWalker</code>'s associated filter.
280     * <code>currentNode</code> may also be explicitly set to any node,
281     * whether or not it is within the subtree specified by the
282     * <code>root</code> node or would be accepted by the filter and
283     * <code>whatToShow</code> flags. Further traversal occurs relative to
284     * <code>currentNode</code> even if it is not part of the current view,
285     * by applying the filters in the requested direction; if no traversal
286     * is possible, <code>currentNode</code> is not changed.
287     * @exception DOMException
288     *   NOT_SUPPORTED_ERR: Raised if an attempt is made to set
289     *   <code>currentNode</code> to <code>null</code>.
290     *
291     * @since DOM Level 2
292     */
293    virtual void              setCurrentNode(DOMNode* currentNode)= 0;
294    //@}
295
296    // -----------------------------------------------------------------------
297    //  Non-standard Extension
298    // -----------------------------------------------------------------------
299    /** @name Non-standard Extension */
300    //@{
301    /**
302     * Called to indicate that this TreeWalker is no longer in use
303     * and that the implementation may relinquish any resources associated with it.
304     *
305     * Access to a released object will lead to unexpected result.
306     */
307    virtual void              release() = 0;
308    //@}
309};
310
311XERCES_CPP_NAMESPACE_END
312
313#endif
Note: See TracBrowser for help on using the repository browser.