Applied patch [ 1432449 ] wxXml API documentation

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@37994 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/classes.tex

@@ -373,6 +373,9 @@
 \input wizard.tex
 \input wizevt.tex
 \input wizpage.tex
+\input xmldocument.tex
+\input xmlnode.tex
+\input xmlproperty.tex
 \input xmlres.tex
 \input xmlresh.tex
 \input zipstrm.tex

docs/latex/wx/xmldocument.tex

@@ -0,0 +1,139 @@
+\section{\class{wxXmlDocument}}\label{wxxmldocument}
+
+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.
+
+\wxheading{Derived from}
+
+\helpref{wxObject}{wxobject}
+
+\wxheading{Include files}
+
+<wx/xml/xml.h>
+
+\wxheading{See also}
+
+\helpref{wxXmlNode}{wxxmlnode}, \helpref{wxXmlProperty}{wxxmlproperty}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxXmlDocument::wxXmlDocument}\label{wxxmldocumentwxxmldocument}
+
+\func{}{wxXmlDocument}{\void}
+
+
+\func{}{wxXmlDocument}{\param{const wxString\& }{filename}, \param{const wxString\& }{encoding = wxT("UTF-8")}}
+
+Loads the given {\it filename} using the given encoding. See \helpref{Load()}{wxxmldocumentload}.
+
+\func{}{wxXmlDocument}{\param{wxInputStream\& }{stream}, \param{const wxString\& }{encoding = wxT("UTF-8")}}
+
+Loads the XML document from given stream using the given encoding. See \helpref{Load()}{wxxmldocumentload}.
+
+\func{}{wxXmlDocument}{\param{const wxXmlDocument\& }{doc}}
+
+Copy constructor.
+
+\membersection{wxXmlDocument::\destruct{wxXmlDocument}}\label{wxxmldocumentdtor}
+
+\func{}{\destruct{wxXmlDocument}}{\void}
+
+Virtual destructor. Frees the document root node.
+
+\membersection{wxXmlDocument::GetEncoding}\label{wxxmldocumentgetencoding}
+
+\constfunc{wxString}{GetEncoding}{\void}
+
+Returns encoding of in-memory representation of the document
+(same as passed to \helpref{Load()}{wxxmldocumentload} or constructor, defaults to UTF-8).
+
+NB: this is meaningless in Unicode build where data are stored as wchar\_t*.
+
+
+\membersection{wxXmlDocument::GetFileEncoding}\label{wxxmldocumentgetfileencoding}
+
+\constfunc{wxString}{GetFileEncoding}{\void}
+
+Returns encoding of document (may be empty).
+
+Note: this is the encoding original file was saved in, *not* the
+encoding of in-memory representation!
+
+
+\membersection{wxXmlDocument::GetRoot}\label{wxxmldocumentgetroot}
+
+\constfunc{wxXmlNode*}{GetRoot}{\void}
+
+Returns the root node of the document.
+
+
+\membersection{wxXmlDocument::GetVersion}\label{wxxmldocumentgetversion}
+
+\constfunc{wxString}{GetVersion}{\void}
+
+Returns the version of document.
+This is the value in the {\tt <?xml version="1.0"?>} header of the XML document.
+If the version property was not explicitely given in the header, this function
+returns an empty string.
+
+
+\membersection{wxXmlDocument::IsOk}\label{wxxmldocumentisok}
+
+\constfunc{bool}{IsOk}{\void}
+
+Returns \true if the document has been loaded successfully.
+
+
+\membersection{wxXmlDocument::Load}\label{wxxmldocumentload}
+
+\func{bool}{Load}{\param{const wxString\& }{filename}, \param{const wxString\& }{encoding = wxT("UTF-8")}}
+
+Parses {\it filename} as an xml document and loads data. Returns \true on success, \false otherwise.
+
+\func{bool}{Load}{\param{wxInputStream\& }{stream}, \param{const wxString\& }{encoding = wxT("UTF-8")}}
+
+Like above but takes the data from given input stream.
+
+\membersection{wxXmlDocument::Save}\label{wxxmldocumentsave}
+
+\constfunc{bool}{Save}{\param{const wxString\& }{filename}}
+
+Saves XML tree creating a file named with given string.
+
+\constfunc{bool}{Save}{\param{wxOutputStream\& }{stream}}
+
+Saves XML tree in the given output stream.
+
+\membersection{wxXmlDocument::SetEncoding}\label{wxxmldocumentsetencoding}
+
+\func{void}{SetEncoding}{\param{const wxString\& }{enc}}
+
+Sets the enconding of the document.
+
+\membersection{wxXmlDocument::SetFileEncoding}\label{wxxmldocumentsetfileencoding}
+
+\func{void}{SetFileEncoding}{\param{const wxString\& }{encoding}}
+
+Sets the enconding of the file which will be used to save the document.
+
+\membersection{wxXmlDocument::SetRoot}\label{wxxmldocumentsetroot}
+
+\func{void}{SetRoot}{\param{wxXmlNode* }{node}}
+
+Sets the root node of this document. Deletes previous root node.
+
+\membersection{wxXmlDocument::SetVersion}\label{wxxmldocumentsetversion}
+
+\func{void}{SetVersion}{\param{const wxString\& }{version}}
+
+Sets the version of the XML file which will be used to save the document.
+
+\membersection{wxXmlDocument::operator=}\label{wxxmldocumentoperatorassign}
+
+\func{wxXmlDocument\& operator}{operator=}{\param{const wxXmlDocument\& }{doc}}
+
+Copies the given document.
+

