From: Julian Smart Date: Sat, 11 Mar 2006 13:43:58 +0000 (+0000) Subject: Applied patch [ 1432449 ] wxXml API documentation X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/4c43dd9078b2f9f8bb280020a878932272d0163e Applied patch [ 1432449 ] wxXml API documentation git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@37994 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/docs/latex/wx/classes.tex b/docs/latex/wx/classes.tex index 54f94379d5..f4ff2a8a63 100644 --- a/docs/latex/wx/classes.tex +++ b/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 diff --git a/docs/latex/wx/xmldocument.tex b/docs/latex/wx/xmldocument.tex new file mode 100644 index 0000000000..2428958038 --- /dev/null +++ b/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} + + + +\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 } 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. + diff --git a/docs/latex/wx/xmlnode.tex b/docs/latex/wx/xmlnode.tex new file mode 100644 index 0000000000..19c62b2423 --- /dev/null +++ b/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 hi} 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} + + + +\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. + diff --git a/docs/latex/wx/xmlproperty.tex b/docs/latex/wx/xmlproperty.tex new file mode 100644 index 0000000000..936759be1b --- /dev/null +++ b/docs/latex/wx/xmlproperty.tex @@ -0,0 +1,74 @@ +\section{\class{wxXmlProperty}}\label{wxxmlproperty} + +Represents a node property. + +Example: in "src" is property with value +"hello.gif" and "id" is a property with value "3". + +\wxheading{Derived from} + +No base class + +\wxheading{Include files} + + + +\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. + diff --git a/include/wx/xml/xml.h b/include/wx/xml/xml.h index 175b51c883..83bedabb5f 100644 --- a/include/wx/xml/xml.h +++ b/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; } @@ -108,10 +99,10 @@ class WXDLLIMPEXP_XML wxXmlNode 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, - wxXmlProperty *props, wxXmlNode *next); - ~wxXmlNode(); + wxXmlNode(wxXmlNode *parent, wxXmlNodeType type, + const wxString& name, const wxString& content = wxEmptyString, + wxXmlProperty *props = NULL, wxXmlNode *next = NULL); + 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); - void InsertChild(wxXmlNode *child, wxXmlNode *before_node); - bool RemoveChild(wxXmlNode *child); - void AddProperty(const wxString& name, const wxString& value); - bool DeleteProperty(const wxString& name); + virtual void AddChild(wxXmlNode *child); + virtual void InsertChild(wxXmlNode *child, wxXmlNode *before_node); + virtual bool RemoveChild(wxXmlNode *child); + virtual void AddProperty(const wxString& name, const wxString& value); + 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, content 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; - bool Save(wxOutputStream& stream) const; + virtual bool Save(const wxString& filename) 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 diff --git a/src/xml/xml.cpp b/src/xml/xml.cpp index c17c12e9c3..619f93ab51 100644 --- a/src/xml/xml.cpp +++ b/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; +} + //-----------------------------------------------------------------------------