compilation fix for PCH-less build

[wxWidgets.git] / interface / xml / xml.h

diff --git a/interface/xml/xml.h b/interface/xml/xml.h
index 3925e340f329e174f7eaf36cc21c711f2f990236..bbc63c62ed9c7a76de457df0ab4f5c9f870a0ce8 100644 (file)
--- a/interface/xml/xml.h
+++ b/interface/xml/xml.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        xml/xml.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        xml/xml.h

-// Purpose:     documentation for wxXmlNode class
+// Purpose:     interface of wxXmlNode

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -9,25 +9,24 @@
 /**
     @class wxXmlNode
     @headerfile xml.h wx/xml/xml.h
 /**
     @class wxXmlNode
     @headerfile xml.h wx/xml/xml.h

-    
+

     Represents a node in an XML document. See wxXmlDocument.
     Represents a node in an XML document. See wxXmlDocument.

-    
-    Node has a name and may have content and attributes. Most common node types are 
-    @c wxXML_TEXT_NODE (name and attributes are irrelevant) and 
+
+    Node has a name and may have content and attributes. Most common node types are
+    @c wxXML_TEXT_NODE (name and attributes are irrelevant) and

     @c wxXML_ELEMENT_NODE (e.g. in @c titlehi/title there is an element
     with name="title", irrelevant content and one child (@c wxXML_TEXT_NODE
     with content="hi").
     @c wxXML_ELEMENT_NODE (e.g. in @c titlehi/title there is an element
     with name="title", irrelevant content and one child (@c wxXML_TEXT_NODE
     with content="hi").

-    
+

     If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to
     wxXmlDocument::Load (default is UTF-8).
     If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to
     wxXmlDocument::Load (default is UTF-8).

-    
+

     @library{wxxml}
     @category{xml}
     @library{wxxml}
     @category{xml}

-    
-    @seealso
-    wxXmlDocument, wxXmlAttribute
+
+    @see wxXmlDocument, wxXmlAttribute

 */
 */