docs/latex/wx/xmlnode.tex

@@ -0,0 +1,242 @@
+\section{\class{wxXmlNode}}\label{wxxmlnode}
+
+Represents a node in an XML document. See \helpref{wxXmlDocument}{wxxmldocument}.
+
+Node has a name and may have content
+and properties. Most common node types are {\tt wxXML\_TEXT\_NODE} (name and
+properties are irrelevant) and {\tt wxXML\_ELEMENT\_NODE} (e.g. in {\tt <title>hi</title>} there is
+an element with name="title", irrelevant content and one child ({\tt wxXML\_TEXT\_NODE}
+with content="hi").
+
+If wxUSE\_UNICODE is 0, all strings are encoded in the encoding given to Load
+(default is UTF-8).
+
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/xml/xml.h>
+
+\wxheading{Constants}
+
+The following are the node types supported by wxXmlNode:
+
+{\small
+\begin{verbatim}
+enum wxXmlNodeType
+{
+    wxXML_ELEMENT_NODE,
+    wxXML_ATTRIBUTE_NODE,
+    wxXML_TEXT_NODE,
+    wxXML_CDATA_SECTION_NODE,
+    wxXML_ENTITY_REF_NODE,
+    wxXML_ENTITY_NODE,
+    wxXML_PI_NODE,
+    wxXML_COMMENT_NODE,
+    wxXML_DOCUMENT_NODE,
+    wxXML_DOCUMENT_TYPE_NODE,
+    wxXML_DOCUMENT_FRAG_NODE,
+    wxXML_NOTATION_NODE,
+    wxXML_HTML_DOCUMENT_NODE
+}
+\end{verbatim}
+}
+
+\wxheading{See also}
+
+\helpref{wxXmlDocument}{wxxmldocument}, \helpref{wxXmlProperty}{wxxmlproperty}
+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxXmlNode::wxXmlNode}\label{wxxmlnodewxxmlnode}
+
+
+\func{}{wxXmlNode}{\param{wxXmlNode* }{parent}, \param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}, \param{wxXmlProperty* }{props = NULL}, \param{wxXmlNode* }{next = NULL}}
+
+\wxheading{Parameters}
+
+\docparam{parent}{The parent node. Can be NULL.}
+\docparam{type}{One of the wxXmlNodeType enumeration value.}
+\docparam{name}{The name of the node. This is the string which appears between angular brackets.}
+\docparam{content}{The content of the node. Only meaningful when {\it type} is {\tt wxXML\_TEXT\_NODE} or {\tt wxXML\_CDATA\_SECTION\_NODE}.}
+\docparam{props}{If not NULL, this wxXmlProperty object and its eventual siblings are attached to
+the node.}
+\docparam{next}{If not NULL, this node and its eventual siblings are attached to
+the node.}
+
+\func{}{wxXmlNode}{\param{const wxXmlNode\& }{node}}
+
+Copy constructor. Note that this does NOT copy syblings
+and parent pointer, i.e. \helpref{GetParent()}{wxxmlnodegetparent} and \helpref{GetNext()}{wxxmlnodegetnext} will return NULL
+after using copy ctor and are never unmodified by operator=.
+
+On the other hand, it DOES copy children and properties.
+
+
+\func{}{wxXmlNode}{\param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}}
+
+A simplified version of the first constructor form.
+
+
+\membersection{wxXmlNode::\destruct{wxXmlNode}}\label{wxxmlnodedtor}
+
+\func{}{\destruct{wxXmlNode}}{\void}
+
+The virtual destructor. Deletes attached children and properties.
+
+\membersection{wxXmlNode::AddChild}\label{wxxmlnodeaddchild}
+
+\func{void}{AddChild}{\param{wxXmlNode* }{child}}
+
+Adds the given node as child of this node. To attach a second children to this node, use the
+\helpref{SetNext()}{wxxmlnodesetnext} function of the {\it child} node.
+
+\membersection{wxXmlNode::AddProperty}\label{wxxmlnodeaddproperty}
+
+\func{void}{AddProperty}{\param{const wxString\& }{name}, \param{const wxString\& }{value}}
+
+Appends a property with given {\it name} and {\it value} to the list of properties for this node.
+
+\func{void}{AddProperty}{\param{wxXmlProperty* }{prop}}
+
+Appends the given property to the list of properties for this node.
+
+\membersection{wxXmlNode::DeleteProperty}\label{wxxmlnodedeleteproperty}
+
+\func{bool}{DeleteProperty}{\param{const wxString\& }{name}}
+
+Removes the first properties which has the given {\it name} from the list of properties for this node.
+
+\membersection{wxXmlNode::GetChildren}\label{wxxmlnodegetchildren}
+
+\constfunc{wxXmlNode*}{GetChildren}{\void}
+
+Returns the first child of this node.
+To get a pointer to the second child of this node (if it does exist), use the
+\helpref{GetNext()}{wxxmlnodegetnext} function on the returned value.
+
+\membersection{wxXmlNode::GetContent}\label{wxxmlnodegetcontent}
+
+\constfunc{wxString}{GetContent}{\void}
+
+Returns the content of this node. Can be an empty string.
+
+\membersection{wxXmlNode::GetName}\label{wxxmlnodegetname}
+
+\constfunc{wxString}{GetName}{\void}
+
+Returns the name of this node. Can be an empty string (e.g. for nodes of type {\tt wxXML\_TEXT\_NODE} or {\tt wxXML\_CDATA\_SECTION\_NODE}).
+
+\membersection{wxXmlNode::GetNext}\label{wxxmlnodegetnext}
+
+\constfunc{wxXmlNode*}{GetNext}{\void}
+
+Returns a pointer to the sibling of this node or NULL if there are no siblings.
+
+\membersection{wxXmlNode::GetParent}\label{wxxmlnodegetparent}
+
+\constfunc{wxXmlNode*}{GetParent}{\void}
+
+Returns a pointer to the parent of this node or NULL if this node has no parent.
+
+\membersection{wxXmlNode::GetPropVal}\label{wxxmlnodegetpropval}
+
+\constfunc{bool}{GetPropVal}{\param{const wxString\& }{propName}, \param{wxString* }{value}}
+
+Returns \true if a property named {\it propName} could be found.
+If the {\it value} pointer is not NULL, the value of that property is saved there.
+
+\constfunc{wxString}{GetPropVal}{\param{const wxString\& }{propName}, \param{const wxString\& }{defaultVal}}
+
+Returns the value of the property named {\it propName} if it does exist.
+If it does not exist, the {\it defaultVal} is returned.
+
+\membersection{wxXmlNode::GetProperties}\label{wxxmlnodegetproperties}
+
+\constfunc{wxXmlProperty*}{GetProperties}{\void}
+
+Return a pointer to the first property of this node.
+
+\membersection{wxXmlNode::GetType}\label{wxxmlnodegettype}
+
+\constfunc{wxXmlNodeType}{GetType}{\void}
+
+Returns the type of this node.
+
+
+\membersection{wxXmlNode::HasProp}\label{wxxmlnodehasprop}
+
+\constfunc{bool}{HasProp}{\param{const wxString\& }{propName}}
+
+Returns \true if this node has a property named {\it propName}.
+
+\membersection{wxXmlNode::InsertChild}\label{wxxmlnodeinsertchild}
+
+\func{void}{InsertChild}{\param{wxXmlNode* }{child}, \param{wxXmlNode* }{before\_node}}
+
+Inserts the {\it child} node after {\it before\_node} in the children list.
+
+\membersection{wxXmlNode::RemoveChild}\label{wxxmlnoderemovechild}
+
+\func{bool}{RemoveChild}{\param{wxXmlNode* }{child}}
+
+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.
+
+\membersection{wxXmlNode::SetChildren}\label{wxxmlnodesetchildren}
+
+\func{void}{SetChildren}{\param{wxXmlNode* }{child}}
+
+Sets as first child the given node. The caller is responsible to delete any previously present
+children node.
+
+\membersection{wxXmlNode::SetContent}\label{wxxmlnodesetcontent}
+
+\func{void}{SetContent}{\param{const wxString\& }{con}}
+
+Sets the content of this node.
+
+\membersection{wxXmlNode::SetName}\label{wxxmlnodesetname}
+
+\func{void}{SetName}{\param{const wxString\& }{name}}
+
+Sets the name of this node.
+
+\membersection{wxXmlNode::SetNext}\label{wxxmlnodesetnext}
+
+\func{void}{SetNext}{\param{wxXmlNode* }{next}}
+
+Sets as sibling the given node. The caller is responsible to delete any previously present
+sibling node.
+
+\membersection{wxXmlNode::SetParent}\label{wxxmlnodesetparent}
+
+\func{void}{SetParent}{\param{wxXmlNode* }{parent}}
+
+Sets as parent the given node. The caller is responsible to delete any previously present
+parent node.
+
+\membersection{wxXmlNode::SetProperties}\label{wxxmlnodesetproperties}
+
+\func{void}{SetProperties}{\param{wxXmlProperty* }{prop}}
+
+Sets as first property the given wxXmlProperty object.
+The caller is responsible to delete any previously present properties attached to this node.
+
+\membersection{wxXmlNode::SetType}\label{wxxmlnodesettype}
+
+\func{void}{SetType}{\param{wxXmlNodeType }{type}}
+
+Sets the type of this node.
+
+\membersection{wxXmlNode::operator=}\label{wxxmlnodeoperatorassign}
+
+\func{wxXmlNode\& operator}{operator=}{\param{const wxXmlNode\& }{node}}
+
+See the copy constructor for more info.
+

