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