More documentation. Traversal needed conversion to NodePtr. Traversal needs more...

diff --git a/src/dom/traversal.h b/src/dom/traversal.h
index 4e99b8e527b4d8efe31774e1412a55a44ef76aaa..6d00bac67d33f0caac496439969b8293fc5ca2c8 100644 (file)
--- a/src/dom/traversal.h
+++ b/src/dom/traversal.h
@@ -13,7 +13,7 @@
  * Authors:
  *   Bob Jamison
  *
- * Copyright (C) 2005 Bob Jamison
+ * Copyright (C) 2005-2008 Bob Jamison
  *
  *  This library is free software; you can redistribute it and/or
  *  modify it under the terms of the GNU Lesser General Public
@@ -28,6 +28,12 @@
  *  You should have received a copy of the GNU Lesser General Public
  *  License along with this library; if not, write to the Free Software
  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ *  
+ * ==========================================================================
+ * NOTES
+ * 
+ * This interface is described here:
+ * http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113      
  */
 
 
@@ -54,24 +60,66 @@ typedef dom::Node Node;
 /*#########################################################################
 ## NodeFilter
 #########################################################################*/
+
 /**
- *
+ * Filters are objects that know how to "filter out" nodes. If a NodeIterator or 
+ * TreeWalker is given a NodeFilter, it applies the filter before it returns the 
+ * next node. If the filter says to accept the node, the traversal logic returns 
+ * it; otherwise, traversal looks for the next node and pretends that the node 
+ * that was rejected was not there.
+ * 
+ * The DOM does not provide any filters. NodeFilter is just an interface that 
+ * users can implement to provide their own filters.
+ * 
+ * NodeFilters do not need to know how to traverse from node to node, nor do they 
+ * need to know anything about the data structure that is being traversed. This 
+ * makes it very easy to write filters, since the only thing they have to know 
+ * how to do is evaluate a single node. One filter may be used with a number of 
+ * different kinds of traversals, encouraging code reuse.
+ * 
+ * Note:
+ * The spec is slightly vague on this interface, for instance, setting the
+ * whatToShow value.    
  */
 class NodeFilter
 {
 public:
 
-    // Constants returned by acceptNode
+    /**
+     * The following constants are returned by the acceptNode() method
+     */             
     typedef enum
         {
         FILTER_ACCEPT                  = 1,
         FILTER_REJECT                  = 2,
         FILTER_SKIP                    = 3
-        } AcceptNodeReturn;
+        } AcceptNodeType;
 
+    /**
+     * Test whether a specified node is visible in the logical view of a TreeWalker 
+     * or NodeIterator. This function will be called by the implementation of 
+     * TreeWalker and NodeIterator; it is not normally called directly from user 
+     * code. (Though you could do so if you wanted to use the same filter to guide 
+     * your own application logic.)
+     */
+    virtual short acceptNode(const NodePtr /*n*/)
+        {
+        return 0;
+        }
 
 
-    // Constants for whatToShow
+    /**
+     * These are the available values for the whatToShow parameter used in 
+     * TreeWalkers and NodeIterators. They are the same as the set of possible types 
+     * for Node, and their values are derived by using a bit position corresponding 
+     * to the value of nodeType for the equivalent node type. If a bit in whatToShow 
+     * is set false, that will be taken as a request to skip over this type of node; 
+     * the behavior in that case is similar to that of FILTER_SKIP.
+     * 
+     * Note that if node types greater than 32 are ever introduced, they may not be 
+     * individually testable via whatToShow. If that need should arise, it can be 
+     * handled by selecting SHOW_ALL together with an appropriate NodeFilter.
+     */    
     typedef enum
         {
         SHOW_ALL                       = 0xFFFFFFFF,
@@ -87,15 +135,8 @@ public:
         SHOW_DOCUMENT_TYPE             = 0x00000200,
         SHOW_DOCUMENT_FRAGMENT         = 0x00000400,
         SHOW_NOTATION                  = 0x00000800
-        } WhatToShowReturn;
+        } WhatToShowType;
 
-    /**
-     *
-     */
-    virtual short acceptNode(const Node */*n*/)
-        {
-        return 0;
-        }
 
 
 
@@ -106,14 +147,31 @@ public:
     /**
      *
      */
-    NodeFilter()
+    NodeFilter() : whatToShow(SHOW_ALL)
         {}
 
     /**
      *
      */