docs/latex/wx/xmlproperty.tex

@@ -0,0 +1,74 @@
+\section{\class{wxXmlProperty}}\label{wxxmlproperty}
+
+Represents a node property.
+
+Example: in <img src="hello.gif" id="3"/> "src" is property with value
+"hello.gif" and "id" is a property with value "3".
+
+\wxheading{Derived from}
+
+No base class
+
+\wxheading{Include files}
+
+<wx/xml/xml.h>
+
+\wxheading{See also}
+
+\helpref{wxXmlDocument}{wxxmldocument}, \helpref{wxXmlNode}{wxxmlnode}
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+
+\membersection{wxXmlProperty::wxXmlProperty}\label{wxxmlpropertywxxmlproperty}
+
+\func{}{wxXmlProperty}{\void}
+
+
+\func{}{wxXmlProperty}{\param{const wxString\& }{name}, \param{const wxString\& }{value}, \param{wxXmlProperty* }{next = NULL}}
+
+Creates the property with given {\it name} and {\it value}.
+If {\it next} is not NULL, then sets it as sibling of this property.
+
+\membersection{wxXmlProperty::\destruct{wxXmlProperty}}\label{wxxmlpropertydtor}
+
+\func{}{\destruct{wxXmlProperty}}{\void}
+
+The virtual destructor.
+
+\membersection{wxXmlProperty::GetName}\label{wxxmlpropertygetname}
+
+\constfunc{wxString}{GetName}{\void}
+
+Returns the name of this property.
+
+\membersection{wxXmlProperty::GetNext}\label{wxxmlpropertygetnext}
+
+\constfunc{wxXmlProperty*}{GetNext}{\void}
+
+Returns the sibling of this property or NULL if there are no siblings.
+
+\membersection{wxXmlProperty::GetValue}\label{wxxmlpropertygetvalue}
+
+\constfunc{wxString}{GetValue}{\void}
+
+Returns the value of this property.
+
+\membersection{wxXmlProperty::SetName}\label{wxxmlpropertysetname}
+
+\func{void}{SetName}{\param{const wxString\& }{name}}
+
+Sets the name of this property.
+
+\membersection{wxXmlProperty::SetNext}\label{wxxmlpropertysetnext}
+
+\func{void}{SetNext}{\param{wxXmlProperty* }{next}}
+
+Sets the sibling of this property.
+
+\membersection{wxXmlProperty::SetValue}\label{wxxmlpropertysetvalue}
+
+\func{void}{SetValue}{\param{const wxString\& }{value}}
+
+Sets the value of this property.
+

