Resolve ambiguity between GetClientXXX() methods in wxOSX wxComboBox.

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

diff --git a/interface/wx/xml/xml.h b/interface/wx/xml/xml.h
index 71ac36a37b8d8eede03ba0f2325b54a5b6b6c384..8605491dd16c63ac8eff3832c4767148305f8869 100644 (file)
--- a/interface/wx/xml/xml.h
+++ b/interface/wx/xml/xml.h
@@ -1,21 +1,49 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        xml/xml.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        xml/xml.h

-// Purpose:     interface of wxXmlNode
+// Purpose:     interface of wxXmlNode, wxXmlAttribute, wxXmlDocument

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /////////////////////////////////////////////////////////////////////////////
 

+
+/// Represents XML node type.
+enum wxXmlNodeType
+{
+    // note: values are synchronized with xmlElementType from libxml
+    wxXML_ELEMENT_NODE       =  1,
+    wxXML_ATTRIBUTE_NODE     =  2,
+    wxXML_TEXT_NODE          =  3,
+    wxXML_CDATA_SECTION_NODE =  4,
+    wxXML_ENTITY_REF_NODE    =  5,
+    wxXML_ENTITY_NODE        =  6,
+    wxXML_PI_NODE            =  7,
+    wxXML_COMMENT_NODE       =  8,
+    wxXML_DOCUMENT_NODE      =  9,
+    wxXML_DOCUMENT_TYPE_NODE = 10,
+    wxXML_DOCUMENT_FRAG_NODE = 11,
+    wxXML_NOTATION_NODE      = 12,
+    wxXML_HTML_DOCUMENT_NODE = 13
+};
+

 /**
     @class wxXmlNode
 
     Represents a node in an XML document. See wxXmlDocument.
 
 /**
     @class wxXmlNode
 
     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
-    @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").
+    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.
+
+    Example: in <tt>\<title\>hi\</title\></tt> there is an element with the name
+    @c title and irrelevant content and one child of type @c wxXML_TEXT_NODE
+    with @c hi as content.
+
+    The @c wxXML_PI_NODE type sets the name to the PI target and the contents to
+    the instructions. Note that whilst the PI instructions are often in the form
+    of pseudo-attributes these do not use the nodes attribute system. It is the users
+    responsibility to code and decode the instruction text.

 
     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).


@@ -28,33 +56,76 @@
 class wxXmlNode
 {
 public:
 class wxXmlNode
 {
 public:

-    //@{

     /**
     /**

-        A simplified version of the first constructor form, assuming a @NULL parent.
+        Creates this XML node and eventually insert it into an existing XML tree.
+
+        @param parent
+            The parent node to which append this node instance.
+            If this argument is @NULL this new node will be floating and it can
+            be appended later to another one using the AddChild() or InsertChild()
+            functions. Otherwise the child is already added to the XML tree by
+            this constructor and it shouldn't be done again.
+        @param type
+            One of the ::wxXmlNodeType enumeration value.
+        @param name
+            The name of the node. This is the string which appears between angular brackets.
+        @param content
+            The content of the node.
+            Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
+        @param attrs
+            If not @NULL, this wxXmlAttribute object and its eventual siblings are attached to the node.
+        @param next
+            If not @NULL, this node and its eventual siblings are attached to the node.
+        @param lineNo
+            Number of line this node was present at in input file or -1.

     */
     wxXmlNode(wxXmlNode* parent, wxXmlNodeType type,
               const wxString& name,
               const wxString& content = wxEmptyString,
               wxXmlAttribute* attrs = NULL,
               wxXmlNode* next = NULL, int lineNo = -1);
     */
     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);
+
+    /**
+        A simplified version of the first constructor form, assuming a @NULL parent.
+
+        @param type
+            One of the ::wxXmlNodeType enumeration value.
+        @param name
+            The name of the node. This is the string which appears between angular brackets.
+        @param content
+            The content of the node.
+            Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
+        @param lineNo
+            Number of line this node was present at in input file or -1.
+    */

     wxXmlNode(wxXmlNodeType type, const wxString& name,
               const wxString& content = wxEmptyString,
               int lineNo = -1);
     wxXmlNode(wxXmlNodeType type, const wxString& name,
               const wxString& content = wxEmptyString,
               int lineNo = -1);

