X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef..40c53d1b49569facfd71e30ef56d26df790621c4:/interface/xml/xml.h

diff --git a/interface/xml/xml.h b/interface/xml/xml.h
index faa4fa12fe..bbc63c62ed 100644
--- a/interface/xml/xml.h
+++ b/interface/xml/xml.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        xml/xml.h
-// Purpose:     documentation for wxXmlNode class
+// Purpose:     interface of wxXmlNode
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -24,8 +24,7 @@
     @library{wxxml}
     @category{xml}
 
-    @seealso
-    wxXmlDocument, wxXmlAttribute
+    @see wxXmlDocument, wxXmlAttribute
 */
 class wxXmlNode
 {
@@ -59,9 +58,16 @@ public:
     //@}
 
     /**
-        Adds the given node as child of this node. To attach a second children to this
-        node, use the
-        SetNext() function of the @a child node.
+        Adds node @a child as the last child of this node.
+
+        @note
+        Note that this function works in O(n) time where @e n is the number
+        of existing children. Consequently, adding large number of child
+        nodes using this method can be expensive, because it has O(n^2) time
+        complexity in number of nodes to be added. Use InsertChildAfter() to
+        populate XML tree in linear time.
+
+        @see InsertChild(), InsertChildAfter()
     */
     void AddChild(wxXmlNode* child);
 
@@ -76,22 +82,22 @@ public:
         Returns the value of the attribute named @a attrName if it does exist.
         If it does not exist, the @a defaultVal is returned.
     */
-    bool GetAttribute(const wxString& attrName, wxString* value);
-    wxString GetAttribute(const wxString& attrName,
-                          const wxString& defaultVal);
+    bool GetAttribute(const wxString& attrName, wxString* value) const;
+    const wxString  GetAttribute(const wxString& attrName,
+                                 const wxString& defaultVal = wxEmptyString) const;
     //@}
 
     /**
         Return a pointer to the first attribute of this node.
     */
-    wxXmlAttribute* GetAttributes();
+    wxXmlAttribute* GetAttributes() const;
 
     /**
         Returns the first child of this node.
         To get a pointer to the second child of this node (if it does exist), use the
         GetNext() function on the returned value.
     */
-    wxXmlNode* GetChildren();
+    wxXmlNode* GetChildren() const;
 
     /**
         Returns the content of this node. Can be an empty string.
@@ -99,7 +105,7 @@ public:
         the
         content is an empty string. See GetNodeContent() for more details.
     */
-    wxString GetContent();
+    wxString GetContent() const;
 
     /**
         Returns the number of nodes which separe this node from @c grandparent.
@@ -108,24 +114,24 @@ public:
         or the @NULL node (which is the parent of non-linked nodes or the parent of a
         wxXmlDocument's root node).
     */
-    int GetDepth(wxXmlNode* grandparent = NULL);
+    int GetDepth(wxXmlNode* grandparent = NULL) const;
 
     /**
         Returns line number of the node in the input XML file or -1 if it is unknown.
     */
-    int GetLineNumber();
+    int GetLineNumber() const;
 
     /**
         Returns the name of this node. Can be an empty string (e.g. for nodes of type
         @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE).
     */
-    wxString GetName();
+    wxString GetName() const;
 
     /**
         Returns a pointer to the sibling of this node or @NULL if there are no
         siblings.
     */
-    wxXmlNode* GetNext();
+    wxXmlNode* GetNext() const;
 
     /**
         Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c
@@ -133,39 +139,64 @@ public:
         This function is very useful since the XML snippet @c
         "tagnametagcontent/tagname" is represented by
         expat with the following tag tree:
-        
+
         or eventually:
-        
+
         An empty string is returned if the node has no children of type @c
         wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty.
     */
-    wxString GetNodeContent();
+    wxString GetNodeContent() const;
 
     /**
         Returns a pointer to the parent of this node or @NULL if this node has no
         parent.
     */
-    wxXmlNode* GetParent();
+    wxXmlNode* GetParent() const;
 
     /**
         Returns the type of this node.
     */
-    wxXmlNodeType GetType();
+    wxXmlNodeType GetType() const;
 
     /**
         Returns @true if this node has a attribute named @e attrName.
     */
-    bool HasAttribute(const wxString& attrName);
+    bool HasAttribute(const wxString& attrName) const;
 
     /**
-        Inserts the @a child node after @a before_node in the children list.
-        If @a before_node is @NULL, then @a child is prepended to the list of
-        children and
-        becomes the first child of this node.
-        Returns @true if @a before_node has been found and the @a child node has been
-        inserted.
+        Inserts the @a child node immediately before @a followingNode in the
+        children list.
+
+        @return @true if @a followingNode has been found and the @a child
+                node has been inserted.
+
+        @note
+        For historical reasons, @a followingNode may be @NULL. In that case,
+        then @a child is prepended to the list of children and becomes the
+        first child of this node, i.e. it behaves identically to using the
+        first children (as returned by GetChildren()) for @a followingNode).
+
+        @see AddChild(), InsertChildAfter()
     */
-    bool InsertChild(wxXmlNode* child, wxXmlNode* before_node);
+    bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode);
+
+    /**
+        Inserts the @a child node immediately after @a precedingNode in the
+        children list.
+
+        @return @true if @a precedingNode has been found and the @a child
+                node has been inserted.
+
+        @param precedingNode
+            The node to insert @a child after. As a special case, this can be
+            @NULL if this node has no children yet -- in that case, @a child
+            will become this node's only child node.
+
+        @since 2.8.8
+
+        @see InsertChild(), AddChild()
+    */
+    bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode);
 
     /**
         Returns @true if the content of this node is a string containing only
@@ -175,7 +206,7 @@ public:
         documents must always produce the exact same tree regardless of the locale it
         runs under.
     */