include/wx/xml/xml.h

@@ -9,16 +9,6 @@
 /////////////////////////////////////////////////////////////////////////////
 
 
-/* ************************************************************************* *
- *                                CAUTION!                                   *
- *                                                                           *
- *  The API defined in this header *WILL* change in the future and backward  *
- *  compatibility will *not* be preserved. If you use these classes in your  *
- *  application, it probably won't compile with future wxWidgets releases.   *
- *  Use on your own risk.                                                    *
- *                                                                           *
- * ************************************************************************* */
-
 #ifndef _WX_XML_H_
 #define _WX_XML_H_
 
@@ -75,8 +65,9 @@ class WXDLLIMPEXP_XML wxXmlProperty
 public:
     wxXmlProperty() : m_next(NULL) {}
     wxXmlProperty(const wxString& name, const wxString& value,
-                  wxXmlProperty *next)
+                  wxXmlProperty *next = NULL)
             : m_name(name), m_value(value), m_next(next) {}
+    virtual ~wxXmlProperty() {}
 
     wxString GetName() const { return m_name; }
     wxString GetValue() const { return m_value; }
@@ -109,9 +100,9 @@ public:
     wxXmlNode() : m_properties(NULL), m_parent(NULL),
                   m_children(NULL), m_next(NULL) {}
     wxXmlNode(wxXmlNode *parent, wxXmlNodeType type,
-              const wxString& name, const wxString& content,
+              const wxString& name, const wxString& content = wxEmptyString,
-              wxXmlProperty *props, wxXmlNode *next);
+              wxXmlProperty *props = NULL, wxXmlNode *next = NULL);
-    ~wxXmlNode();
+    virtual ~wxXmlNode();
 
     // copy ctor & operator=. Note that this does NOT copy syblings
     // and parent pointer, i.e. m_parent and m_next will be NULL