-    //@}
+
+    /**
+        Copy constructor.
+
+        Note that this does NOT copy siblings and parent pointer, i.e. GetParent()
+        and GetNext() will return @NULL after using copy ctor and are never unmodified by operator=().
+        On the other hand, it DOES copy children and attributes.
+    */
+    wxXmlNode(const wxXmlNode& node);

 
     /**
         The virtual destructor. Deletes attached children and attributes.
     */
 
     /**
         The virtual destructor. Deletes attached children and attributes.
     */

-    ~wxXmlNode();
+    virtual ~wxXmlNode();
+
+    /**
+        Appends a attribute with given @a name and @a value to the list of
+        attributes for this node.
+    */
+    virtual void AddAttribute(const wxString& name, const wxString& value);

 
 

-    //@{

     /**
         Appends given attribute to the list of attributes for this node.
     */
     /**
         Appends given attribute to the list of attributes for this node.
     */

-    void AddAttribute(const wxString& name, const wxString& value);
-    void AddAttribute(wxXmlAttribute* attr);
-    //@}
+    virtual void AddAttribute(wxXmlAttribute* attr);

 
     /**
         Adds node @a child as the last child of this node.
 
     /**
         Adds node @a child as the last child of this node.


@@ -68,23 +139,26 @@ public:
 
         @see InsertChild(), InsertChildAfter()
     */
 
         @see InsertChild(), InsertChildAfter()
     */

-    void AddChild(wxXmlNode* child);
+    virtual void AddChild(wxXmlNode* child);

 
     /**
         Removes the first attributes which has the given @a name from the list of
         attributes for this node.
     */
 
     /**
         Removes the first attributes which has the given @a name from the list of
         attributes for this node.
     */

-    bool DeleteAttribute(const wxString& name);
+    virtual bool DeleteAttribute(const wxString& name);
+
+    /**
+        Returns true if a attribute named attrName could be found.
+        The value of that attribute is saved in value (which must not be @NULL).
+    */
+    bool GetAttribute(const wxString& attrName, wxString* value) const;

 
 

-    //@{

     /**
         Returns the value of the attribute named @a attrName if it does exist.
         If it does not exist, the @a 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) const;
-    const wxString  GetAttribute(const wxString& attrName,
-                                 const wxString& defaultVal = wxEmptyString) 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.


@@ -101,30 +175,37 @@ public:
     /**
         Returns the content of this node. Can be an empty string.
         Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type)
     /**
         Returns the content of this node. Can be an empty string.
         Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type)

-        the
-        content is an empty string. See GetNodeContent() for more details.
+        the content is an empty string. See GetNodeContent() for more details.

     */
     */

-    wxString GetContent() const;
+    const wxString& GetContent() const;

 
     /**
 
     /**

-        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).
+        Returns the number of nodes which separate this node from @c grandparent.
+
+        This function searches only the parents of this node until it finds
+        @a grandparent or the @NULL node (which is the parent of non-linked
+        nodes or the parent of a wxXmlDocument's root element node).

     */
     int GetDepth(wxXmlNode* grandparent = NULL) const;
 
     /**
     */
     int GetDepth(wxXmlNode* grandparent = NULL) const;
 
     /**

-        Returns line number of the node in the input XML file or -1 if it is unknown.
+        Returns a flag indicating whether encoding conversion is necessary when saving. The default is @false.
+
+        You can improve saving efficiency considerably by setting this value.
+    */
+    bool GetNoConversion() const;
+
+    /**
+        Returns line number of the node in the input XML file or @c -1 if it is unknown.

     */
     int GetLineNumber() const;
 
     /**
     */
     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() const;
