[wxWidgets.git] / interface / xml / xml.h

/////////////////////////////////////////////////////////////////////////////
// Name:        xml/xml.h
// Purpose:     documentation for wxXmlNode class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxXmlNode
    @headerfile xml.h wx/xml/xml.h
    
    Represents a node in an XML document. See wxXmlDocument.
    
    Node has a name and may have content and attributes. Most common node types are 
    @c wxXML_TEXT_NODE (name and attributes are irrelevant) and 
    @c wxXML_ELEMENT_NODE (e.g. in @c titlehi/title there is an element
    with name="title", irrelevant content and one child (@c wxXML_TEXT_NODE
    with content="hi").
    
    If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to
    wxXmlDocument::Load (default is UTF-8).
    
    @library{wxxml}
    @category{xml}
    
    @seealso
    wxXmlDocument, wxXmlAttribute
*/
class wxXmlNode 
{
public:
    //@{
    /**
        A simplified version of the first constructor form, assuming a @NULL parent.
    */
    wxXmlNode(wxXmlNode* parent, wxXmlNodeType type,
              const wxString& name,
              const wxString& content = wxEmptyString,
              wxXmlAttribute* attrs = @NULL,
              wxXmlNode* next = @NULL, int lineNo = -1);
        wxXmlNode(const wxXmlNode& node);
        wxXmlNode(wxXmlNodeType type, const wxString& name,
                  const wxString& content = wxEmptyString,
                  int lineNo = -1);
    //@}

    /**
        The virtual destructor. Deletes attached children and attributes.
    */
    ~wxXmlNode();

    //@{
    /**
        Appends given attribute to the list of attributes for this node.
    */
    void AddAttribute(const wxString& name, const wxString& value);
        void AddAttribute(wxXmlAttribute* attr);
    //@}

    /**
        Adds the given node as child of this node. To attach a second children to this
        node, use the
        SetNext() function of the @e child node.
    */
    void AddChild(wxXmlNode* child);

    /**
        Removes the first attributes which has the given @e name from the list of
        attributes for this node.
    */
    bool DeleteAttribute(const wxString& name);

    //@{
    /**
        Returns the value of the attribute named @e attrName if it does exist.
        If it does not exist, the @e defaultVal is returned.
    */
    bool GetAttribute(const wxString& attrName, wxString* value);
        wxString GetAttribute(const wxString& attrName,
                              const wxString& defaultVal);
    //@}

    /**
        Return a pointer to the first attribute of this node.
    */
    wxXmlAttribute * GetAttributes();

    /**
        Returns the first child of this node.
        To get a pointer to the second child of this node (if it does exist), use the
        GetNext() function on the returned value.
    */
    wxXmlNode* GetChildren();

    /**
        Returns the content of this node. Can be an empty string.
        Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type)
        the
        content is an empty string. See GetNodeContent() for more details.
    */
    wxString GetContent();

    /**
        Returns the number of nodes which separe this node from @c grandparent.
        
        This function searches only the parents of this node until it finds @c
        grandparent
        or the @NULL node (which is the parent of non-linked nodes or the parent of a
        wxXmlDocument's root node).
    */
    int GetDepth(wxXmlNode* grandparent = @NULL);

    /**
        Returns line number of the node in the input XML file or -1 if it is unknown.
    */
    int GetLineNumber();

    /**
        Returns the name of this node. Can be an empty string (e.g. for nodes of type
        @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE).
    */
    wxString GetName();

    /**
        Returns a pointer to the sibling of this node or @NULL if there are no
        siblings.
    */
    wxXmlNode* GetNext();

    /**
        Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c
        wxXML_CDATA_SECTION_NODE.
        This function is very useful since the XML snippet @c
        "tagnametagcontent/tagname" is represented by
        expat with the following tag tree:
        or eventually:
        An empty string is returned if the node has no children of type @c
        wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty.
    */
    wxString GetNodeContent();

    /**
        Returns a pointer to the parent of this node or @NULL if this node has no
        parent.
    */
    wxXmlNode* GetParent();

    /**
        Returns the type of this node.
    */
    wxXmlNodeType GetType();

    /**
        Returns @true if this node has a attribute named @e attrName.
    */
    bool HasAttribute(const wxString& attrName);

    /**
        Inserts the @e child node after @e before_node in the children list.
        If @e before_node is @NULL, then @e child is prepended to the list of
        children and
        becomes the first child of this node.
        Returns @true if @e before_node has been found and the @e child node has been
        inserted.
    */
    bool InsertChild(wxXmlNode* child, wxXmlNode* before_node);

    /**
        Returns @true if the content of this node is a string containing only
        whitespaces (spaces,
        tabs, new lines, etc). Note that this function is locale-independent since the
        parsing of XML
        documents must always produce the exact same tree regardless of the locale it
        runs under.
    */
    bool IsWhitespaceOnly();

    /**
        Removes the given node from the children list. Returns @true if the node was
        found and removed
        or @false if the node could not be found.
        
        Note that the caller is reponsible for deleting the removed node in order to
        avoid memory leaks.
    */
    bool RemoveChild(wxXmlNode* child);

    /**
        Sets as first attribute the given wxXmlAttribute object.
        The caller is responsible to delete any previously present attributes attached
        to this node.
    */
    void SetAttributes(wxXmlAttribute* attr);

    /**
        Sets as first child the given node. The caller is responsible to delete any
        previously present
        children node.
    */
    void SetChildren(wxXmlNode* child);

    /**
        Sets the content of this node.
    */
    void SetContent(const wxString& con);

    /**
        Sets the name of this node.
    */
    void SetName(const wxString& name);

    /**
        Sets as sibling the given node. The caller is responsible to delete any
        previously present
        sibling node.
    */
    void SetNext(wxXmlNode* next);

    /**
        Sets as parent the given node. The caller is responsible to delete any
        previously present
        parent node.
    */
    void SetParent(wxXmlNode* parent);

    /**
        Sets the type of this node.
    */
    void SetType(wxXmlNodeType type);

    /**
        See the copy constructor for more info.
    */
    wxXmlNode operator=(const wxXmlNode& node);
};


/**
    @class wxXmlAttribute
    @headerfile xml.h wx/xml/xml.h
    
    Represents a node attribute.
    
    Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value
    @c "hello.gif" and @c "id" is a attribute with value @c "3".
    
    @library{wxxml}
    @category{xml}
    
    @seealso
    wxXmlDocument, wxXmlNode
*/
class wxXmlAttribute 
{
public:
    //@{
    /**
        Creates the attribute with given @e name and @e value.
        If @e next is not @NULL, then sets it as sibling of this attribute.
    */
    wxXmlAttribute();
        wxXmlAttribute(const wxString& name, const wxString& value,
                       wxXmlAttribute* next = @NULL);
    //@}

    /**
        The virtual destructor.
    */
    ~wxXmlAttribute();

    /**
        Returns the name of this attribute.
    */
    wxString GetName();

    /**
        Returns the sibling of this attribute or @NULL if there are no siblings.
    */
    wxXmlAttribute* GetNext();

    /**
        Returns the value of this attribute.
    */
    wxString GetValue();

    /**
        Sets the name of this attribute.
    */
    void SetName(const wxString& name);

    /**
        Sets the sibling of this attribute.
    */
    void SetNext(wxXmlAttribute* next);

    /**
        Sets the value of this attribute.
    */
    void SetValue(const wxString& value);
};


/**
    @class wxXmlDocument
    @headerfile xml.h wx/xml/xml.h
    
    This class holds XML data/document as parsed by XML parser in the root node.
    
    wxXmlDocument internally uses the expat library which comes with wxWidgets to
    parse the given stream.
    
    A simple example of using XML classes is:
    
    @code
    wxXmlDocument doc;
    if (!doc.Load(wxT("myfile.xml")))
        return @false;
    
    // start processing the XML file
    if (doc.GetRoot()-GetName() != wxT("myroot-node"))
        return @false;
    
    wxXmlNode *child = doc.GetRoot()-GetChildren();
    while (child) {
    
        if (child-GetName() == wxT("tag1")) {
    
            // process text enclosed by tag1/tag1
            wxString content = child-GetNodeContent();
    
            ...
    
            // process attributes of tag1
            wxString attrvalue1 = 
                child-GetAttribute(wxT("attr1"), 
                                  wxT("default-value"));
            wxString attrvalue2 = 
                child-GetAttribute(wxT("attr2"), 
                                  wxT("default-value"));
    
            ...
    
        } else if (child-GetName() == wxT("tag2")) {
    
            // process tag2 ...
        }
    
        child = child-GetNext();
    }
    @endcode
    
    @b Note: if you want to preserve the original formatting of the loaded file
    including whitespaces
    and indentation, you need to turn off whitespace-only textnode removal and
    automatic indentation:
    
    @code
    wxXmlDocument doc;
    doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES);
    
    // myfile2.xml will be indentic to myfile.xml saving it this way:
    doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION);
    @endcode
    
    Using default parameters, you will get a reformatted document which in general
    is different from
    the original loaded content:
    
    @code
    wxXmlDocument doc;
    doc.Load(wxT("myfile.xml"));
    doc.Save(wxT("myfile2.xml"));  // myfile2.xml != myfile.xml
    @endcode
    
    @library{wxxml}
    @category{xml}
    
    @seealso
    wxXmlNode, wxXmlAttribute
*/
class wxXmlDocument : public wxObject
{
public:
    //@{
    /**
        Copy constructor. Deep copies all the XML tree of the given document.
    */
    wxXmlDocument();
        wxXmlDocument(const wxString& filename);
        wxXmlDocument(wxInputStream& stream);
        wxXmlDocument(const wxXmlDocument& doc);
    //@}

    /**
        Virtual destructor. Frees the document root node.
    */
    ~wxXmlDocument();

    /**
        Detaches the document root node and returns it. The document root node will be
        set to @NULL
        and thus IsOk() will return @false after calling this function.
        
        Note that the caller is reponsible for deleting the returned node in order to
        avoid memory leaks.
    */
    wxXmlNode* DetachRoot();

    /**
        Returns encoding of in-memory representation of the document
        (same as passed to Load() or constructor, defaults to UTF-8).
        
        NB: this is meaningless in Unicode build where data are stored as @c wchar_t*.
    */
    wxString GetEncoding();

    /**
        Returns encoding of document (may be empty).
        
        Note: this is the encoding original file was saved in, @b not the
        encoding of in-memory representation!
    */
    wxString GetFileEncoding();

    /**
        Returns the root node of the document.
    */
    wxXmlNode* GetRoot();

    /**
        Returns the version of document.
        This is the value in the @c ?xml version="1.0"? header of the XML document.
        If the version attribute was not explicitely given in the header, this function
        returns an empty string.
    */
    wxString GetVersion();

    /**
        Returns @true if the document has been loaded successfully.
    */
#define bool IsOk()     /* implementation is private */

    //@{
    /**
        , @b int@e flags = wxXMLDOC_NONE)
        
        Like above but takes the data from given input stream.
    */
    bool Load(const wxString& filename);
        int bool Load(wxInputStream& stream);
    //@}

    //@{
    /**
        Saves XML tree in the given output stream. See other overload for a description
        of @c indentstep.
    */
    bool Save(const wxString& filename, int indentstep = 1);
        bool Save(wxOutputStream& stream, int indentstep = 1);
    //@}

    /**
        Sets the enconding of the document.
    */
    void SetEncoding(const wxString& enc);

    /**
        Sets the enconding of the file which will be used to save the document.
    */
    void SetFileEncoding(const wxString& encoding);

    /**
        Sets the root node of this document. Deletes previous root node.
        Use DetachRoot() and then 
        SetRoot() if you want
        to replace the root node without deleting the old document tree.
    */
    void SetRoot(wxXmlNode* node);

    /**
        Sets the version of the XML file which will be used to save the document.
    */
    void SetVersion(const wxString& version);

    /**
        Deep copies the given document.
    */
    wxXmlDocument& operator operator=(const wxXmlDocument& doc);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: xml/xml.h
	3	// Purpose: documentation for wxXmlNode class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxXmlNode
	11	@headerfile xml.h wx/xml/xml.h
	12
	13	Represents a node in an XML document. See wxXmlDocument.
	14
	15	Node has a name and may have content and attributes. Most common node types are
	16	@c wxXML_TEXT_NODE (name and attributes are irrelevant) and
	17	@c wxXML_ELEMENT_NODE (e.g. in @c titlehi/title there is an element
	18	with name="title", irrelevant content and one child (@c wxXML_TEXT_NODE
	19	with content="hi").
	20
	21	If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to
	22	wxXmlDocument::Load (default is UTF-8).
	23
	24	@library{wxxml}
	25	@category{xml}
	26
	27	@seealso
	28	wxXmlDocument, wxXmlAttribute
	29	*/
	30	class wxXmlNode
	31	{
	32	public:
	33	//@{
	34	/**
	35	A simplified version of the first constructor form, assuming a @NULL parent.
	36	*/
	37	wxXmlNode(wxXmlNode* parent, wxXmlNodeType type,
	38	const wxString& name,
	39	const wxString& content = wxEmptyString,
	40	wxXmlAttribute* attrs = @NULL,
	41	wxXmlNode* next = @NULL, int lineNo = -1);
	42	wxXmlNode(const wxXmlNode& node);
	43	wxXmlNode(wxXmlNodeType type, const wxString& name,
	44	const wxString& content = wxEmptyString,
	45	int lineNo = -1);
	46	//@}
	47
	48	/**
	49	The virtual destructor. Deletes attached children and attributes.
	50	*/
	51	~wxXmlNode();
	52
	53	//@{
	54	/**
	55	Appends given attribute to the list of attributes for this node.
	56	*/
	57	void AddAttribute(const wxString& name, const wxString& value);
	58	void AddAttribute(wxXmlAttribute* attr);
	59	//@}
	60
	61	/**
	62	Adds the given node as child of this node. To attach a second children to this
	63	node, use the
	64	SetNext() function of the @e child node.
65	*/
66	void AddChild(wxXmlNode* child);
67
68	/**
69	Removes the first attributes which has the given @e name from the list of
70	attributes for this node.
71	*/
72	bool DeleteAttribute(const wxString& name);
73
74	//@{
75	/**
76	Returns the value of the attribute named @e attrName if it does exist.
77	If it does not exist, the @e defaultVal is returned.
78	*/
79	bool GetAttribute(const wxString& attrName, wxString* value);
80	wxString GetAttribute(const wxString& attrName,
81	const wxString& defaultVal);
82	//@}
83
84	/**
85	Return a pointer to the first attribute of this node.
86	*/
87	wxXmlAttribute * GetAttributes();
88
89	/**
90	Returns the first child of this node.
91	To get a pointer to the second child of this node (if it does exist), use the
92	GetNext() function on the returned value.
93	*/
94	wxXmlNode* GetChildren();
95
96	/**
97	Returns the content of this node. Can be an empty string.
98	Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type)
99	the
100	content is an empty string. See GetNodeContent() for more details.
101	*/
102	wxString GetContent();
103
104	/**
105	Returns the number of nodes which separe this node from @c grandparent.
106
107	This function searches only the parents of this node until it finds @c
108	grandparent
109	or the @NULL node (which is the parent of non-linked nodes or the parent of a
110	wxXmlDocument's root node).
111	*/
112	int GetDepth(wxXmlNode* grandparent = @NULL);
113
114	/**
115	Returns line number of the node in the input XML file or -1 if it is unknown.
116	*/
117	int GetLineNumber();
118
119	/**
120	Returns the name of this node. Can be an empty string (e.g. for nodes of type
121	@c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE).
122	*/
123	wxString GetName();
124
125	/**
126	Returns a pointer to the sibling of this node or @NULL if there are no
127	siblings.
128	*/
129	wxXmlNode* GetNext();
130
131	/**
132	Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c
133	wxXML_CDATA_SECTION_NODE.
134	This function is very useful since the XML snippet @c
135	"tagnametagcontent/tagname" is represented by
136	expat with the following tag tree:
137	or eventually:
138	An empty string is returned if the node has no children of type @c
139	wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty.
140	*/
141	wxString GetNodeContent();
142
143	/**
144	Returns a pointer to the parent of this node or @NULL if this node has no
145	parent.
146	*/
147	wxXmlNode* GetParent();
148
149	/**
150	Returns the type of this node.
151	*/
152	wxXmlNodeType GetType();
153
154	/**
155	Returns @true if this node has a attribute named @e attrName.
156	*/
157	bool HasAttribute(const wxString& attrName);
158
159	/**
160	Inserts the @e child node after @e before_node in the children list.
161	If @e before_node is @NULL, then @e child is prepended to the list of
162	children and
163	becomes the first child of this node.
164	Returns @true if @e before_node has been found and the @e child node has been
165	inserted.
166	*/
167	bool InsertChild(wxXmlNode* child, wxXmlNode* before_node);
168
169	/**
170	Returns @true if the content of this node is a string containing only
171	whitespaces (spaces,
172	tabs, new lines, etc). Note that this function is locale-independent since the
173	parsing of XML
174	documents must always produce the exact same tree regardless of the locale it
175	runs under.
176	*/
177	bool IsWhitespaceOnly();
178
179	/**
180	Removes the given node from the children list. Returns @true if the node was
181	found and removed
182	or @false if the node could not be found.
183
184	Note that the caller is reponsible for deleting the removed node in order to
185	avoid memory leaks.
186	*/
187	bool RemoveChild(wxXmlNode* child);
188
189	/**
190	Sets as first attribute the given wxXmlAttribute object.
191	The caller is responsible to delete any previously present attributes attached
192	to this node.
193	*/
194	void SetAttributes(wxXmlAttribute* attr);
195
196	/**
197	Sets as first child the given node. The caller is responsible to delete any
198	previously present
199	children node.
200	*/
201	void SetChildren(wxXmlNode* child);
202
203	/**
204	Sets the content of this node.
205	*/
206	void SetContent(const wxString& con);
207
208	/**
209	Sets the name of this node.
210	*/
211	void SetName(const wxString& name);
212
213	/**
214	Sets as sibling the given node. The caller is responsible to delete any
215	previously present
216	sibling node.
217	*/
218	void SetNext(wxXmlNode* next);
219
220	/**
221	Sets as parent the given node. The caller is responsible to delete any
222	previously present
223	parent node.
224	*/
225	void SetParent(wxXmlNode* parent);
226
227	/**
228	Sets the type of this node.
229	*/
230	void SetType(wxXmlNodeType type);
231
232	/**
233	See the copy constructor for more info.
234	*/
235	wxXmlNode operator=(const wxXmlNode& node);
236	};
237
238
239	/**
240	@class wxXmlAttribute
241	@headerfile xml.h wx/xml/xml.h
242
243	Represents a node attribute.
244
245	Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value
246	@c "hello.gif" and @c "id" is a attribute with value @c "3".
247
248	@library{wxxml}
249	@category{xml}
250
251	@seealso
252	wxXmlDocument, wxXmlNode
253	*/
254	class wxXmlAttribute
255	{
256	public:
257	//@{
258	/**
259	Creates the attribute with given @e name and @e value.
260	If @e next is not @NULL, then sets it as sibling of this attribute.
261	*/
262	wxXmlAttribute();
263	wxXmlAttribute(const wxString& name, const wxString& value,
264	wxXmlAttribute* next = @NULL);
265	//@}
266
267	/**
268	The virtual destructor.
269	*/
270	~wxXmlAttribute();
271
272	/**
273	Returns the name of this attribute.
274	*/
275	wxString GetName();
276
277	/**
278	Returns the sibling of this attribute or @NULL if there are no siblings.
279	*/
280	wxXmlAttribute* GetNext();
281
282	/**
283	Returns the value of this attribute.
284	*/
285	wxString GetValue();
286
287	/**
288	Sets the name of this attribute.
289	*/
290	void SetName(const wxString& name);
291
292	/**
293	Sets the sibling of this attribute.
294	*/
295	void SetNext(wxXmlAttribute* next);
296
297	/**
298	Sets the value of this attribute.
299	*/
300	void SetValue(const wxString& value);
301	};
302
303
304	/**
305	@class wxXmlDocument
306	@headerfile xml.h wx/xml/xml.h
307
308	This class holds XML data/document as parsed by XML parser in the root node.
309
310	wxXmlDocument internally uses the expat library which comes with wxWidgets to
311	parse the given stream.
312
313	A simple example of using XML classes is:
314
315	@code
316	wxXmlDocument doc;
317	if (!doc.Load(wxT("myfile.xml")))
318	return @false;
319
320	// start processing the XML file
321	if (doc.GetRoot()-GetName() != wxT("myroot-node"))
322	return @false;
323
324	wxXmlNode *child = doc.GetRoot()-GetChildren();
325	while (child) {
326
327	if (child-GetName() == wxT("tag1")) {
328
329	// process text enclosed by tag1/tag1
330	wxString content = child-GetNodeContent();
331
332	...
333
334	// process attributes of tag1
335	wxString attrvalue1 =
336	child-GetAttribute(wxT("attr1"),
337	wxT("default-value"));
338	wxString attrvalue2 =
339	child-GetAttribute(wxT("attr2"),
340	wxT("default-value"));
341
342	...
343
344	} else if (child-GetName() == wxT("tag2")) {
345
346	// process tag2 ...
347	}
348
349	child = child-GetNext();
350	}
351	@endcode
352
353	@b Note: if you want to preserve the original formatting of the loaded file
354	including whitespaces
355	and indentation, you need to turn off whitespace-only textnode removal and
356	automatic indentation:
357
358	@code
359	wxXmlDocument doc;
360	doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES);
361
362	// myfile2.xml will be indentic to myfile.xml saving it this way:
363	doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION);
364	@endcode
365
366	Using default parameters, you will get a reformatted document which in general
367	is different from
368	the original loaded content:
369
370	@code
371	wxXmlDocument doc;
372	doc.Load(wxT("myfile.xml"));
373	doc.Save(wxT("myfile2.xml")); // myfile2.xml != myfile.xml
374	@endcode
375
376	@library{wxxml}
377	@category{xml}
378
379	@seealso
380	wxXmlNode, wxXmlAttribute
381	*/
382	class wxXmlDocument : public wxObject
383	{
384	public:
385	//@{
386	/**
387	Copy constructor. Deep copies all the XML tree of the given document.
388	*/
389	wxXmlDocument();
390	wxXmlDocument(const wxString& filename);
391	wxXmlDocument(wxInputStream& stream);
392	wxXmlDocument(const wxXmlDocument& doc);
393	//@}
394
395	/**
396	Virtual destructor. Frees the document root node.
397	*/
398	~wxXmlDocument();
399
400	/**
401	Detaches the document root node and returns it. The document root node will be
402	set to @NULL
403	and thus IsOk() will return @false after calling this function.
404
405	Note that the caller is reponsible for deleting the returned node in order to
406	avoid memory leaks.
407	*/
408	wxXmlNode* DetachRoot();
409
410	/**
411	Returns encoding of in-memory representation of the document
412	(same as passed to Load() or constructor, defaults to UTF-8).
413
414	NB: this is meaningless in Unicode build where data are stored as @c wchar_t*.
415	*/
416	wxString GetEncoding();
417
418	/**
419	Returns encoding of document (may be empty).
420
421	Note: this is the encoding original file was saved in, @b not the
422	encoding of in-memory representation!
423	*/
424	wxString GetFileEncoding();
425
426	/**
427	Returns the root node of the document.
428	*/
429	wxXmlNode* GetRoot();
430
431	/**
432	Returns the version of document.
433	This is the value in the @c ?xml version="1.0"? header of the XML document.
434	If the version attribute was not explicitely given in the header, this function
435	returns an empty string.
436	*/
437	wxString GetVersion();
438
439	/**
440	Returns @true if the document has been loaded successfully.
441	*/
442	#define bool IsOk() /* implementation is private */
443
444	//@{
445	/**
446	, @b int@e flags = wxXMLDOC_NONE)
447
448	Like above but takes the data from given input stream.
449	*/
450	bool Load(const wxString& filename);
451	int bool Load(wxInputStream& stream);
452	//@}
453
454	//@{
455	/**
456	Saves XML tree in the given output stream. See other overload for a description
457	of @c indentstep.
458	*/
459	bool Save(const wxString& filename, int indentstep = 1);
460	bool Save(wxOutputStream& stream, int indentstep = 1);
461	//@}
462
463	/**
464	Sets the enconding of the document.
465	*/
466	void SetEncoding(const wxString& enc);
467
468	/**
469	Sets the enconding of the file which will be used to save the document.
470	*/
471	void SetFileEncoding(const wxString& encoding);
472
473	/**
474	Sets the root node of this document. Deletes previous root node.
475	Use DetachRoot() and then
476	SetRoot() if you want
477	to replace the root node without deleting the old document tree.
478	*/
479	void SetRoot(wxXmlNode* node);
480
481	/**
482	Sets the version of the XML file which will be used to save the document.
483	*/
484	void SetVersion(const wxString& version);
485
486	/**
487	Deep copies the given document.
488	*/
489	wxXmlDocument& operator operator=(const wxXmlDocument& doc);
490	};