X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4c43dd9078b2f9f8bb280020a878932272d0163e..9c57566224918b8a121d1011aa7baa5b28b334a6:/docs/latex/wx/xmldocument.tex

diff --git a/docs/latex/wx/xmldocument.tex b/docs/latex/wx/xmldocument.tex
index 2428958038..d73740818b 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 <tag1></tag1>
+        wxString content = child->GetNodeContent();
+
+        ...
+
+
+        // process properties of <tag1>
+        wxString propvalue1 = 
+            child->GetPropVal(wxT("prop1"), 
+                              wxT("default-value"));
+        wxString propvalue2 = 
+            child->GetPropVal(wxT("prop2"), 
+                              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}
@@ -20,22 +92,24 @@ wxXmlDocument internally uses the expat library which comes with wxWidgets to pa
 \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,6 +159,7 @@ encoding of in-memory representation!
 Returns the root node of the document.
 
 
+
 \membersection{wxXmlDocument::GetVersion}\label{wxxmldocumentgetversion}
 
 \constfunc{wxString}{GetVersion}{\void}
@@ -80,6 +170,7 @@ 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}
@@ -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.