+    const wxString& GetName() const;

 
     /**
         Returns a pointer to the sibling of this node or @NULL if there are no
 
     /**
         Returns a pointer to the sibling of this node or @NULL if there are no


@@ -133,16 +214,26 @@ public:
     wxXmlNode* GetNext() const;
 
     /**
     wxXmlNode* GetNext() const;
 
     /**

-        Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c
-        wxXML_CDATA_SECTION_NODE.
-        This function is very useful since the XML snippet @c
-        "tagnametagcontent/tagname" is represented by
-        expat with the following tag tree:
+        Returns the content of the first child node of type @c wxXML_TEXT_NODE
+        or @c wxXML_CDATA_SECTION_NODE.
+        This function is very useful since the XML snippet @c "tagnametagcontent/tagname"
+        is represented by expat with the following tag tree:
+
+        @code
+        wxXML_ELEMENT_NODE name="tagname", content=""
+        |-- wxXML_TEXT_NODE name="", content="tagcontent"
+        @endcode

 
         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.
+        @code
+        wxXML_ELEMENT_NODE name="tagname", content=""
+        |-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
+        @endcode
+
+        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() const;
 
     */
     wxString GetNodeContent() const;
 


@@ -158,7 +249,7 @@ public:
     wxXmlNodeType GetType() const;
 
     /**
     wxXmlNodeType GetType() const;
 
     /**

-        Returns @true if this node has a attribute named @e attrName.
+        Returns @true if this node has a attribute named @a attrName.

     */
     bool HasAttribute(const wxString& attrName) const;
 
     */
     bool HasAttribute(const wxString& attrName) const;
 


@@ -177,7 +268,7 @@ public:
 
         @see AddChild(), InsertChildAfter()
     */
 
         @see AddChild(), InsertChildAfter()
     */

-    bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode);
+    virtual bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode);

 
     /**
         Inserts the @a child node immediately after @a precedingNode in the
 
     /**
         Inserts the @a child node immediately after @a precedingNode in the


@@ -186,6 +277,8 @@ public:
         @return @true if @a precedingNode has been found and the @a child
                 node has been inserted.
 
         @return @true if @a precedingNode has been found and the @a child
                 node has been inserted.
 

+        @param child
+            The child to insert.

         @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
         @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


@@ -195,38 +288,40 @@ public:
 
         @see InsertChild(), AddChild()
     */
 
         @see InsertChild(), AddChild()
     */

-    bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode);
+    virtual 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

-        whitespaces (spaces,
-        tabs, new lines, etc). Note that this function is locale-independent since the
-        parsing of XML
-        documents must always produce the exact same tree regardless of the locale it
-        runs under.
+        whitespaces (spaces, tabs, new lines, etc).
+
+        Note that this function is locale-independent since the parsing of XML
+        documents must always produce the exact same tree regardless of the
+        locale it runs under.

     */
     bool IsWhitespaceOnly() const;
 
     /**
     */
     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.
-        Note that the caller is reponsible for deleting the removed node in order to
-        avoid memory leaks.
+        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 responsible for deleting the removed node in order
+        to avoid memory leaks.

     */
     */

-    bool RemoveChild(wxXmlNode* child);
+    virtual bool RemoveChild(wxXmlNode* child);

 
     /**
         Sets as first attribute the given wxXmlAttribute object.
 
     /**
         Sets as first attribute the given wxXmlAttribute object.

-        The caller is responsible to delete any previously present attributes attached
-        to this node.
+
+        The caller is responsible for deleting any previously present attributes
+        attached to this node.

     */
     void SetAttributes(wxXmlAttribute* attr);
 
     /**
     */
     void SetAttributes(wxXmlAttribute* attr);
 
     /**

-        Sets as first child the given node. The caller is responsible to delete any
-        previously present
-        children node.
+        Sets as first child the given node.
+
+        The caller is responsible for deleting any previously present children node.

     */
     void SetChildren(wxXmlNode* child);
 
     */
     void SetChildren(wxXmlNode* child);
 