-    NodeFilter(const NodeFilter &/*other*/)
+    NodeFilter(int whatToShowArg) : whatToShow(whatToShowArg)
+        {}
+
+
+    /**
+     *
+     */
+    NodeFilter(const NodeFilter &other)
+        {
+        whatToShow = other.whatToShow;
+        }
+
+    /**
+     *
+     */
+    NodeFilter& operator=(const NodeFilter &other)
         {
+        whatToShow = other.whatToShow;
+        return *this;
         }
 
     /**
@@ -122,68 +180,104 @@ public:
     virtual ~NodeFilter() {}
 
 
+    int whatToShow;
+
 };
 
+
+
 /*#########################################################################
 ## NodeIterator
 #########################################################################*/
+
 /**
- *
+ * Iterators are used to step through a set of nodes, e.g. the set of nodes in a 
+ * NodeList, the document subtree governed by a particular Node, the results of a 
+ * query, or any other set of nodes. The set of nodes to be iterated is 
+ * determined by the implementation of the NodeIterator. DOM Level 2 specifies a 
+ * single NodeIterator implementation for document-order traversal of a document 
+ * subtree. Instances of these iterators are created by calling 
+ * DocumentTraversal .createNodeIterator().
  */
 class NodeIterator
 {
 public:
 
     /**
-     *
+     * The root node of the NodeIterator, as specified when it was created.
      */
-    virtual Node *getRoot()
+    virtual NodePtr getRoot()
         {
-        return NULL;
+        NodePtr ptr;
+        return ptr;
         }
 
     /**
-     *
+     * This attribute determines which node types are presented via the iterator. The 
+     * available set of constants is defined in the NodeFilter interface. Nodes not 
+     * accepted by whatToShow will be skipped, but their children may still be 
+     * considered. Note that this skip takes precedence over the filter, if any.
      */
     virtual unsigned long getWhatToShow()
         { return whatToShow; }
 
     /**
-     *
+     * The NodeFilter used to screen nodes.
      */
     virtual NodeFilter getFilter()
         { return filter; }
 
     /**
-     *
+     * The value of this flag determines whether the children of entity reference 
+     * nodes are visible to the iterator. If false, they and their descendants will 
+     * be rejected. Note that this rejection takes precedence over whatToShow and the 
+     * filter. Also note that this is currently the only situation where 
+     * NodeIterators may reject a complete subtree rather than skipping individual 
+     * nodes.
+     * 
+     * To produce a view of the document that has entity references expanded and does 
+     * not expose the entity reference node itself, use the whatToShow flags to hide 
+     * the entity reference node and set expandEntityReferences to true when creating 
+     * the iterator. To produce a view of the document that has entity reference 
+     * nodes but no entity expansion, use the whatToShow flags to show the entity 
+     * reference node and set expandEntityReferences to false.
      */
     virtual bool getExpandEntityReferences()
         { return expandEntityReferences; }
 
     /**
-     *
+     * Returns the next node in the set and advances the position of the iterator in 
+     * the set. After a NodeIterator is created, the first call to nextNode() returns 
+     * the first node in the set.
      */
-    virtual Node *nextNode() throw(dom::DOMException)
+    virtual NodePtr nextNode() throw(dom::DOMException)
         {
-        return NULL;
+        NodePtr ptr;
+        return ptr;
         }
 
     /**
-     *
+     * Returns the previous node in the set and moves the position of the
+     * NodeIterator backwards in the set. 
      */
-    virtual Node *previousNode() throw(dom::DOMException)
+    virtual NodePtr previousNode() throw(dom::DOMException)
         {
-        return NULL;
+        NodePtr ptr;
+        return ptr;
         }
 
     /**
-     *
+     * Detaches the NodeIterator from the set which it iterated over, releasing any 
+     * computational resources and placing the iterator in the INVALID state. After 
+     * detach has been invoked, calls to nextNode or previousNode will raise the 
+     * exception INVALID_STATE_ERR.
      */
     virtual void detach()
         {
         }
 
 
+
     //##################
     //# Non-API methods
     //##################
@@ -211,8 +305,8 @@ public:
 protected:
 
     unsigned long whatToShow;
-    NodeFilter filter;
-    bool expandEntityReferences;
+    NodeFilter    filter;
+    bool          expandEntityReferences;
 
 
 };
