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 \membersection{wxXmlDocument::GetEncoding}\label{wxxmldocumentgetencoding}
  96
  97 \constfunc{wxString}{GetEncoding}{\void}
  98
  99 Returns encoding of in-memory representation of the document
 100 (same as passed to \helpref{Load()}{wxxmldocumentload} or constructor, defaults to UTF-8).
 101
 102 NB: this is meaningless in Unicode build where data are stored as wchar\_t*.
 103
 104
 105 \membersection{wxXmlDocument::GetFileEncoding}\label{wxxmldocumentgetfileencoding}
 106
 107 \constfunc{wxString}{GetFileEncoding}{\void}
 108
 109 Returns encoding of document (may be empty).
 110
 111 Note: this is the encoding original file was saved in, *not* the
 112 encoding of in-memory representation!
 113
 114
 115 \membersection{wxXmlDocument::GetRoot}\label{wxxmldocumentgetroot}
 116
 117 \constfunc{wxXmlNode*}{GetRoot}{\void}
 118
 119 Returns the root node of the document.
 120
 121
 122 \membersection{wxXmlDocument::GetVersion}\label{wxxmldocumentgetversion}
 123
 124 \constfunc{wxString}{GetVersion}{\void}
 125
 126 Returns the version of document.
 127 This is the value in the {\tt <?xml version="1.0"?>} header of the XML document.
 128 If the version property was not explicitely given in the header, this function
 129 returns an empty string.
 130
 131
 132 \membersection{wxXmlDocument::IsOk}\label{wxxmldocumentisok}
 133
 134 \constfunc{bool}{IsOk}{\void}
 135
 136 Returns \true if the document has been loaded successfully.
 137
 138
 139 \membersection{wxXmlDocument::Load}\label{wxxmldocumentload}
 140
 141 \func{bool}{Load}{\param{const wxString\& }{filename}, \param{const wxString\& }{encoding = wxT("UTF-8")}}
 142
 143 Parses {\it filename} as an xml document and loads data. Returns \true on success, \false otherwise.
 144
 145 \func{bool}{Load}{\param{wxInputStream\& }{stream}, \param{const wxString\& }{encoding = wxT("UTF-8")}}
 146
 147 Like above but takes the data from given input stream.
 148
 149 \membersection{wxXmlDocument::Save}\label{wxxmldocumentsave}
 150
 151 \constfunc{bool}{Save}{\param{const wxString\& }{filename}}
 152
 153 Saves XML tree creating a file named with given string.
 154
 155 \constfunc{bool}{Save}{\param{wxOutputStream\& }{stream}}
 156
 157 Saves XML tree in the given output stream.
 158
 159 \membersection{wxXmlDocument::SetEncoding}\label{wxxmldocumentsetencoding}
 160
 161 \func{void}{SetEncoding}{\param{const wxString\& }{enc}}
 162
 163 Sets the enconding of the document.
 164
 165 \membersection{wxXmlDocument::SetFileEncoding}\label{wxxmldocumentsetfileencoding}
 166
 167 \func{void}{SetFileEncoding}{\param{const wxString\& }{encoding}}
 168
 169 Sets the enconding of the file which will be used to save the document.
 170
 171 \membersection{wxXmlDocument::SetRoot}\label{wxxmldocumentsetroot}
 172
 173 \func{void}{SetRoot}{\param{wxXmlNode* }{node}}
 174
 175 Sets the root node of this document. Deletes previous root node.
 176
 177 \membersection{wxXmlDocument::SetVersion}\label{wxxmldocumentsetversion}
 178
 179 \func{void}{SetVersion}{\param{const wxString\& }{version}}
 180
 181 Sets the version of the XML file which will be used to save the document.
 182
 183 \membersection{wxXmlDocument::operator=}\label{wxxmldocumentoperatorassign}
 184
 185 \func{wxXmlDocument\& operator}{operator=}{\param{const wxXmlDocument\& }{doc}}
 186
 187 Copies the given document.
 188