X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a124f99a24fb1f2ef41e37223ea35bcc9a4eece9..c266eff98c5e44012647f54f38a1e29ecabd8759:/docs/latex/wx/xmldocument.tex?ds=sidebyside diff --git a/docs/latex/wx/xmldocument.tex b/docs/latex/wx/xmldocument.tex index c99bdae67c..94574c9e0a 100644 --- a/docs/latex/wx/xmldocument.tex +++ b/docs/latex/wx/xmldocument.tex @@ -1,5 +1,5 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -%% Name: xmlnode.tex +%% Name: xmldocument.tex %% Purpose: wxXmlDocument documentation %% Author: Francesco Montorsi %% Created: 2006-04-18 @@ -18,7 +18,7 @@ A simple example of using XML classes is: \begin{verbatim} wxXmlDocument doc; -if (!doc.Load(wxT("myfile.xml")) +if (!doc.Load(wxT("myfile.xml"))) return false; // start processing the XML file @@ -36,9 +36,13 @@ while (child) { ... - // process properties of - wxString propvalue1 = child->GetPropVal(wxT("prop1"), wxT("default-value")); - wxString propvalue2 = child->GetPropVal(wxT("prop2"), wxT("default-value")); + // process attributes of + wxString attrvalue1 = + child->GetAttribute(wxT("attr1"), + wxT("default-value")); + wxString attrvalue2 = + child->GetAttribute(wxT("attr2"), + wxT("default-value")); ... @@ -51,6 +55,25 @@ while (child) { } \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} @@ -61,30 +84,36 @@ while (child) { +\wxheading{Library} + +\helpref{wxXml}{librarieslist} + \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} @@ -93,6 +122,7 @@ Copy constructor. Virtual destructor. Frees the document root node. + \membersection{wxXmlDocument::DetachRoot}\label{wxxmldocumentdetachroot} \func{wxXmlNode*}{DetachRoot}{\void} @@ -103,14 +133,16 @@ and thus \helpref{IsOk}{wxxmldocumentisok} will return \false after calling this 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} @@ -119,10 +151,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} @@ -130,16 +163,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} @@ -147,25 +182,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. + +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. -Parses {\it filename} as an xml document and loads data. Returns \true on success, \false otherwise. +Returns \true on success, \false otherwise. -\func{bool}{Load}{\param{wxInputStream\& }{stream}, \param{const wxString\& }{encoding = wxT("UTF-8")}} +\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} @@ -173,19 +224,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}{wxxmlnodedetachroot} and then SetRoot if you want to -replace the root node without deleting the old document tree. +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} @@ -193,9 +248,10 @@ replace the root node without deleting the old document tree. 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.