-class wxXmlNode 
+class wxXmlNode

 {
 public:
     //@{
 {
 public:
     //@{


@@ -37,12 +36,12 @@ public:
     wxXmlNode(wxXmlNode* parent, wxXmlNodeType type,
               const wxString& name,
               const wxString& content = wxEmptyString,
     wxXmlNode(wxXmlNode* parent, wxXmlNodeType type,
               const wxString& name,
               const wxString& content = wxEmptyString,

-              wxXmlAttribute* attrs = @NULL,
-              wxXmlNode* next = @NULL, int lineNo = -1);
-        wxXmlNode(const wxXmlNode& node);
-        wxXmlNode(wxXmlNodeType type, const wxString& name,
-                  const wxString& content = wxEmptyString,
-                  int lineNo = -1);
+              wxXmlAttribute* attrs = NULL,
+              wxXmlNode* next = NULL, int lineNo = -1);
+    wxXmlNode(const wxXmlNode& node);
+    wxXmlNode(wxXmlNodeType type, const wxString& name,
+              const wxString& content = wxEmptyString,
+              int lineNo = -1);

     //@}
 
     /**
     //@}
 
     /**


@@ -55,43 +54,50 @@ public:
         Appends given attribute to the list of attributes for this node.
     */
     void AddAttribute(const wxString& name, const wxString& value);
         Appends given attribute to the list of attributes for this node.
     */
     void AddAttribute(const wxString& name, const wxString& value);

-        void AddAttribute(wxXmlAttribute* attr);
+    void AddAttribute(wxXmlAttribute* attr);

     //@}
 
     /**
     //@}
 
     /**

-        Adds the given node as child of this node. To attach a second children to this
-        node, use the
-        SetNext() function of the @e 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);
 
     /**
     */
     void AddChild(wxXmlNode* child);
 
     /**

-        Removes the first attributes which has the given @e name from the list of
+        Removes the first attributes which has the given @a name from the list of

         attributes for this node.
     */
     bool DeleteAttribute(const wxString& name);
 
     //@{
     /**
         attributes for this node.
     */
     bool DeleteAttribute(const wxString& name);
 
     //@{
     /**

-        Returns the value of the attribute named @e attrName if it does exist.
-        If it does not exist, the @e defaultVal is returned.
+        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.
     */
     //@}
 
     /**
         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.
     */
 
     /**
         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.
 
     /**
         Returns the content of this node. Can be an empty string.


@@ -99,34 +105,33 @@ public:
         the
         content is an empty string. See GetNodeContent() for more details.
     */
         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.
 
     /**
         Returns the number of nodes which separe this node from @c grandparent.

-        

         This function searches only the parents of this node until it finds @c
         grandparent
         or the @NULL node (which is the parent of non-linked nodes or the parent of a
         wxXmlDocument's root node).
     */
         This function searches only the parents of this node until it finds @c
         grandparent
         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.
     */
 
     /**
         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).
     */
 
     /**
         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.
     */
 
     /**
         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
 
     /**
         Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c


@@ -134,37 +139,64 @@ public:
         This function is very useful since the XML snippet @c
         "tagnametagcontent/tagname" is represented by
         expat with the following tag tree:
         This function is very useful since the XML snippet @c
         "tagnametagcontent/tagname" is represented by
         expat with the following tag tree:

+

         or eventually:
         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.
     */
         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.
     */
 
     /**
         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.
     */
 
     /**
         Returns the type of this node.
     */

-    wxXmlNodeType GetType();
+    wxXmlNodeType GetType() const;

 
     /**
         Returns @true if this node has a attribute named @e attrName.
     */
 
     /**
         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 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* followingNode);

 
     /**
 
     /**

-        Inserts the @e child node after @e before_node in the children list.
-        If @e before_node is @NULL, then @e child is prepended to the list of
-        children and
-        becomes the first child of this node.
-        Returns @true if @e before_node has been found and the @e child node has been
-        inserted.
+        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 InsertChild(wxXmlNode* child, wxXmlNode* before_node);
+    bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode);

 
     /**
         Returns @true if the content of this node is a string containing only
 
     /**
         Returns @true if the content of this node is a string containing only


@@ -174,13 +206,12 @@ public:
         documents must always produce the exact same tree regardless of the locale it
         runs under.
     */
         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
         found and removed
         or @false if the node could not be found.
 
     /**
         Removes the given node from the children list. Returns @true if the node was
         found and removed
         or @false if the node could not be found.

-        

         Note that the caller is reponsible for deleting the removed node in order to
         avoid memory leaks.
     */
         Note that the caller is reponsible for deleting the removed node in order to
         avoid memory leaks.
     */


@@ -236,32 +267,32 @@ public:
 };
 
 
 };
 
 

+

 /**
     @class wxXmlAttribute
     @headerfile xml.h wx/xml/xml.h
 /**
     @class wxXmlAttribute
     @headerfile xml.h wx/xml/xml.h

-    
+

     Represents a node attribute.
     Represents a node attribute.

-    
+

     Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value
     @c "hello.gif" and @c "id" is a attribute with value @c "3".
     Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value
     @c "hello.gif" and @c "id" is a attribute with value @c "3".

-    
+

     @library{wxxml}
     @category{xml}
     @library{wxxml}
     @category{xml}

-    
-    @seealso
-    wxXmlDocument, wxXmlNode
+
+    @see wxXmlDocument, wxXmlNode

 */
 */