@@ -241,16 +336,23 @@ public:
     void SetName(const wxString& name);
 
     /**
     void SetName(const wxString& name);
 
     /**

-        Sets as sibling the given node. The caller is responsible to delete any
-        previously present
-        sibling node.
+        Sets as sibling the given node.
+
+        The caller is responsible for deleting any previously present sibling node.

     */
     void SetNext(wxXmlNode* next);
 
     /**
     */
     void SetNext(wxXmlNode* next);
 
     /**

-        Sets as parent the given node. The caller is responsible to delete any
-        previously present
-        parent node.
+        Sets a flag to indicate whether encoding conversion is necessary when saving. The default is @false.
+
+        You can improve saving efficiency considerably by setting this value.
+    */
+    void SetNoConversion(bool noconversion);
+
+    /**
+        Sets as parent the given node.
+
+        The caller is responsible for deleting any previously present parent node.

     */
     void SetParent(wxXmlNode* parent);
 
     */
     void SetParent(wxXmlNode* parent);
 


@@ -262,7 +364,7 @@ public:
     /**
         See the copy constructor for more info.
     */
     /**
         See the copy constructor for more info.
     */

-    wxXmlNode operator=(const wxXmlNode& node);
+    wxXmlNode& operator=(const wxXmlNode& node);

 };
 
 
 };
 
 


@@ -272,8 +374,8 @@ public:
 
     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 <tt>\<img src="hello.gif" id="3"/\></tt>, @c src is an attribute
+    with value @c hello.gif and @c id is an attribute with value @c 3.

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


