docs/latex/wx/xmldocument.tex

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