-    bool IsWhitespaceOnly();
+    bool IsWhitespaceOnly() const;
 
     /**
         Removes the given node from the children list. Returns @true if the node was
@@ -236,6 +267,7 @@ public:
 };
 
 
+
 /**
     @class wxXmlAttribute
     @headerfile xml.h wx/xml/xml.h
@@ -248,8 +280,7 @@ public:
     @library{wxxml}
     @category{xml}
 
-    @seealso
-    wxXmlDocument, wxXmlNode
+    @see wxXmlDocument, wxXmlNode
 */
 class wxXmlAttribute
 {
@@ -272,17 +303,17 @@ public:
     /**
         Returns the name of this attribute.
     */
-    wxString GetName();
+    wxString GetName() const;
 
     /**
         Returns the sibling of this attribute or @NULL if there are no siblings.
     */
-    wxXmlAttribute* GetNext();
+    wxXmlAttribute* GetNext() const;
 
     /**
         Returns the value of this attribute.
     */
-    wxString GetValue();
+    wxString GetValue() const;
 
     /**
         Sets the name of this attribute.
@@ -301,6 +332,7 @@ public:
 };
 
 
+
 /**
     @class wxXmlDocument
     @headerfile xml.h wx/xml/xml.h
@@ -350,7 +382,7 @@ public:
     }
     @endcode
 
-    @b Note: if you want to preserve the original formatting of the loaded file
+    @note if you want to preserve the original formatting of the loaded file
     including whitespaces
     and indentation, you need to turn off whitespace-only textnode removal and
     automatic indentation:
@@ -376,8 +408,7 @@ public:
     @library{wxxml}
     @category{xml}
 
-    @seealso
-    wxXmlNode, wxXmlAttribute
+    @see wxXmlNode, wxXmlAttribute
 */
 class wxXmlDocument : public wxObject
 {
@@ -409,21 +440,21 @@ public:
     /**
         Returns encoding of in-memory representation of the document
         (same as passed to Load() or constructor, defaults to UTF-8).
-        NB: this is meaningless in Unicode build where data are stored as @c wchar_t*.
+        @note this is meaningless in Unicode build where data are stored as @c wchar_t*.
     */
-    wxString GetEncoding();
+    wxString GetEncoding() const;
 
     /**
         Returns encoding of document (may be empty).
         Note: this is the encoding original file was saved in, @b not the
         encoding of in-memory representation!
     */
-    wxString GetFileEncoding();
+    wxString GetFileEncoding() const;
 
     /**
         Returns the root node of the document.
     */
-    wxXmlNode* GetRoot();
+    wxXmlNode* GetRoot() const;
 
     /**
         Returns the version of document.
@@ -431,12 +462,12 @@ public:
         If the version attribute was not explicitely given in the header, this function
         returns an empty string.
     */
-    wxString GetVersion();
+    wxString GetVersion() const;
 
     /**
         Returns @true if the document has been loaded successfully.
     */
-    bool IsOk();
+    bool IsOk() const;
 
     //@{
     /**
@@ -452,8 +483,8 @@ public:
         Saves XML tree in the given output stream. See other overload for a description
         of @c indentstep.
     */
-    bool Save(const wxString& filename, int indentstep = 1);
-    bool Save(wxOutputStream& stream, int indentstep = 1);
+    bool Save(const wxString& filename, int indentstep = 1) const;
+    const bool Save(wxOutputStream& stream, int indentstep = 1) const;
     //@}
 
     /**
@@ -484,3 +515,4 @@ public:
     */
     wxXmlDocument& operator operator=(const wxXmlDocument& doc);
 };
+