X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4c43dd9078b2f9f8bb280020a878932272d0163e..fc715b5088d317ad09cad84f0d9d375bfac055fd:/docs/latex/wx/xmldocument.tex diff --git a/docs/latex/wx/xmldocument.tex b/docs/latex/wx/xmldocument.tex index 2428958038..df0acfdceb 100644 --- a/docs/latex/wx/xmldocument.tex +++ b/docs/latex/wx/xmldocument.tex @@ -1,9 +1,81 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Name: xmlnode.tex +%% Purpose: wxXmlDocument documentation +%% Author: Francesco Montorsi +%% Created: 2006-04-18 +%% RCS-ID: $Id$ +%% Copyright: (c) 2006 Francesco Montorsi +%% License: wxWindows license +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \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. +A simple example of using XML classes is: + +\begin{verbatim} +wxXmlDocument doc; +if (!doc.Load(wxT("myfile.xml"))) + return false; + +// start processing the XML file +if (doc.GetRoot()->GetName() != wxT("myroot-node")) + return false; + +wxXmlNode *child = doc.GetRoot()->GetChildren(); +while (child) { + + if (child->GetName() == wxT("tag1")) { + + // process text enclosed by + wxString content = child->GetNodeContent(); + + ... + + + // process attributes of + wxString attrvalue1 = + child->GetAttribute(wxT("attr1"), + wxT("default-value")); + wxString attrvalue2 = + child->GetAttribute(wxT("attr2"), + wxT("default-value")); + + ... + + } else if (child->GetName() == wxT("tag2")) { + + // process tag2 ... + } + + child = child->GetNext(); +} +\end{verbatim} + +{\bf 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: + +\begin{verbatim} +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); +\end{verbatim} + +Using default parameters, you will get a reformatted document which in general is different from +the original loaded content: + +\begin{verbatim} +wxXmlDocument doc; +doc.Load(wxT("myfile.xml")); +doc.Save(wxT("myfile2.xml")); // myfile2.xml != myfile.xml +\end{verbatim} + + \wxheading{Derived from} \helpref{wxObject}{wxobject} @@ -14,28 +86,30 @@ wxXmlDocument internally uses the expat library which comes with wxWidgets to pa \wxheading{See also} -\helpref{wxXmlNode}{wxxmlnode}, \helpref{wxXmlProperty}{wxxmlproperty} +\helpref{wxXmlNode}{wxxmlnode}, \helpref{wxXmlAttribute}{wxxmlattribute} \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")}} +\func{}{wxXmlDocument}{\param{const wxString\& }{filename}, \param{const wxString\& }{encoding = wxT("UTF-8")}, \param{int }{flags = wxXMLDOC\_NONE}} -Loads the given {\it filename} using the given encoding. See \helpref{Load()}{wxxmldocumentload}. +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")}} +\func{}{wxXmlDocument}{\param{wxInputStream\& }{stream}, \param{const wxString\& }{encoding = wxT("UTF-8")}, \param{int }{flags = wxXMLDOC\_NONE}} -Loads the XML document from given stream using the given encoding. See \helpref{Load()}{wxxmldocumentload}. +Loads the XML document from given stream using the given encoding. See \helpref{Load}{wxxmldocumentload}. \func{}{wxXmlDocument}{\param{const wxXmlDocument\& }{doc}} -Copy constructor. +Copy constructor. Deep copies all the XML tree of the given document. + \membersection{wxXmlDocument::\destruct{wxXmlDocument}}\label{wxxmldocumentdtor} @@ -43,14 +117,28 @@ Copy constructor. Virtual destructor. Frees the document root node. + + +\membersection{wxXmlDocument::DetachRoot}\label{wxxmldocumentdetachroot} + +\func{wxXmlNode*}{DetachRoot}{\void} + +Detaches the document root node and returns it. The document root node will be set to \NULL +and thus \helpref{IsOk}{wxxmldocumentisok} will return \false after calling this function. + +Note that the caller is reponsible for deleting the returned node in order to avoid memory leaks. + + + \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). +(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 {\tt wchar\_t*}. -NB: this is meaningless in Unicode build where data are stored as wchar\_t*. \membersection{wxXmlDocument::GetFileEncoding}\label{wxxmldocumentgetfileencoding} @@ -59,10 +147,11 @@ NB: this is meaningless in Unicode build where data are stored as wchar\_t*. Returns encoding of document (may be empty). -Note: this is the encoding original file was saved in, *not* the +Note: this is the encoding original file was saved in, {\bf not} the encoding of in-memory representation! + \membersection{wxXmlDocument::GetRoot}\label{wxxmldocumentgetroot} \constfunc{wxXmlNode*}{GetRoot}{\void} @@ -70,16 +159,18 @@ encoding of in-memory representation! 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 +If the version attribute was not explicitely given in the header, this function returns an empty string. + \membersection{wxXmlDocument::IsOk}\label{wxxmldocumentisok} \constfunc{bool}{IsOk}{\void} @@ -87,25 +178,41 @@ returns an empty string. 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")}} +\func{bool}{Load}{\param{const wxString\& }{filename}, \param{const wxString\& }{encoding = wxT("UTF-8")}, \param{int }{flags = wxXMLDOC\_NONE}} + +Parses {\it filename} as an xml document and loads its data. -Parses {\it filename} as an xml document and loads data. Returns \true on success, \false otherwise. +If {\tt flags} does not contain {\tt wxXMLDOC\_KEEP\_WHITESPACE\_NODES}, then, while loading, all nodes of +type {\tt wxXML\_TEXT\_NODE} (see \helpref{wxXmlNode}{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 \helpref{Save}{wxxmldocumentsave} call later. +Read the initial description of this class for more info. -\func{bool}{Load}{\param{wxInputStream\& }{stream}, \param{const wxString\& }{encoding = wxT("UTF-8")}} +Returns \true on success, \false otherwise. + +\func{bool}{Load}{\param{wxInputStream\& }{stream}, \param{const wxString\& }{encoding = wxT("UTF-8")}, \param{int }{flags = wxXMLDOC\_NONE}} Like above but takes the data from given input stream. + \membersection{wxXmlDocument::Save}\label{wxxmldocumentsave} -\constfunc{bool}{Save}{\param{const wxString\& }{filename}} +\constfunc{bool}{Save}{\param{const wxString\& }{filename}, \param{int }{indentstep = 1}} Saves XML tree creating a file named with given string. -\constfunc{bool}{Save}{\param{wxOutputStream\& }{stream}} +If {\tt indentstep} is greater than or equal to zero, then, while saving, an automatic indentation +is added with steps composed by {\tt indentstep} spaces. +If {\tt indentstep} is {\tt wxXML\_NO\_INDENTATION}, then, automatic indentation is turned off. + +\constfunc{bool}{Save}{\param{wxOutputStream\& }{stream}, \param{int }{indentstep = 1}} + +Saves XML tree in the given output stream. See other overload for a description of {\tt indentstep}. -Saves XML tree in the given output stream. \membersection{wxXmlDocument::SetEncoding}\label{wxxmldocumentsetencoding} @@ -113,17 +220,23 @@ Saves XML tree in the given output stream. 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. +Use \helpref{DetachRoot}{wxxmldocumentdetachroot} and then +\helpref{SetRoot}{wxxmldocumentsetroot} if you want +to replace the root node without deleting the old document tree. + \membersection{wxXmlDocument::SetVersion}\label{wxxmldocumentsetversion} @@ -131,9 +244,10 @@ Sets the root node of this document. Deletes previous root node. 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. +Deep copies the given document.