@@ -224,7 +318,19 @@ protected:
 #########################################################################*/
 
 /**
- *
+ * TreeWalker objects are used to navigate a document tree or subtree using the 
+ * view of the document defined by their whatToShow flags and filter (if any). 
+ * Any function which performs navigation using a TreeWalker will automatically 
+ * support any view defined by a TreeWalker.
+ * 
+ * Omitting nodes from the logical view of a subtree can result in a structure 
+ * that is substantially different from the same subtree in the complete, 
+ * unfiltered document. Nodes that are siblings in the TreeWalker view may be 
+ * children of different, widely separated nodes in the original view. For 
+ * instance, consider a NodeFilter that skips all nodes except for Text nodes and 
+ * the root node of a document. In the logical view that results, all text nodes 
+ * will be siblings and appear as direct children of the root node, no matter how 
+ * deeply nested the structure of the original document.
  */
 class TreeWalker
 {
@@ -232,97 +338,141 @@ public:
 
 
     /**
-     *
+     * The root node of the TreeWalker, as specified when it was created.
      */
-    virtual Node *getRoot()
+    virtual NodePtr getRoot()
         {
-        return NULL;
+        NodePtr ptr;
+        return ptr;
         }
 
     /**
-     *
+     * This attribute determines which node types are presented via the TreeWalker. 
+     * The available set of constants is defined in the NodeFilter interface. Nodes 
+     * not accepted by whatToShow will be skipped, but their children may still be 
+     * considered. Note that this skip takes precedence over the filter, if any.
      */
     virtual unsigned long getWhatToShow()
         { return whatToShow; }
 
     /**
-     *
+     * The filter used to screen nodes.
      */
     virtual NodeFilter getFilter()
         { return filter; }
 
     /**
-     *
+     * The value of this flag determines whether the children of entity reference 
+     * nodes are visible to the TreeWalker. If false, they and their descendants will 
+     * be rejected. Note that this rejection takes precedence over whatToShow and the 
+     * filter, if any. To produce a view of the document that has entity references 
+     * expanded and does not expose the entity reference node itself, use the 
+     * whatToShow flags to hide the entity reference node and set 
+     * expandEntityReferences to true when creating the TreeWalker. To produce a view 
+     * of the document that has entity reference nodes but no entity expansion, use 
+     * the whatToShow flags to show the entity reference node and set 
+     * expandEntityReferences to false.
      */
     virtual bool getExpandEntityReferences()
         { return expandEntityReferences; }
 
     /**
-     *
+     * The node at which the TreeWalker is currently positioned. Alterations to the 
+     * DOM tree may cause the current node to no longer be accepted by the 
+     * TreeWalker's associated filter. currentNode may also be explicitly set to any 
+     * node, whether or not it is within the subtree specified by the root node or 
+     * would be accepted by the filter and whatToShow flags. Further traversal occurs 
+     * relative to currentNode even if it is not part of the current view, by 
+     * applying the filters in the requested direction; if no traversal is possible, 
+     * currentNode is not changed.
      */
-    virtual Node *getCurrentNode()
+    virtual NodePtr getCurrentNode()
         { return currentNode; }
 
     /**
-     *
+     * Sets the value above.
      */
-    virtual void setCurrentNode(const Node *val) throw(dom::DOMException)
-        { currentNode = (Node *)val; }
+    virtual void setCurrentNode(const NodePtr val) throw(dom::DOMException)
+        { currentNode = val; }
 
     /**
-     *
+     * Moves to and returns the closest visible ancestor node of the current node. If 
+     * the search for parentNode attempts to step upward from the TreeWalker's root 
+     * node, or if it fails to find a visible ancestor node, this method retains the 
+     * current position and returns null.
      */
-    virtual Node *parentNode()
+    virtual NodePtr parentNode()
         {
-        return NULL;
+        NodePtr ptr;
+        return ptr;
         }
 
     /**
-     *
+     * Moves the TreeWalker to the first visible child of the current node, and 
+     * returns the new node. If the current node has no visible children, returns 
+     * null, and retains the current node.
      */
-    virtual Node *firstChild()
+    virtual NodePtr firstChild()
         {
-        return NULL;
+        NodePtr ptr;
+        return ptr;
         }
 
     /**
-     *
+     * Moves the TreeWalker to the last visible child of the current node, and 
+     * returns the new node. If the current node has no visible children, returns 
+     * null, and retains the current node.
      */
-    virtual Node *lastChild()
+    virtual NodePtr lastChild()
         {
-        return NULL;
+        NodePtr ptr;
+        return ptr;
         }
 
     /**
-     *
+     * Moves the TreeWalker to the previous sibling of the current node, and returns 
+     * the new node. If the current node has no visible previous sibling, returns 
+     * null, and retains the current node.
      */
-    virtual Node *previousSibling()
+    virtual NodePtr previousSibling()
         {
-        return NULL;
+        NodePtr ptr;
+        return ptr;
         }
 
     /**
-     *
+     * Moves the TreeWalker to the next sibling of the current node, and returns the 
+     * new node. If the current node has no visible next sibling, returns null, and 
+     * retains the current node.
      */
-    virtual Node *nextSibling()
+    virtual NodePtr nextSibling()
         {
-        return NULL;
+        NodePtr ptr;
+        return ptr;
         }
 
     /**
-     *
+     * Moves the TreeWalker to the previous visible node in document order relative 
+     * to the current node, and returns the new node. If the current node has no 
+     * previous node, or if the search for previousNode attempts to step upward from 
+     * the TreeWalker's root node, returns null, and retains the current node.
      */
-    virtual Node *previousNode()
+    virtual NodePtr previousNode()
         {
-        return NULL;
+        NodePtr ptr;
+        return ptr;
         }
 
     /**
-     *
+     * Moves the TreeWalker to the next visible node in document order relative to 
+     * the current node, and returns the new node. If the current node has no next 
+     * node, or if the search for nextNode attempts to step upward from the 
+     * TreeWalker's root node, returns null, and retains the current node.
      */
-    virtual Node *nextNode()
+    virtual NodePtr nextNode()
         {
-        return NULL;
+        NodePtr ptr;
+        return ptr;
         }
 
 
@@ -356,9 +506,9 @@ public:
 protected:
 
     unsigned long whatToShow;
-    NodeFilter filter;
-    bool expandEntityReferences;
-    Node *currentNode;
+    NodeFilter    filter;
+    bool          expandEntityReferences;
+    NodePtr       currentNode;
 
 };
 