-class wxXmlAttribute 
+class wxXmlAttribute

 {
 public:
     //@{
     /**
 {
 public:
     //@{
     /**

-        Creates the attribute with given @e name and @e value.
-        If @e next is not @NULL, then sets it as sibling of this attribute.
+        Creates the attribute with given @a name and @e value.
+        If @a next is not @NULL, then sets it as sibling of this attribute.

     */
     wxXmlAttribute();
     */
     wxXmlAttribute();

-        wxXmlAttribute(const wxString& name, const wxString& value,
-                       wxXmlAttribute* next = @NULL);
+    wxXmlAttribute(const wxString& name, const wxString& value,
+                   wxXmlAttribute* next = NULL);

     //@}
 
     /**
     //@}
 
     /**


@@ -272,17 +303,17 @@ public:
     /**
         Returns the name of this attribute.
     */
     /**
         Returns the name of this attribute.
     */

-    wxString GetName();
+    wxString GetName() const;

 
     /**
         Returns the sibling of this attribute or @NULL if there are no siblings.
     */
 
     /**
         Returns the sibling of this attribute or @NULL if there are no siblings.
     */

-    wxXmlAttribute* GetNext();
+    wxXmlAttribute* GetNext() const;

 
     /**
         Returns the value of this attribute.
     */
 
     /**
         Returns the value of this attribute.
     */

-    wxString GetValue();
+    wxString GetValue() const;

 
     /**
         Sets the name of this attribute.
 
     /**
         Sets the name of this attribute.


@@ -301,83 +332,83 @@ public:
 };
 
 
 };
 
 

+

 /**
     @class wxXmlDocument
     @headerfile xml.h wx/xml/xml.h
 /**
     @class wxXmlDocument
     @headerfile xml.h wx/xml/xml.h

-    
+

     This class holds XML data/document as parsed by XML parser in the root node.
     This class holds XML data/document as parsed by XML parser in the root node.

-    
+

     wxXmlDocument internally uses the expat library which comes with wxWidgets to
     parse the given stream.
     wxXmlDocument internally uses the expat library which comes with wxWidgets to
     parse the given stream.

-    
+

     A simple example of using XML classes is:
     A simple example of using XML classes is:

-    
+

     @code
     wxXmlDocument doc;
     if (!doc.Load(wxT("myfile.xml")))
         return @false;
     @code
     wxXmlDocument doc;
     if (!doc.Load(wxT("myfile.xml")))
         return @false;

-    
+

     // start processing the XML file
     if (doc.GetRoot()-GetName() != wxT("myroot-node"))
         return @false;
     // start processing the XML file
     if (doc.GetRoot()-GetName() != wxT("myroot-node"))
         return @false;

-    
+

     wxXmlNode *child = doc.GetRoot()-GetChildren();
     while (child) {
     wxXmlNode *child = doc.GetRoot()-GetChildren();
     while (child) {

-    
+

         if (child-GetName() == wxT("tag1")) {
         if (child-GetName() == wxT("tag1")) {

-    
+

             // process text enclosed by tag1/tag1
             wxString content = child-GetNodeContent();
             // process text enclosed by tag1/tag1
             wxString content = child-GetNodeContent();

-    
+

             ...
             ...

-    
+

             // process attributes of tag1
             // process attributes of tag1

-            wxString attrvalue1 = 
-                child-GetAttribute(wxT("attr1"), 
+            wxString attrvalue1 =
+                child-GetAttribute(wxT("attr1"),

                                   wxT("default-value"));
                                   wxT("default-value"));

-            wxString attrvalue2 = 
-                child-GetAttribute(wxT("attr2"), 
+            wxString attrvalue2 =
+                child-GetAttribute(wxT("attr2"),

                                   wxT("default-value"));
                                   wxT("default-value"));

-    
+

             ...
             ...

-    
+

         } else if (child-GetName() == wxT("tag2")) {
         } else if (child-GetName() == wxT("tag2")) {

-    
+

             // process tag2 ...
         }
             // process tag2 ...
         }

-    
+

         child = child-GetNext();
     }
     @endcode
         child = child-GetNext();
     }
     @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:
     including whitespaces
     and indentation, you need to turn off whitespace-only textnode removal and
     automatic indentation:

-    
+

     @code
     wxXmlDocument doc;
     doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES);
     @code
     wxXmlDocument doc;
     doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES);

-    
+

     // myfile2.xml will be indentic to myfile.xml saving it this way:
     doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION);
     @endcode
     // myfile2.xml will be indentic to myfile.xml saving it this way:
     doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION);
     @endcode

-    
+

     Using default parameters, you will get a reformatted document which in general
     is different from
     the original loaded content:
     Using default parameters, you will get a reformatted document which in general
     is different from
     the original loaded content:

-    
+

     @code
     wxXmlDocument doc;
     doc.Load(wxT("myfile.xml"));
     doc.Save(wxT("myfile2.xml"));  // myfile2.xml != myfile.xml
     @endcode
     @code
     wxXmlDocument doc;
     doc.Load(wxT("myfile.xml"));
     doc.Save(wxT("myfile2.xml"));  // myfile2.xml != myfile.xml
     @endcode

-    
+

     @library{wxxml}
     @category{xml}
     @library{wxxml}
     @category{xml}

-    
-    @seealso
-    wxXmlNode, wxXmlAttribute
+
+    @see wxXmlNode, wxXmlAttribute

 */
 class wxXmlDocument : public wxObject
 {
 */
 class wxXmlDocument : public wxObject
 {


@@ -387,9 +418,9 @@ public:
         Copy constructor. Deep copies all the XML tree of the given document.
     */
     wxXmlDocument();
         Copy constructor. Deep copies all the XML tree of the given document.
     */
     wxXmlDocument();

-        wxXmlDocument(const wxString& filename);
-        wxXmlDocument(wxInputStream& stream);
-        wxXmlDocument(const wxXmlDocument& doc);
+    wxXmlDocument(const wxString& filename);
+    wxXmlDocument(wxInputStream& stream);
+    wxXmlDocument(const wxXmlDocument& doc);

     //@}
 
     /**
     //@}
 
     /**


@@ -401,7 +432,6 @@ public:
         Detaches the document root node and returns it. The document root node will be
         set to @NULL
         and thus IsOk() will return @false after calling this function.
         Detaches the document root node and returns it. The document root node will be
         set to @NULL
         and thus IsOk() will return @false after calling this function.

-        

         Note that the caller is reponsible for deleting the returned node in order to
         avoid memory leaks.
     */
         Note that the caller is reponsible for deleting the returned node in order to
         avoid memory leaks.
     */


@@ -410,23 +440,21 @@ public:
     /**
         Returns encoding of in-memory representation of the document
         (same as passed to Load() or constructor, defaults to UTF-8).
     /**
         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).
 
     /**
         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!
     */
         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.
     */
 
     /**
         Returns the root node of the document.
     */

-    wxXmlNode* GetRoot();
+    wxXmlNode* GetRoot() const;

 
     /**
         Returns the version of document.
 
     /**
         Returns the version of document.


@@ -434,21 +462,20 @@ public:
         If the version attribute was not explicitely given in the header, this function
         returns an empty string.
     */
         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.
     */
 
     /**
         Returns @true if the document has been loaded successfully.
     */

-#define bool IsOk()     /* implementation is private */
+    bool IsOk() const;

 
     //@{
     /**
         , @b int@e flags = wxXMLDOC_NONE)
 
     //@{
     /**
         , @b int@e flags = wxXMLDOC_NONE)

-        

         Like above but takes the data from given input stream.
     */
     bool Load(const wxString& filename);
         Like above but takes the data from given input stream.
     */
     bool Load(const wxString& filename);

-        int bool Load(wxInputStream& stream);
+    int bool Load(wxInputStream& stream);

     //@}
 
     //@{
     //@}
 
     //@{


@@ -456,8 +483,8 @@ public:
         Saves XML tree in the given output stream. See other overload for a description
         of @c indentstep.
     */
         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;

     //@}
 
     /**
     //@}
 
     /**


@@ -472,7 +499,7 @@ public:
 
     /**
         Sets the root node of this document. Deletes previous root node.
 
     /**
         Sets the root node of this document. Deletes previous root node.

-        Use DetachRoot() and then 
+        Use DetachRoot() and then

         SetRoot() if you want
         to replace the root node without deleting the old document tree.
     */
         SetRoot() if you want
         to replace the root node without deleting the old document tree.
     */


@@ -488,3 +515,4 @@ public:
     */
     wxXmlDocument& operator operator=(const wxXmlDocument& doc);
 };
     */
     wxXmlDocument& operator operator=(const wxXmlDocument& doc);
 };

+