@@ -123,17 +114,24 @@ public:
     // user-friendly creation:
     wxXmlNode(wxXmlNodeType type, const wxString& name,
               const wxString& content = wxEmptyString);
-    void AddChild(wxXmlNode *child);
+    virtual void AddChild(wxXmlNode *child);
-    void InsertChild(wxXmlNode *child, wxXmlNode *before_node);
+    virtual void InsertChild(wxXmlNode *child, wxXmlNode *before_node);
-    bool RemoveChild(wxXmlNode *child);
+    virtual bool RemoveChild(wxXmlNode *child);
-    void AddProperty(const wxString& name, const wxString& value);
+    virtual void AddProperty(const wxString& name, const wxString& value);
-    bool DeleteProperty(const wxString& name);
+    virtual bool DeleteProperty(const wxString& name);
 
     // access methods:
     wxXmlNodeType GetType() const { return m_type; }
     wxString GetName() const { return m_name; }
     wxString GetContent() const { return m_content; }
 
+    // Gets node content from wxXML_ENTITY_NODE
+    // The problem is, <tag>content<tag> is represented as
+    // wxXML_ENTITY_NODE name="tag", content=""
+    //    |-- wxXML_TEXT_NODE or
+    //        wxXML_CDATA_SECTION_NODE name="" content="content"
+    wxString GetNodeContent() const;
+
     wxXmlNode *GetParent() const { return m_parent; }
     wxXmlNode *GetNext() const { return m_next; }
     wxXmlNode *GetChildren() const { return m_children; }
