| 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 | |