]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: xml/xml.h | |
f41d6c8c | 3 | // Purpose: interface of wxXmlNode, wxXmlAttribute, wxXmlDocument |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows license | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
f41d6c8c FM |
9 | |
10 | /// Represents XML node type. | |
11 | enum wxXmlNodeType | |
12 | { | |
13 | // note: values are synchronized with xmlElementType from libxml | |
14 | wxXML_ELEMENT_NODE = 1, | |
15 | wxXML_ATTRIBUTE_NODE = 2, | |
16 | wxXML_TEXT_NODE = 3, | |
17 | wxXML_CDATA_SECTION_NODE = 4, | |
18 | wxXML_ENTITY_REF_NODE = 5, | |
19 | wxXML_ENTITY_NODE = 6, | |
20 | wxXML_PI_NODE = 7, | |
21 | wxXML_COMMENT_NODE = 8, | |
22 | wxXML_DOCUMENT_NODE = 9, | |
23 | wxXML_DOCUMENT_TYPE_NODE = 10, | |
24 | wxXML_DOCUMENT_FRAG_NODE = 11, | |
25 | wxXML_NOTATION_NODE = 12, | |
26 | wxXML_HTML_DOCUMENT_NODE = 13 | |
27 | }; | |
28 | ||
23324ae1 FM |
29 | /** |
30 | @class wxXmlNode | |
7c913512 | 31 | |
23324ae1 | 32 | Represents a node in an XML document. See wxXmlDocument. |
7c913512 | 33 | |
f41d6c8c FM |
34 | Node has a name and may have content and attributes. |
35 | ||
36 | Most common node types are @c wxXML_TEXT_NODE (name and attributes are irrelevant) | |
4ce846b1 FM |
37 | and @c wxXML_ELEMENT_NODE. |
38 | ||
39 | Example: in <tt>\<title\>hi\</title\></tt> there is an element with the name | |
40 | @c title and irrelevant content and one child of type @c wxXML_TEXT_NODE | |
41 | with @c hi as content. | |
7c913512 | 42 | |
23324ae1 FM |
43 | If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to |
44 | wxXmlDocument::Load (default is UTF-8). | |
7c913512 | 45 | |
23324ae1 FM |
46 | @library{wxxml} |
47 | @category{xml} | |
7c913512 | 48 | |
e54c96f1 | 49 | @see wxXmlDocument, wxXmlAttribute |
23324ae1 | 50 | */ |
7c913512 | 51 | class wxXmlNode |
23324ae1 FM |
52 | { |
53 | public: | |
23324ae1 | 54 | /** |
f41d6c8c FM |
55 | Creates this XML node and eventually insert it into an existing XML tree. |
56 | ||
57 | @param parent | |
58 | The parent node to which append this node instance. | |
59 | If this argument is @NULL this new node will be floating and it can | |
60 | be appended later to another one using the AddChild() or InsertChild() | |
61 | functions. Otherwise the child is already added to the XML tree by | |
62 | this constructor and it shouldn't be done again. | |
63 | @param type | |
64 | One of the ::wxXmlNodeType enumeration value. | |
65 | @param name | |
66 | The name of the node. This is the string which appears between angular brackets. | |
67 | @param content | |
68 | The content of the node. | |
69 | Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE. | |
70 | @param attrs | |
71 | If not @NULL, this wxXmlAttribute object and its eventual siblings are attached to the node. | |
72 | @param next | |
73 | If not @NULL, this node and its eventual siblings are attached to the node. | |
74 | @param lineNo | |
75 | Number of line this node was present at in input file or -1. | |
23324ae1 FM |
76 | */ |
77 | wxXmlNode(wxXmlNode* parent, wxXmlNodeType type, | |
78 | const wxString& name, | |
79 | const wxString& content = wxEmptyString, | |
4cc4bfaf FM |
80 | wxXmlAttribute* attrs = NULL, |
81 | wxXmlNode* next = NULL, int lineNo = -1); | |
f41d6c8c FM |
82 | |
83 | /** | |
84 | A simplified version of the first constructor form, assuming a @NULL parent. | |
85 | ||
86 | @param type | |
87 | One of the ::wxXmlNodeType enumeration value. | |
88 | @param name | |
89 | The name of the node. This is the string which appears between angular brackets. | |
90 | @param content | |
91 | The content of the node. | |
92 | Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE. | |
93 | @param lineNo | |
94 | Number of line this node was present at in input file or -1. | |
95 | */ | |
7c913512 FM |
96 | wxXmlNode(wxXmlNodeType type, const wxString& name, |
97 | const wxString& content = wxEmptyString, | |
98 | int lineNo = -1); | |
f41d6c8c FM |
99 | |
100 | /** | |
101 | Copy constructor. | |
102 | ||
103 | Note that this does NOT copy syblings and parent pointer, i.e. GetParent() | |
104 | and GetNext() will return @NULL after using copy ctor and are never unmodified by operator=(). | |
105 | On the other hand, it DOES copy children and attributes. | |
106 | */ | |
107 | wxXmlNode(const wxXmlNode& node); | |
23324ae1 FM |
108 | |
109 | /** | |
110 | The virtual destructor. Deletes attached children and attributes. | |
111 | */ | |
adaaa686 | 112 | virtual ~wxXmlNode(); |
23324ae1 | 113 | |
23324ae1 | 114 | /** |
f41d6c8c FM |
115 | Appends a attribute with given @a name and @a value to the list of |
116 | attributes for this node. | |
23324ae1 | 117 | */ |
adaaa686 | 118 | virtual void AddAttribute(const wxString& name, const wxString& value); |
f41d6c8c FM |
119 | |
120 | /** | |
121 | Appends given attribute to the list of attributes for this node. | |
122 | */ | |
adaaa686 | 123 | virtual void AddAttribute(wxXmlAttribute* attr); |
23324ae1 FM |
124 | |
125 | /** | |
43a302f2 VS |
126 | Adds node @a child as the last child of this node. |
127 | ||
128 | @note | |
129 | Note that this function works in O(n) time where @e n is the number | |
130 | of existing children. Consequently, adding large number of child | |
131 | nodes using this method can be expensive, because it has O(n^2) time | |
132 | complexity in number of nodes to be added. Use InsertChildAfter() to | |
133 | populate XML tree in linear time. | |
134 | ||
135 | @see InsertChild(), InsertChildAfter() | |
23324ae1 | 136 | */ |
adaaa686 | 137 | virtual void AddChild(wxXmlNode* child); |
23324ae1 FM |
138 | |
139 | /** | |
4cc4bfaf | 140 | Removes the first attributes which has the given @a name from the list of |
23324ae1 FM |
141 | attributes for this node. |
142 | */ | |
adaaa686 | 143 | virtual bool DeleteAttribute(const wxString& name); |
23324ae1 | 144 | |
f41d6c8c FM |
145 | /** |
146 | Returns true if a attribute named attrName could be found. | |
147 | The value of that attribute is saved in value (which must not be @NULL). | |
148 | */ | |
149 | bool GetAttribute(const wxString& attrName, wxString* value) const; | |
150 | ||
23324ae1 | 151 | /** |
4cc4bfaf FM |
152 | Returns the value of the attribute named @a attrName if it does exist. |
153 | If it does not exist, the @a defaultVal is returned. | |
23324ae1 | 154 | */ |
f41d6c8c FM |
155 | wxString GetAttribute(const wxString& attrName, |
156 | const wxString& defaultVal = wxEmptyString) const; | |
23324ae1 FM |
157 | |
158 | /** | |
159 | Return a pointer to the first attribute of this node. | |
160 | */ | |
328f5751 | 161 | wxXmlAttribute* GetAttributes() const; |
23324ae1 FM |
162 | |
163 | /** | |
164 | Returns the first child of this node. | |
165 | To get a pointer to the second child of this node (if it does exist), use the | |
166 | GetNext() function on the returned value. | |
167 | */ | |
328f5751 | 168 | wxXmlNode* GetChildren() const; |
23324ae1 FM |
169 | |
170 | /** | |
171 | Returns the content of this node. Can be an empty string. | |
172 | Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type) | |
f41d6c8c | 173 | the content is an empty string. See GetNodeContent() for more details. |
23324ae1 | 174 | */ |
95b4a59e | 175 | const wxString& GetContent() const; |
23324ae1 FM |
176 | |
177 | /** | |
178 | Returns the number of nodes which separe this node from @c grandparent. | |
f41d6c8c FM |
179 | |
180 | This function searches only the parents of this node until it finds | |
181 | @a grandparent or the @NULL node (which is the parent of non-linked | |
182 | nodes or the parent of a wxXmlDocument's root node). | |
23324ae1 | 183 | */ |
328f5751 | 184 | int GetDepth(wxXmlNode* grandparent = NULL) const; |
23324ae1 FM |
185 | |
186 | /** | |
f41d6c8c | 187 | Returns line number of the node in the input XML file or @c -1 if it is unknown. |
23324ae1 | 188 | */ |
328f5751 | 189 | int GetLineNumber() const; |
23324ae1 FM |
190 | |
191 | /** | |
f41d6c8c FM |
192 | Returns the name of this node. |
193 | Can be an empty string (e.g. for nodes of type @c wxXML_TEXT_NODE or | |
194 | @c wxXML_CDATA_SECTION_NODE). | |
23324ae1 | 195 | */ |
95b4a59e | 196 | const wxString& GetName() const; |
23324ae1 FM |
197 | |
198 | /** | |
199 | Returns a pointer to the sibling of this node or @NULL if there are no | |
200 | siblings. | |
201 | */ | |
328f5751 | 202 | wxXmlNode* GetNext() const; |
23324ae1 FM |
203 | |
204 | /** | |
f41d6c8c FM |
205 | Returns the content of the first child node of type @c wxXML_TEXT_NODE |
206 | or @c wxXML_CDATA_SECTION_NODE. | |
207 | This function is very useful since the XML snippet @c "tagnametagcontent/tagname" | |
208 | is represented by expat with the following tag tree: | |
209 | ||
210 | @code | |
211 | wxXML_ENTITY_NODE name="tagname", content="" | |
212 | |-- wxXML_TEXT_NODE name="", content="tagcontent" | |
213 | @endcode | |
b5cc5cbd | 214 | |
23324ae1 | 215 | or eventually: |
b5cc5cbd | 216 | |
f41d6c8c FM |
217 | @code |
218 | wxXML_ENTITY_NODE name="tagname", content="" | |
219 | |-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent" | |
220 | @endcode | |
221 | ||
222 | An empty string is returned if the node has no children of type | |
223 | @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content | |
224 | of the first child of such types is empty. | |
23324ae1 | 225 | */ |
328f5751 | 226 | wxString GetNodeContent() const; |
23324ae1 FM |
227 | |
228 | /** | |
229 | Returns a pointer to the parent of this node or @NULL if this node has no | |
230 | parent. | |
231 | */ | |
328f5751 | 232 | wxXmlNode* GetParent() const; |
23324ae1 FM |
233 | |
234 | /** | |
235 | Returns the type of this node. | |
236 | */ | |
328f5751 | 237 | wxXmlNodeType GetType() const; |
23324ae1 FM |
238 | |
239 | /** | |
f41d6c8c | 240 | Returns @true if this node has a attribute named @a attrName. |
23324ae1 | 241 | */ |
328f5751 | 242 | bool HasAttribute(const wxString& attrName) const; |
23324ae1 FM |
243 | |
244 | /** | |
5e05df3c VS |
245 | Inserts the @a child node immediately before @a followingNode in the |
246 | children list. | |
247 | ||
248 | @return @true if @a followingNode has been found and the @a child | |
249 | node has been inserted. | |
250 | ||
251 | @note | |
252 | For historical reasons, @a followingNode may be @NULL. In that case, | |
253 | then @a child is prepended to the list of children and becomes the | |
254 | first child of this node, i.e. it behaves identically to using the | |
255 | first children (as returned by GetChildren()) for @a followingNode). | |
43a302f2 VS |
256 | |
257 | @see AddChild(), InsertChildAfter() | |
5e05df3c | 258 | */ |
adaaa686 | 259 | virtual bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode); |
23324ae1 | 260 | |
43a302f2 VS |
261 | /** |
262 | Inserts the @a child node immediately after @a precedingNode in the | |
263 | children list. | |
264 | ||
265 | @return @true if @a precedingNode has been found and the @a child | |
266 | node has been inserted. | |
267 | ||
77bfb902 FM |
268 | @param child |
269 | The child to insert. | |
43a302f2 VS |
270 | @param precedingNode |
271 | The node to insert @a child after. As a special case, this can be | |
272 | @NULL if this node has no children yet -- in that case, @a child | |
273 | will become this node's only child node. | |
274 | ||
275 | @since 2.8.8 | |
276 | ||
277 | @see InsertChild(), AddChild() | |
278 | */ | |
adaaa686 | 279 | virtual bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode); |
43a302f2 | 280 | |
23324ae1 FM |
281 | /** |
282 | Returns @true if the content of this node is a string containing only | |
f41d6c8c FM |
283 | whitespaces (spaces, tabs, new lines, etc). |
284 | ||
285 | Note that this function is locale-independent since the parsing of XML | |
286 | documents must always produce the exact same tree regardless of the | |
287 | locale it runs under. | |
23324ae1 | 288 | */ |
328f5751 | 289 | bool IsWhitespaceOnly() const; |
23324ae1 FM |
290 | |
291 | /** | |
f41d6c8c FM |
292 | Removes the given node from the children list. |
293 | ||
294 | Returns @true if the node was found and removed or @false if the node | |
295 | could not be found. | |
296 | Note that the caller is reponsible for deleting the removed node in order | |
297 | to avoid memory leaks. | |
23324ae1 | 298 | */ |
adaaa686 | 299 | virtual bool RemoveChild(wxXmlNode* child); |
23324ae1 FM |
300 | |
301 | /** | |
302 | Sets as first attribute the given wxXmlAttribute object. | |
f41d6c8c FM |
303 | |
304 | The caller is responsible to delete any previously present attributes | |
305 | attached to this node. | |
23324ae1 FM |
306 | */ |
307 | void SetAttributes(wxXmlAttribute* attr); | |
308 | ||
309 | /** | |
f41d6c8c FM |
310 | Sets as first child the given node. |
311 | ||
312 | The caller is responsible to delete any previously present children node. | |
23324ae1 FM |
313 | */ |
314 | void SetChildren(wxXmlNode* child); | |
315 | ||
316 | /** | |
317 | Sets the content of this node. | |
318 | */ | |
319 | void SetContent(const wxString& con); | |
320 | ||
321 | /** | |
322 | Sets the name of this node. | |
323 | */ | |
324 | void SetName(const wxString& name); | |
325 | ||
326 | /** | |
f41d6c8c FM |
327 | Sets as sibling the given node. |
328 | ||
329 | The caller is responsible to delete any previously present sibling node. | |
23324ae1 FM |
330 | */ |
331 | void SetNext(wxXmlNode* next); | |
332 | ||
333 | /** | |
f41d6c8c FM |
334 | Sets as parent the given node. |
335 | ||
336 | The caller is responsible to delete any previously present parent node. | |
23324ae1 FM |
337 | */ |
338 | void SetParent(wxXmlNode* parent); | |
339 | ||
340 | /** | |
341 | Sets the type of this node. | |
342 | */ | |
343 | void SetType(wxXmlNodeType type); | |
344 | ||
345 | /** | |
346 | See the copy constructor for more info. | |
347 | */ | |
f41d6c8c | 348 | wxXmlNode& operator=(const wxXmlNode& node); |
23324ae1 FM |
349 | }; |
350 | ||
351 | ||
e54c96f1 | 352 | |
23324ae1 FM |
353 | /** |
354 | @class wxXmlAttribute | |
7c913512 | 355 | |
23324ae1 | 356 | Represents a node attribute. |
7c913512 | 357 | |
4ce846b1 FM |
358 | Example: in <tt>\<img src="hello.gif" id="3"/\></tt>, @c src is an attribute |
359 | with value @c hello.gif and @c id is an attribute with value @c 3. | |
7c913512 | 360 | |
23324ae1 FM |
361 | @library{wxxml} |
362 | @category{xml} | |
7c913512 | 363 | |
e54c96f1 | 364 | @see wxXmlDocument, wxXmlNode |
23324ae1 | 365 | */ |
7c913512 | 366 | class wxXmlAttribute |
23324ae1 FM |
367 | { |
368 | public: | |
23324ae1 | 369 | /** |
f41d6c8c | 370 | Default constructor. |
23324ae1 FM |
371 | */ |
372 | wxXmlAttribute(); | |
f41d6c8c FM |
373 | |
374 | /** | |
375 | Creates the attribute with given @a name and @a value. | |
376 | If @a next is not @NULL, then sets it as sibling of this attribute. | |
377 | */ | |
7c913512 | 378 | wxXmlAttribute(const wxString& name, const wxString& value, |
4cc4bfaf | 379 | wxXmlAttribute* next = NULL); |
23324ae1 FM |
380 | |
381 | /** | |
382 | The virtual destructor. | |
383 | */ | |
adaaa686 | 384 | virtual ~wxXmlAttribute(); |
23324ae1 FM |
385 | |
386 | /** | |
387 | Returns the name of this attribute. | |
388 | */ | |
328f5751 | 389 | wxString GetName() const; |
23324ae1 FM |
390 | |
391 | /** | |
392 | Returns the sibling of this attribute or @NULL if there are no siblings. | |
393 | */ | |
328f5751 | 394 | wxXmlAttribute* GetNext() const; |
23324ae1 FM |
395 | |
396 | /** | |
397 | Returns the value of this attribute. | |
398 | */ | |
328f5751 | 399 | wxString GetValue() const; |
23324ae1 FM |
400 | |
401 | /** | |
402 | Sets the name of this attribute. | |
403 | */ | |
404 | void SetName(const wxString& name); | |
405 | ||
406 | /** | |
407 | Sets the sibling of this attribute. | |
408 | */ | |
409 | void SetNext(wxXmlAttribute* next); | |
410 | ||
411 | /** | |
412 | Sets the value of this attribute. | |
413 | */ | |
414 | void SetValue(const wxString& value); | |
415 | }; | |
416 | ||
417 | ||
e54c96f1 | 418 | |
23324ae1 FM |
419 | /** |
420 | @class wxXmlDocument | |
7c913512 | 421 | |
23324ae1 | 422 | This class holds XML data/document as parsed by XML parser in the root node. |
7c913512 | 423 | |
23324ae1 FM |
424 | wxXmlDocument internally uses the expat library which comes with wxWidgets to |
425 | parse the given stream. | |
7c913512 | 426 | |
23324ae1 | 427 | A simple example of using XML classes is: |
7c913512 | 428 | |
23324ae1 FM |
429 | @code |
430 | wxXmlDocument doc; | |
1707da0c | 431 | if (!doc.Load("myfile.xml")) |
4ce846b1 | 432 | return false; |
7c913512 | 433 | |
23324ae1 | 434 | // start processing the XML file |
1707da0c | 435 | if (doc.GetRoot()->GetName() != "myroot-node") |
4ce846b1 | 436 | return false; |
7c913512 | 437 | |
1707da0c | 438 | wxXmlNode *child = doc.GetRoot()->GetChildren(); |
23324ae1 | 439 | while (child) { |
7c913512 | 440 | |
4ce846b1 | 441 | if (child->GetName() == "tag1") { |
7c913512 | 442 | |
23324ae1 | 443 | // process text enclosed by tag1/tag1 |
1707da0c | 444 | wxString content = child->GetNodeContent(); |
7c913512 | 445 | |
23324ae1 | 446 | ... |
7c913512 | 447 | |
23324ae1 | 448 | // process attributes of tag1 |
7c913512 | 449 | wxString attrvalue1 = |
1707da0c | 450 | child->GetAttribute("attr1", "default-value"); |
7c913512 | 451 | wxString attrvalue2 = |
1707da0c | 452 | child->GetAttribute("attr2", "default-value"); |
7c913512 | 453 | |
23324ae1 | 454 | ... |
7c913512 | 455 | |
1707da0c | 456 | } else if (child->GetName() == "tag2") { |
7c913512 | 457 | |
23324ae1 FM |
458 | // process tag2 ... |
459 | } | |
7c913512 | 460 | |
1707da0c | 461 | child = child->GetNext(); |
23324ae1 FM |
462 | } |
463 | @endcode | |
7c913512 | 464 | |
f41d6c8c FM |
465 | Note that if you want to preserve the original formatting of the loaded file |
466 | including whitespaces and indentation, you need to turn off whitespace-only | |
467 | textnode removal and automatic indentation: | |
7c913512 | 468 | |
23324ae1 FM |
469 | @code |
470 | wxXmlDocument doc; | |
1707da0c | 471 | doc.Load("myfile.xml", "UTF-8", wxXMLDOC_KEEP_WHITESPACE_NODES); |
7c913512 | 472 | |
23324ae1 | 473 | // myfile2.xml will be indentic to myfile.xml saving it this way: |
1707da0c | 474 | doc.Save("myfile2.xml", wxXML_NO_INDENTATION); |
23324ae1 | 475 | @endcode |
7c913512 | 476 | |
23324ae1 | 477 | Using default parameters, you will get a reformatted document which in general |
f41d6c8c | 478 | is different from the original loaded content: |
7c913512 | 479 | |
23324ae1 FM |
480 | @code |
481 | wxXmlDocument doc; | |
1707da0c FM |
482 | doc.Load("myfile.xml"); |
483 | doc.Save("myfile2.xml"); // myfile2.xml != myfile.xml | |
23324ae1 | 484 | @endcode |
7c913512 | 485 | |
23324ae1 FM |
486 | @library{wxxml} |
487 | @category{xml} | |
7c913512 | 488 | |
e54c96f1 | 489 | @see wxXmlNode, wxXmlAttribute |
23324ae1 FM |
490 | */ |
491 | class wxXmlDocument : public wxObject | |
492 | { | |
493 | public: | |
23324ae1 | 494 | /** |
f41d6c8c | 495 | Default constructor. |
23324ae1 FM |
496 | */ |
497 | wxXmlDocument(); | |
f41d6c8c FM |
498 | |
499 | /** | |
500 | Copy constructor. Deep copies all the XML tree of the given document. | |
501 | */ | |
7c913512 | 502 | wxXmlDocument(const wxXmlDocument& doc); |
f41d6c8c FM |
503 | |
504 | /** | |
505 | Loads the given filename using the given encoding. See Load(). | |
506 | */ | |
507 | wxXmlDocument(const wxString& filename, | |
1707da0c | 508 | const wxString& encoding = "UTF-8")); |
f41d6c8c FM |
509 | |
510 | /** | |
511 | Loads the XML document from given stream using the given encoding. See Load(). | |
512 | */ | |
513 | wxXmlDocument(wxInputStream& stream, | |
514 | const wxString& encoding = wxT("UTF-8")); | |
23324ae1 FM |
515 | |
516 | /** | |
517 | Virtual destructor. Frees the document root node. | |
518 | */ | |
adaaa686 | 519 | virtual ~wxXmlDocument(); |
23324ae1 FM |
520 | |
521 | /** | |
f41d6c8c FM |
522 | Detaches the document root node and returns it. |
523 | ||
524 | The document root node will be set to @NULL and thus IsOk() will | |
525 | return @false after calling this function. | |
526 | ||
527 | Note that the caller is reponsible for deleting the returned node in order | |
528 | to avoid memory leaks. | |
23324ae1 FM |
529 | */ |
530 | wxXmlNode* DetachRoot(); | |
531 | ||
532 | /** | |
533 | Returns encoding of in-memory representation of the document | |
534 | (same as passed to Load() or constructor, defaults to UTF-8). | |
f41d6c8c | 535 | |
1add55ae | 536 | @note this is meaningless in Unicode build where data are stored as @c wchar_t*. |
23324ae1 | 537 | */ |
328f5751 | 538 | wxString GetEncoding() const; |
23324ae1 FM |
539 | |
540 | /** | |
541 | Returns encoding of document (may be empty). | |
f41d6c8c FM |
542 | |
543 | @note This is the encoding original file was saved in, @b not the | |
544 | encoding of in-memory representation! | |
23324ae1 | 545 | */ |
95b4a59e | 546 | const wxString& GetFileEncoding() const; |
23324ae1 FM |
547 | |
548 | /** | |
549 | Returns the root node of the document. | |
550 | */ | |
328f5751 | 551 | wxXmlNode* GetRoot() const; |
23324ae1 FM |
552 | |
553 | /** | |
554 | Returns the version of document. | |
f41d6c8c FM |
555 | |
556 | This is the value in the @c \<?xml version="1.0"?\> header of the XML document. | |
23324ae1 FM |
557 | If the version attribute was not explicitely given in the header, this function |
558 | returns an empty string. | |
559 | */ | |
95b4a59e | 560 | const wxString& GetVersion() const; |
23324ae1 FM |
561 | |
562 | /** | |
563 | Returns @true if the document has been loaded successfully. | |
564 | */ | |
328f5751 | 565 | bool IsOk() const; |
23324ae1 | 566 | |
f41d6c8c | 567 | |
23324ae1 | 568 | /** |
f41d6c8c FM |
569 | Parses @a filename as an xml document and loads its data. |
570 | ||
571 | If @a flags does not contain wxXMLDOC_KEEP_WHITESPACE_NODES, then, while loading, | |
572 | all nodes of type @c wxXML_TEXT_NODE (see wxXmlNode) are automatically skipped | |
573 | if they contain whitespaces only. | |
574 | ||
575 | The removal of these nodes makes the load process slightly faster and requires | |
576 | less memory however makes impossible to recreate exactly the loaded text with a | |
577 | Save() call later. Read the initial description of this class for more info. | |
578 | ||
579 | Returns true on success, false otherwise. | |
580 | */ | |
581 | virtual bool Load(const wxString& filename, | |
582 | const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE); | |
583 | ||
584 | /** | |
585 | Like Load(const wxString&, const wxString&, int) but takes the data from | |
586 | given input stream. | |
587 | */ | |
588 | virtual bool Load(wxInputStream& stream, | |
589 | const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE); | |
590 | ||
591 | /** | |
592 | Saves XML tree creating a file named with given string. | |
593 | ||
594 | If @a indentstep is greater than or equal to zero, then, while saving, | |
595 | an automatic indentation is added with steps composed by indentstep spaces. | |
596 | ||
597 | If @a indentstep is @c wxXML_NO_INDENTATION, then, automatic indentation | |
598 | is turned off. | |
23324ae1 | 599 | */ |
f41d6c8c | 600 | virtual bool Save(const wxString& filename, int indentstep = 1) const; |
23324ae1 | 601 | |
23324ae1 | 602 | /** |
f41d6c8c FM |
603 | Saves XML tree in the given output stream. |
604 | See Save(const wxString&, int) for a description of @a indentstep. | |
23324ae1 | 605 | */ |
f41d6c8c | 606 | virtual bool Save(wxOutputStream& stream, int indentstep = 1) const; |
23324ae1 FM |
607 | |
608 | /** | |
609 | Sets the enconding of the document. | |
610 | */ | |
611 | void SetEncoding(const wxString& enc); | |
612 | ||
613 | /** | |
614 | Sets the enconding of the file which will be used to save the document. | |
615 | */ | |
616 | void SetFileEncoding(const wxString& encoding); | |
617 | ||
618 | /** | |
619 | Sets the root node of this document. Deletes previous root node. | |
f41d6c8c FM |
620 | Use DetachRoot() and then SetRoot() if you want to replace the root |
621 | node without deleting the old document tree. | |
23324ae1 FM |
622 | */ |
623 | void SetRoot(wxXmlNode* node); | |
624 | ||
625 | /** | |
626 | Sets the version of the XML file which will be used to save the document. | |
627 | */ | |
628 | void SetVersion(const wxString& version); | |
629 | ||
630 | /** | |
631 | Deep copies the given document. | |
632 | */ | |
f41d6c8c | 633 | wxXmlDocument& operator=(const wxXmlDocument& doc); |
23324ae1 | 634 | }; |
e54c96f1 | 635 |