@@ -153,7 +151,7 @@ public:
     void SetChildren(wxXmlNode *child) { m_children = child; }
 
     void SetProperties(wxXmlProperty *prop) { m_properties = prop; }
-    void AddProperty(wxXmlProperty *prop);
+    virtual void AddProperty(wxXmlProperty *prop);
 
 private:
     wxXmlNodeType m_type;
@@ -181,21 +179,21 @@ public:
                   const wxString& encoding = wxT("UTF-8"));
     wxXmlDocument(wxInputStream& stream,
                   const wxString& encoding = wxT("UTF-8"));
-    ~wxXmlDocument() { delete m_root; }
+    virtual ~wxXmlDocument() { wxDELETE(m_root); }
 
     wxXmlDocument(const wxXmlDocument& doc);
     wxXmlDocument& operator=(const wxXmlDocument& doc);
 
     // Parses .xml file and loads data. Returns TRUE on success, FALSE
     // otherwise.
-    bool Load(const wxString& filename,
+    virtual bool Load(const wxString& filename,
               const wxString& encoding = wxT("UTF-8"));
-    bool Load(wxInputStream& stream,
+    virtual bool Load(wxInputStream& stream,
               const wxString& encoding = wxT("UTF-8"));
     
     // Saves document as .xml file.
-    bool Save(const wxString& filename) const;
+    virtual bool Save(const wxString& filename) const;
-    bool Save(wxOutputStream& stream) const;
+    virtual bool Save(wxOutputStream& stream) const;
 
     bool IsOk() const { return m_root != NULL; }
 
@@ -210,7 +208,7 @@ public:
     wxString GetFileEncoding() const { return m_fileEncoding; }
 
     // Write-access methods:
-    void SetRoot(wxXmlNode *node) { delete m_root ; m_root = node; }
+    void SetRoot(wxXmlNode *node) { wxDELETE(m_root); m_root = node; }
     void SetVersion(const wxString& version) { m_version = version; }
     void SetFileEncoding(const wxString& encoding) { m_fileEncoding = encoding; }
 
@@ -231,6 +229,8 @@ private:
     wxXmlNode *m_root;
 
     void DoCopy(const wxXmlDocument& doc);
+
+    DECLARE_CLASS(wxXmlDocument)
 };
 
 #endif // wxUSE_XML

src/xml/xml.cpp

@@ -32,6 +32,11 @@
 #include "wx/app.h"
 WX_CHECK_BUILD_OPTIONS("wxXML")
 
+
+IMPLEMENT_CLASS(wxXmlDocument, wxObject)
+
+
+
 //-----------------------------------------------------------------------------
 //  wxXmlNode
 //-----------------------------------------------------------------------------
@@ -268,6 +273,20 @@ bool wxXmlNode::DeleteProperty(const wxString& name)
     }
 }
 
+wxString wxXmlNode::GetNodeContent() const
+{
+    wxXmlNode *n = GetChildren();
+
+    while (n)
+    {
+        if (n->GetType() == wxXML_TEXT_NODE ||
+            n->GetType() == wxXML_CDATA_SECTION_NODE)
+            return n->GetContent();
+        n = n->GetNext();
+    }
+    return wxEmptyString;
+}
+
 
 
 //-----------------------------------------------------------------------------