docs/latex/wx/xmldocument.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        xmlnode.tex
   3 %% Purpose:     wxXmlDocument documentation
   4 %% Author:      Francesco Montorsi
   5 %% Created:     2006-04-18
   6 %% RCS-ID:      $Id$
   7 %% Copyright:   (c) 2006 Francesco Montorsi
   8 %% License:     wxWindows license
   9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  10
  11 \section{\class{wxXmlDocument}}\label{wxxmldocument}
  12
  13 This class holds XML data/document as parsed by XML parser in the root node.
  14
  15 wxXmlDocument internally uses the expat library which comes with wxWidgets to parse the given stream.
  16
  17 A simple example of using XML classes is:
  18
  19 \begin{verbatim}
  20 wxXmlDocument doc;
  21 if (!doc.Load(wxT("myfile.xml")))
  22     return false;
  23
  24 // start processing the XML file
  25 if (doc.GetRoot()->GetName() != wxT("myroot-node"))
  26     return false;
  27
  28 wxXmlNode *child = doc.GetRoot()->GetChildren();
  29 while (child) {
  30
  31     if (child->GetName() == wxT("tag1")) {
  32
  33         // process text enclosed by <tag1></tag1>
  34         wxString content = child->GetNodeContent();
  35
  36         ...
  37
  38
  39         // process properties of <tag1>
  40         wxString propvalue1 = child->GetPropVal(wxT("prop1"), wxT("default-value"));
  41         wxString propvalue2 = child->GetPropVal(wxT("prop2"), wxT("default-value"));
  42
  43         ...
  44
  45     } else if (child->GetName() == wxT("tag2")) {
  46
  47         // process tag2 ...
  48     }
  49
  50     child = child->GetNext();
  51 }
  52 \end{verbatim}
  53
  54 {\bf Note:} if you want to preserve the original formatting of the loaded file including whitespaces
  55 and indentation, you need to turn off whitespace-only textnode removal and automatic indentation:
  56
  57 \begin{verbatim}
  58 wxXmlDocument doc;
  59 doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES);
  60 doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION);       // myfile2.xml will be indentic to myfile.xml
  61 \end{verbatim}
  62
  63 Using default parameters, you will get a reformatted document which in general is different from
  64 the original loaded content:
  65
  66 \begin{verbatim}
  67 wxXmlDocument doc;
  68 doc.Load(wxT("myfile.xml"));
  69 doc.Save(wxT("myfile2.xml"));       // myfile2.xml != myfile.xml
  70 \end{verbatim}
  71
  72
  73 \wxheading{Derived from}
  74
  75 \helpref{wxObject}{wxobject}
  76
  77 \wxheading{Include files}
  78
  79 <wx/xml/xml.h>
  80
  81 \wxheading{See also}
  82
  83 \helpref{wxXmlNode}{wxxmlnode}, \helpref{wxXmlProperty}{wxxmlproperty}
  84
  85
  86 \latexignore{\rtfignore{\wxheading{Members}}}
  87
  88
  89
  90 \membersection{wxXmlDocument::wxXmlDocument}\label{wxxmldocumentwxxmldocument}
  91
  92 \func{}{wxXmlDocument}{\void}
  93
  94
  95 \func{}{wxXmlDocument}{\param{const wxString\& }{filename}, \param{const wxString\& }{encoding = wxT("UTF-8")}, \param{int }{flags = wxXMLDOC\_NONE}}
  96
  97 Loads the given {\it filename} using the given encoding. See \helpref{Load()}{wxxmldocumentload}.
  98
  99 \func{}{wxXmlDocument}{\param{wxInputStream\& }{stream}, \param{const wxString\& }{encoding = wxT("UTF-8")}, \param{int }{flags = wxXMLDOC\_NONE}}
 100
 101 Loads the XML document from given stream using the given encoding. See \helpref{Load()}{wxxmldocumentload}.
 102
 103 \func{}{wxXmlDocument}{\param{const wxXmlDocument\& }{doc}}
 104
 105 Copy constructor.
 106
 107
 108 \membersection{wxXmlDocument::\destruct{wxXmlDocument}}\label{wxxmldocumentdtor}
 109
 110 \func{}{\destruct{wxXmlDocument}}{\void}
 111
 112 Virtual destructor. Frees the document root node.
 113
 114
 115
 116 \membersection{wxXmlDocument::DetachRoot}\label{wxxmldocumentdetachroot}
 117
 118 \func{wxXmlNode*}{DetachRoot}{\void}
 119
 120 Detaches the document root node and returns it. The document root node will be set to \NULL
 121 and thus \helpref{IsOk}{wxxmldocumentisok} will return \false after calling this function.
 122
 123 Note that the caller is reponsible for deleting the returned node in order to avoid memory leaks.
 124
 125
 126
 127 \membersection{wxXmlDocument::GetEncoding}\label{wxxmldocumentgetencoding}
 128
 129 \constfunc{wxString}{GetEncoding}{\void}
 130
 131 Returns encoding of in-memory representation of the document
 132 (same as passed to \helpref{Load()}{wxxmldocumentload} or constructor, defaults to UTF-8).
 133
 134 NB: this is meaningless in Unicode build where data are stored as wchar\_t*.
 135
 136
 137
 138 \membersection{wxXmlDocument::GetFileEncoding}\label{wxxmldocumentgetfileencoding}
 139
 140 \constfunc{wxString}{GetFileEncoding}{\void}
 141
 142 Returns encoding of document (may be empty).
 143
 144 Note: this is the encoding original file was saved in, *not* the
 145 encoding of in-memory representation!
 146
 147
 148
 149 \membersection{wxXmlDocument::GetRoot}\label{wxxmldocumentgetroot}
 150
 151 \constfunc{wxXmlNode*}{GetRoot}{\void}
 152
 153 Returns the root node of the document.
 154
 155
 156
 157 \membersection{wxXmlDocument::GetVersion}\label{wxxmldocumentgetversion}
 158
 159 \constfunc{wxString}{GetVersion}{\void}
 160
 161 Returns the version of document.
 162 This is the value in the {\tt <?xml version="1.0"?>} header of the XML document.
 163 If the version property was not explicitely given in the header, this function
 164 returns an empty string.
 165
 166
 167
 168 \membersection{wxXmlDocument::IsOk}\label{wxxmldocumentisok}
 169
 170 \constfunc{bool}{IsOk}{\void}
 171
 172 Returns \true if the document has been loaded successfully.
 173
 174
 175
 176 \membersection{wxXmlDocument::Load}\label{wxxmldocumentload}
 177
 178 \func{bool}{Load}{\param{const wxString\& }{filename}, \param{const wxString\& }{encoding = wxT("UTF-8")}, \param{int }{flags = wxXMLDOC\_NONE}}
 179
 180 Parses {\it filename} as an xml document and loads its data.
 181
 182 If {\tt flags} does not contain {\tt wxXMLDOC\_KEEP\_WHITESPACE\_NODES}, then, while loading, all nodes of
 183 type {\tt wxXML\_TEXT\_NODE} (see \helpref{wxXmlNode}{wxxmlnode}) are automatically skipped if they
 184 contain whitespaces only.
 185 The removal of these nodes makes the load process slightly faster and requires less memory however
 186 makes impossible to recreate exactly the loaded text with a \helpref{Save}{wxxmldocumentsave} call later.
 187 Read the initial description of this class for more info.
 188
 189 Returns \true on success, \false otherwise.
 190
 191 \func{bool}{Load}{\param{wxInputStream\& }{stream}, \param{const wxString\& }{encoding = wxT("UTF-8")}, \param{int }{flags = wxXMLDOC\_NONE}}
 192
 193 Like above but takes the data from given input stream.
 194
 195
 196 \membersection{wxXmlDocument::Save}\label{wxxmldocumentsave}
 197
 198 \constfunc{bool}{Save}{\param{const wxString\& }{filename}, \param{int }{indentstep = 1}}
 199
 200 Saves XML tree creating a file named with given string.
 201
 202 If {\tt indentstep} is greater than or equal to zero, then, while saving, an automatic indentation
 203 is added with steps composed by {\tt indentstep} spaces.
 204 If {\tt indentstep} is {\tt wxXML\_NO\_INDENTATION}, then, automatic indentation is turned off.
 205
 206 \constfunc{bool}{Save}{\param{wxOutputStream\& }{stream}, \param{int }{indentstep = 1}}
 207
 208 Saves XML tree in the given output stream. See other overload for a description of {\tt indentstep}.
 209
 210
 211 \membersection{wxXmlDocument::SetEncoding}\label{wxxmldocumentsetencoding}
 212
 213 \func{void}{SetEncoding}{\param{const wxString\& }{enc}}
 214
 215 Sets the enconding of the document.
 216
 217
 218 \membersection{wxXmlDocument::SetFileEncoding}\label{wxxmldocumentsetfileencoding}
 219
 220 \func{void}{SetFileEncoding}{\param{const wxString\& }{encoding}}
 221
 222 Sets the enconding of the file which will be used to save the document.
 223
 224
 225 \membersection{wxXmlDocument::SetRoot}\label{wxxmldocumentsetroot}
 226
 227 \func{void}{SetRoot}{\param{wxXmlNode* }{node}}
 228
 229 Sets the root node of this document. Deletes previous root node.
 230 Use \helpref{DetachRoot}{wxxmldocumentdetachroot} and then SetRoot if you want
 231 to replace the root node without deleting the old document tree.
 232
 233
 234 \membersection{wxXmlDocument::SetVersion}\label{wxxmldocumentsetversion}
 235
 236 \func{void}{SetVersion}{\param{const wxString\& }{version}}
 237
 238 Sets the version of the XML file which will be used to save the document.
 239
 240
 241 \membersection{wxXmlDocument::operator=}\label{wxxmldocumentoperatorassign}
 242
 243 \func{wxXmlDocument\& operator}{operator=}{\param{const wxXmlDocument\& }{doc}}
 244
 245 Copies the given document.
 246