@@ -370,31 +520,36 @@ protected:
 #########################################################################*/
 
 /**
- *
+ * DocumentTraversal contains methods that create iterators and tree-walkers to 
+ * traverse a node and its children in document order (depth first, pre-order 
+ * traversal, which is equivalent to the order in which the start tags occur in 
+ * the text representation of the document). In DOMs which support the Traversal 
+ * feature, DocumentTraversal will be implemented by the same objects that 
+ * implement the Document interface.
  */
 class DocumentTraversal
 {
 public:
 
     /**
-     *
+     * Create a new NodeIterator over the subtree rooted at the specified node. 
      */
-    virtual NodeIterator createNodeIterator(const Node */*root*/,
+    virtual NodeIterator createNodeIterator(const NodePtr /*root*/,
                                             unsigned long /*whatToShow*/,
-                                            const NodeFilter */*filter*/,
+                                            const NodeFilter/*filter*/,
                                             bool /*entityReferenceExpansion*/)
-                                          throw (dom::DOMException)
+                                            throw (dom::DOMException)
         {
         NodeIterator ret;
         return ret;
         }
 
     /**
-     *
+     * Create a new TreeWalker over the subtree rooted at the specified node. 
      */
-    virtual TreeWalker createTreeWalker(const Node */*root*/,
+    virtual TreeWalker createTreeWalker(const NodePtr/*root*/,
                                         unsigned long /*whatToShow*/,
-                                        const NodeFilter */*filter*/,
+                                        const NodeFilter/*filter*/,
                                         bool /*entityReferenceExpansion*/)
                                         throw (dom::DOMException)
         {

diff --git a/src/dom/views.h b/src/dom/views.h
index f7d26bcfa3398ad618b4f57887d31e7ca1fc961a..9e87dfbe7a1aff5ddecc055573f3cdd5cc8fe3d6 100644 (file)
--- a/src/dom/views.h
+++ b/src/dom/views.h
@@ -28,6 +28,19 @@
  *  You should have received a copy of the GNU Lesser General Public
  *  License along with this library; if not, write to the Free Software
  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
+ *  
+ * =========================================================================
+ * NOTES
+ * 
+ * This is the Level 2 Views definition, which is very minimalist.  It is
+ * described here:
+ * http://www.w3.org/TR/2000/REC-DOM-Level-2-Views-20001113
+ * 
+ * Note that SVG uses the DOM Core and Events Level 3, but Level 2 CSS and Views.         
+ * 
+ * The level 3 version is much larger:
+ * http://www.w3.org/TR/2004/NOTE-DOM-Level-3-Views-20040226
+ * Be prepared in the future to adjust to this, if SVG ever switches .
  */
 
 
@@ -61,14 +74,14 @@ class AbstractView;
 #########################################################################*/
 
 /**
- *
+ * A base interface that all views shall derive from.
  */
 class AbstractView
 {
 public:
 
     /**
-     *
+     * The source DocumentView of which this is an AbstractView.
      */
     virtual DocumentView *getDocument()
         {
@@ -125,14 +138,16 @@ private:
 
 
 /**
- *
+ * The DocumentView interface is implemented by Document objects in DOM 
+ * implementations supporting DOM Views. It provides an attribute to retrieve the 
+ * default view of a document.
  */
 class DocumentView
 {
 public:
 
     /**
-     *
+     * The default AbstractView for this Document, or null if none available.
      */
     virtual AbstractView *getDefaultView()
         {