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
  55
  56 \wxheading{Derived from}
  57
  58 \helpref{wxObject}{wxobject}
  59
  60 \wxheading{Include files}
  61
  62 <wx/xml/xml.h>
  63
  64 \wxheading{See also}
  65
  66 \helpref{wxXmlNode}{wxxmlnode}, \helpref{wxXmlProperty}{wxxmlproperty}
  67
  68
  69 \latexignore{\rtfignore{\wxheading{Members}}}
  70
  71
  72 \membersection{wxXmlDocument::wxXmlDocument}\label{wxxmldocumentwxxmldocument}
  73
  74 \func{}{wxXmlDocument}{\void}
  75
  76
  77 \func{}{wxXmlDocument}{\param{const wxString\& }{filename}, \param{const wxString\& }{encoding = wxT("UTF-8")}}
  78
  79 Loads the given {\it filename} using the given encoding. See \helpref{Load()}{wxxmldocumentload}.
  80
  81 \func{}{wxXmlDocument}{\param{wxInputStream\& }{stream}, \param{const wxString\& }{encoding = wxT("UTF-8")}}
  82
  83 Loads the XML document from given stream using the given encoding. See \helpref{Load()}{wxxmldocumentload}.
  84
  85 \func{}{wxXmlDocument}{\param{const wxXmlDocument\& }{doc}}
  86
  87 Copy constructor.
  88
  89 \membersection{wxXmlDocument::\destruct{wxXmlDocument}}\label{wxxmldocumentdtor}
  90
  91 \func{}{\destruct{wxXmlDocument}}{\void}
  92
  93 Virtual destructor. Frees the document root node.
  94
  95
  96 \membersection{wxXmlDocument::DetachRoot}\label{wxxmldocumentdetachroot}
  97
  98 \func{wxXmlNode*}{DetachRoot}{\void}
  99
 100 Detaches the document root node and returns it. The document root node will be set to \NULL
 101 and thus \helpref{IsOk}{wxxmldocumentisok} will return \false after calling this function.
 102
 103 Note that the caller is reponsible for deleting the returned node in order to avoid memory leaks.
 104
 105
 106 \membersection{wxXmlDocument::GetEncoding}\label{wxxmldocumentgetencoding}
 107
 108 \constfunc{wxString}{GetEncoding}{\void}
 109
 110 Returns encoding of in-memory representation of the document
 111 (same as passed to \helpref{Load()}{wxxmldocumentload} or constructor, defaults to UTF-8).
 112
 113 NB: this is meaningless in Unicode build where data are stored as wchar\_t*.
 114
 115
 116 \membersection{wxXmlDocument::GetFileEncoding}\label{wxxmldocumentgetfileencoding}
 117
 118 \constfunc{wxString}{GetFileEncoding}{\void}
 119
 120 Returns encoding of document (may be empty).
 121
 122 Note: this is the encoding original file was saved in, *not* the
 123 encoding of in-memory representation!
 124
 125
 126 \membersection{wxXmlDocument::GetRoot}\label{wxxmldocumentgetroot}
 127
 128 \constfunc{wxXmlNode*}{GetRoot}{\void}
 129
 130 Returns the root node of the document.
 131
 132
 133 \membersection{wxXmlDocument::GetVersion}\label{wxxmldocumentgetversion}
 134
 135 \constfunc{wxString}{GetVersion}{\void}
 136
 137 Returns the version of document.
 138 This is the value in the {\tt <?xml version="1.0"?>} header of the XML document.
 139 If the version property was not explicitely given in the header, this function
 140 returns an empty string.
 141
 142
 143 \membersection{wxXmlDocument::IsOk}\label{wxxmldocumentisok}
 144
 145 \constfunc{bool}{IsOk}{\void}
 146
 147 Returns \true if the document has been loaded successfully.
 148
 149
 150 \membersection{wxXmlDocument::Load}\label{wxxmldocumentload}
 151
 152 \func{bool}{Load}{\param{const wxString\& }{filename}, \param{const wxString\& }{encoding = wxT("UTF-8")}}
 153
 154 Parses {\it filename} as an xml document and loads data. Returns \true on success, \false otherwise.
 155
 156 \func{bool}{Load}{\param{wxInputStream\& }{stream}, \param{const wxString\& }{encoding = wxT("UTF-8")}}
 157
 158 Like above but takes the data from given input stream.
 159
 160 \membersection{wxXmlDocument::Save}\label{wxxmldocumentsave}
 161
 162 \constfunc{bool}{Save}{\param{const wxString\& }{filename}}
 163
 164 Saves XML tree creating a file named with given string.
 165
 166 \constfunc{bool}{Save}{\param{wxOutputStream\& }{stream}}
 167
 168 Saves XML tree in the given output stream.
 169
 170 \membersection{wxXmlDocument::SetEncoding}\label{wxxmldocumentsetencoding}
 171
 172 \func{void}{SetEncoding}{\param{const wxString\& }{enc}}
 173
 174 Sets the enconding of the document.
 175
 176 \membersection{wxXmlDocument::SetFileEncoding}\label{wxxmldocumentsetfileencoding}
 177
 178 \func{void}{SetFileEncoding}{\param{const wxString\& }{encoding}}
 179
 180 Sets the enconding of the file which will be used to save the document.
 181
 182 \membersection{wxXmlDocument::SetRoot}\label{wxxmldocumentsetroot}
 183
 184 \func{void}{SetRoot}{\param{wxXmlNode* }{node}}
 185
 186 Sets the root node of this document. Deletes previous root node.
 187 Use \helpref{DetachRoot}{wxxmlnodedetachroot} and then SetRoot if you want to
 188 replace the root node without deleting the old document tree.
 189
 190 \membersection{wxXmlDocument::SetVersion}\label{wxxmldocumentsetversion}
 191
 192 \func{void}{SetVersion}{\param{const wxString\& }{version}}
 193
 194 Sets the version of the XML file which will be used to save the document.
 195
 196 \membersection{wxXmlDocument::operator=}\label{wxxmldocumentoperatorassign}
 197
 198 \func{wxXmlDocument\& operator}{operator=}{\param{const wxXmlDocument\& }{doc}}
 199
 200 Copies the given document.
 201