@@ -283,20 +385,22 @@ public:
 class wxXmlAttribute
 {
 public:
 class wxXmlAttribute
 {
 public:

-    //@{

     /**
     /**

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

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

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

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

-    //@}

 
     /**
         The virtual destructor.
     */
 
     /**
         The virtual destructor.
     */

-    ~wxXmlAttribute();
+    virtual ~wxXmlAttribute();

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


@@ -343,63 +447,73 @@ public:
 
     @code
     wxXmlDocument doc;
 
     @code
     wxXmlDocument doc;

-    if (!doc.Load(wxT("myfile.xml")))
-        return @false;
+    if (!doc.Load("myfile.xml"))
+        return false;

 
     // start processing the XML file
 
     // start processing the XML file

-    if (doc.GetRoot()-GetName() != wxT("myroot-node"))
-        return @false;
+    if (doc.GetRoot()->GetName() != "myroot-node")
+        return false;
+
+    // examine prologue
+    wxXmlNode *prolog = doc.GetDocumentNode()->GetChildren();
+    while (prolog) {
+
+        if (prolog->GetType() == wxXML_PI_NODE && prolog->GetName() == "target") {
+
+            // process Process Instruction contents
+            wxString pi = prolog->GetContent();
+
+            ...

 
 

-    wxXmlNode *child = doc.GetRoot()-GetChildren();
+        }
+    }
+
+    wxXmlNode *child = doc.GetRoot()->GetChildren();

     while (child) {
 
     while (child) {
 

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

 
             // process text enclosed by tag1/tag1
 
             // process text enclosed by tag1/tag1

-            wxString content = child-GetNodeContent();
+            wxString content = child->GetNodeContent();

 
             ...
 
             // process attributes of tag1
             wxString attrvalue1 =
 
             ...
 
             // process attributes of tag1
             wxString attrvalue1 =

-                child-GetAttribute(wxT("attr1"),
-                                  wxT("default-value"));
+                child->GetAttribute("attr1", "default-value");

             wxString attrvalue2 =
             wxString attrvalue2 =

-                child-GetAttribute(wxT("attr2"),
-                                  wxT("default-value"));
+                child->GetAttribute("attr2", "default-value");

 
             ...
 
 
             ...
 

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

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

-        child = child-GetNext();
+        child = child->GetNext();

     }
     @endcode
 
     }
     @endcode
 

-    @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:
+    Note that 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:

 
     @code
     wxXmlDocument doc;
 
     @code
     wxXmlDocument doc;

-    doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES);
+    doc.Load("myfile.xml", "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);
+    // myfile2.xml will be identical to myfile.xml saving it this way:
+    doc.Save("myfile2.xml", wxXML_NO_INDENTATION);

     @endcode
 
     Using default parameters, you will get a reformatted document which in general
     @endcode
 
     Using default parameters, you will get a reformatted document which in general

-    is different from
-    the original loaded content:
+    is different from the original loaded content:

 
     @code
     wxXmlDocument doc;
 
     @code
     wxXmlDocument doc;

-    doc.Load(wxT("myfile.xml"));
-    doc.Save(wxT("myfile2.xml"));  // myfile2.xml != myfile.xml
+    doc.Load("myfile.xml");
+    doc.Save("myfile2.xml");  // myfile2.xml != myfile.xml

     @endcode
 
     @library{wxxml}
     @endcode
 
     @library{wxxml}


@@ -410,82 +524,164 @@ public:
 class wxXmlDocument : public wxObject
 {
 public:
 class wxXmlDocument : public wxObject
 {
 public:

-    //@{

     /**
     /**

-        Copy constructor. Deep copies all the XML tree of the given document.
+        Default constructor.

     */
     wxXmlDocument();
     */
     wxXmlDocument();

-    wxXmlDocument(const wxString& filename);
-    wxXmlDocument(wxInputStream& stream);
+
+    /**
+        Copy constructor. Deep copies all the XML tree of the given document.
+    */

     wxXmlDocument(const wxXmlDocument& doc);
     wxXmlDocument(const wxXmlDocument& doc);

-    //@}
+
+    /**
+        Loads the given filename using the given encoding. See Load().
+    */
+    wxXmlDocument(const wxString& filename,
+                  const wxString& encoding = "UTF-8"));
+
+    /**
+        Loads the XML document from given stream using the given encoding. See Load().
+    */
+    wxXmlDocument(wxInputStream& stream,
+                  const wxString& encoding = "UTF-8");

 
     /**
         Virtual destructor. Frees the document root node.
     */
 
     /**
         Virtual destructor. Frees the document root node.
     */

-    ~wxXmlDocument();
+    virtual ~wxXmlDocument();

 
     /**
 
     /**

-        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.
+        Appends a Process Instruction or Comment node to the document prologue.
+
+        Calling this function will create a prologue or attach the node to the
+        end of an existing prologue.
+
+        @since 2.9.2
+    */
+    void AppendToProlog(wxXmlNode* node);
+
+    /**
+        Detaches the document node and returns it.
+
+        The document node will be set to @NULL and thus IsOk() will
+        return @false after calling this function.
+
+        Note that the caller is responsible for deleting the returned node in order
+        to avoid memory leaks.
+
+        @since 2.9.2
+    */
+    wxXmlNode* DetachDocumentNode();
+
+    /**
+        Detaches the root entity node and returns it.
+
+        After calling this function, the document node will remain together with
+        any prologue nodes, but IsOk() will return @false since the root entity
+        will be missing.
+
+        Note that the caller is reponsible for deleting the returned node in order
+        to avoid memory leaks.

     */
     wxXmlNode* DetachRoot();
 
     /**
         Returns encoding of in-memory representation of the document
         (same as passed to Load() or constructor, defaults to UTF-8).
     */
     wxXmlNode* DetachRoot();
 
     /**
         Returns encoding of in-memory representation of the document
         (same as passed to Load() or constructor, defaults to UTF-8).

+

         @note this is meaningless in Unicode build where data are stored as @c wchar_t*.
     */
     wxString GetEncoding() const;
 
     /**
         Returns encoding of document (may be empty).
         @note this is meaningless in Unicode build where data are stored as @c wchar_t*.
     */
     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!
+
+        @note This is the encoding original file was saved in, @b not the
+              encoding of in-memory representation!

     */
     */

-    wxString GetFileEncoding() const;
+    const wxString& GetFileEncoding() const;

 
     /**
 
     /**

-        Returns the root node of the document.
+        Returns the document node of the document.
+
+        @since 2.9.2
+    */
+    wxXmlNode* GetDocumentNode() const;
+
+    /**
+        Returns the root element node of the document.

     */
     wxXmlNode* GetRoot() const;
 
     /**
         Returns the version of document.
     */
     wxXmlNode* GetRoot() const;
 
     /**
         Returns the version of document.

-        This is the value in the @c ?xml version="1.0"? header of the XML document.
-        If the version attribute was not explicitely given in the header, this function
+
+        This is the value in the @c \<?xml version="1.0"?\> header of the XML document.
+        If the version attribute was not explicitly given in the header, this function

         returns an empty string.
     */
         returns an empty string.
     */

-    wxString GetVersion() const;
+    const wxString& GetVersion() const;

 
     /**
         Returns @true if the document has been loaded successfully.
     */
     bool IsOk() const;
 
 
     /**
         Returns @true if the document has been loaded successfully.
     */
     bool IsOk() const;
 

-    //@{
+
+    /**
+        Parses @a filename as an xml document and loads its data.
+
+        If @a flags does not contain wxXMLDOC_KEEP_WHITESPACE_NODES, then, while loading,
+        all nodes of type @c wxXML_TEXT_NODE (see wxXmlNode) are automatically skipped
+        if they contain whitespaces only.
+
+        The removal of these nodes makes the load process slightly faster and requires
+        less memory however makes impossible to recreate exactly the loaded text with a
+        Save() call later. Read the initial description of this class for more info.
+
+        Returns true on success, false otherwise.
+    */
+    virtual bool Load(const wxString& filename,
+                      const wxString& encoding = "UTF-8", int flags = wxXMLDOC_NONE);
+
+    /**
+        Like Load(const wxString&, const wxString&, int) but takes the data from
+        given input stream.
+    */
+    virtual bool Load(wxInputStream& stream,
+                      const wxString& encoding = "UTF-8", int flags = wxXMLDOC_NONE);
+
+    /**
+        Saves XML tree creating a file named with given string.
+
+        If @a indentstep is greater than or equal to zero, then, while saving,
+        an automatic indentation is added with steps composed by indentstep spaces.
+
+        If @a indentstep is @c wxXML_NO_INDENTATION, then, automatic indentation
+        is turned off.
+    */
+    virtual bool Save(const wxString& filename, int indentstep = 2) const;
+

     /**
     /**

-        , @b int@e flags = wxXMLDOC_NONE)
-        Like above but takes the data from given input stream.
+        Saves XML tree in the given output stream.
+        See Save(const wxString&, int) for a description of @a indentstep.

     */
     */

-    bool Load(const wxString& filename);
-    int bool Load(wxInputStream& stream);
-    //@}
+    virtual bool Save(wxOutputStream& stream, int indentstep = 2) const;

 
 

-    //@{

     /**
     /**

-        Saves XML tree in the given output stream. See other overload for a description
-        of @c indentstep.
+        Sets the document node of this document.
+
+        Deletes any previous document node.
+        Use DetachDocumentNode() and then SetDocumentNode() if you want to
+        replace the document node without deleting the old document tree.
+
+        @since 2.9.2

     */
     */

-    bool Save(const wxString& filename, int indentstep = 1) const;
-    const bool Save(wxOutputStream& stream, int indentstep = 1) const;
-    //@}
+    void SetDocumentNode(wxXmlNode* node);

 
     /**
 
     /**

-        Sets the enconding of the document.
+        Sets the encoding of the document.

     */
     void SetEncoding(const wxString& enc);
 
     */
     void SetEncoding(const wxString& enc);
 


@@ -495,10 +691,10 @@ public:
     void SetFileEncoding(const wxString& encoding);
 
     /**
     void SetFileEncoding(const wxString& encoding);
 
     /**

-        Sets the root node of this document. Deletes previous root node.
-        Use DetachRoot() and then
-        SetRoot() if you want
-        to replace the root node without deleting the old document tree.
+        Sets the root element node of this document.
+
+        Will create the document node if necessary. Any previous
+        root element node is deleted.

     */
     void SetRoot(wxXmlNode* node);
 
     */
     void SetRoot(wxXmlNode* node);
 


@@ -510,6 +706,14 @@ public:
     /**
         Deep copies the given document.
     */
     /**
         Deep copies the given document.
     */

-    wxXmlDocument& operator operator=(const wxXmlDocument& doc);
+    wxXmlDocument& operator=(const wxXmlDocument& doc);
+
+    /**
+       Get expat library version information.
+
+       @since 2.9.2
+       @see wxVersionInfo
+    */
+    static wxVersionInfo GetLibraryVersionInfo();

 };
 
 };