]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/xml/xml.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxXmlNode, wxXmlAttribute, wxXmlDocument
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
10 /// Represents XML node type.
13 // note: values are synchronized with xmlElementType from libxml
14 wxXML_ELEMENT_NODE
= 1,
15 wxXML_ATTRIBUTE_NODE
= 2,
17 wxXML_CDATA_SECTION_NODE
= 4,
18 wxXML_ENTITY_REF_NODE
= 5,
19 wxXML_ENTITY_NODE
= 6,
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
32 Represents a node in an XML document. See wxXmlDocument.
34 Node has a name and may have content and attributes.
36 Most common node types are @c wxXML_TEXT_NODE (name and attributes are irrelevant)
37 and @c wxXML_ELEMENT_NODE.
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.
43 If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to
44 wxXmlDocument::Load (default is UTF-8).
49 @see wxXmlDocument, wxXmlAttribute
55 Creates this XML node and eventually insert it into an existing XML tree.
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.
64 One of the ::wxXmlNodeType enumeration value.
66 The name of the node. This is the string which appears between angular brackets.
68 The content of the node.
69 Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
71 If not @NULL, this wxXmlAttribute object and its eventual siblings are attached to the node.
73 If not @NULL, this node and its eventual siblings are attached to the node.
75 Number of line this node was present at in input file or -1.
77 wxXmlNode(wxXmlNode
* parent
, wxXmlNodeType type
,
79 const wxString
& content
= wxEmptyString
,
80 wxXmlAttribute
* attrs
= NULL
,
81 wxXmlNode
* next
= NULL
, int lineNo
= -1);
84 A simplified version of the first constructor form, assuming a @NULL parent.
87 One of the ::wxXmlNodeType enumeration value.
89 The name of the node. This is the string which appears between angular brackets.
91 The content of the node.
92 Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
94 Number of line this node was present at in input file or -1.
96 wxXmlNode(wxXmlNodeType type
, const wxString
& name
,
97 const wxString
& content
= wxEmptyString
,
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.
107 wxXmlNode(const wxXmlNode
& node
);
110 The virtual destructor. Deletes attached children and attributes.
112 virtual ~wxXmlNode();
115 Appends a attribute with given @a name and @a value to the list of
116 attributes for this node.
118 virtual void AddAttribute(const wxString
& name
, const wxString
& value
);
121 Appends given attribute to the list of attributes for this node.
123 virtual void AddAttribute(wxXmlAttribute
* attr
);
126 Adds node @a child as the last child of this node.
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.
135 @see InsertChild(), InsertChildAfter()
137 virtual void AddChild(wxXmlNode
* child
);
140 Removes the first attributes which has the given @a name from the list of
141 attributes for this node.
143 virtual bool DeleteAttribute(const wxString
& name
);
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).
149 bool GetAttribute(const wxString
& attrName
, wxString
* value
) const;
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.
155 wxString
GetAttribute(const wxString
& attrName
,
156 const wxString
& defaultVal
= wxEmptyString
) const;
159 Return a pointer to the first attribute of this node.
161 wxXmlAttribute
* GetAttributes() const;
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.
168 wxXmlNode
* GetChildren() const;
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)
173 the content is an empty string. See GetNodeContent() for more details.
175 const wxString
& GetContent() const;
178 Returns the number of nodes which separe this node from @c grandparent.
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).
184 int GetDepth(wxXmlNode
* grandparent
= NULL
) const;
187 Returns a flag indicating whether encoding conversion is necessary when saving. The default is @false.
189 You can improve saving efficiency considerably by setting this value.
191 bool GetNoConversion() const;
194 Returns line number of the node in the input XML file or @c -1 if it is unknown.
196 int GetLineNumber() const;
199 Returns the name of this node.
200 Can be an empty string (e.g. for nodes of type @c wxXML_TEXT_NODE or
201 @c wxXML_CDATA_SECTION_NODE).
203 const wxString
& GetName() const;
206 Returns a pointer to the sibling of this node or @NULL if there are no
209 wxXmlNode
* GetNext() const;
212 Returns the content of the first child node of type @c wxXML_TEXT_NODE
213 or @c wxXML_CDATA_SECTION_NODE.
214 This function is very useful since the XML snippet @c "tagnametagcontent/tagname"
215 is represented by expat with the following tag tree:
218 wxXML_ENTITY_NODE name="tagname", content=""
219 |-- wxXML_TEXT_NODE name="", content="tagcontent"
225 wxXML_ENTITY_NODE name="tagname", content=""
226 |-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
229 An empty string is returned if the node has no children of type
230 @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content
231 of the first child of such types is empty.
233 wxString
GetNodeContent() const;
236 Returns a pointer to the parent of this node or @NULL if this node has no
239 wxXmlNode
* GetParent() const;
242 Returns the type of this node.
244 wxXmlNodeType
GetType() const;
247 Returns @true if this node has a attribute named @a attrName.
249 bool HasAttribute(const wxString
& attrName
) const;
252 Inserts the @a child node immediately before @a followingNode in the
255 @return @true if @a followingNode has been found and the @a child
256 node has been inserted.
259 For historical reasons, @a followingNode may be @NULL. In that case,
260 then @a child is prepended to the list of children and becomes the
261 first child of this node, i.e. it behaves identically to using the
262 first children (as returned by GetChildren()) for @a followingNode).
264 @see AddChild(), InsertChildAfter()
266 virtual bool InsertChild(wxXmlNode
* child
, wxXmlNode
* followingNode
);
269 Inserts the @a child node immediately after @a precedingNode in the
272 @return @true if @a precedingNode has been found and the @a child
273 node has been inserted.
278 The node to insert @a child after. As a special case, this can be
279 @NULL if this node has no children yet -- in that case, @a child
280 will become this node's only child node.
284 @see InsertChild(), AddChild()
286 virtual bool InsertChildAfter(wxXmlNode
* child
, wxXmlNode
* precedingNode
);
289 Returns @true if the content of this node is a string containing only
290 whitespaces (spaces, tabs, new lines, etc).
292 Note that this function is locale-independent since the parsing of XML
293 documents must always produce the exact same tree regardless of the
294 locale it runs under.
296 bool IsWhitespaceOnly() const;
299 Removes the given node from the children list.
301 Returns @true if the node was found and removed or @false if the node
303 Note that the caller is reponsible for deleting the removed node in order
304 to avoid memory leaks.
306 virtual bool RemoveChild(wxXmlNode
* child
);
309 Sets as first attribute the given wxXmlAttribute object.
311 The caller is responsible for deleting any previously present attributes
312 attached to this node.
314 void SetAttributes(wxXmlAttribute
* attr
);
317 Sets as first child the given node.
319 The caller is responsible for deleting any previously present children node.
321 void SetChildren(wxXmlNode
* child
);
324 Sets the content of this node.
326 void SetContent(const wxString
& con
);
329 Sets the name of this node.
331 void SetName(const wxString
& name
);
334 Sets as sibling the given node.
336 The caller is responsible for deleting any previously present sibling node.
338 void SetNext(wxXmlNode
* next
);
341 Sets a flag to indicate whether encoding conversion is necessary when saving. The default is @false.
343 You can improve saving efficiency considerably by setting this value.
345 void SetNoConversion(bool noconversion
);
348 Sets as parent the given node.
350 The caller is responsible for deleting any previously present parent node.
352 void SetParent(wxXmlNode
* parent
);
355 Sets the type of this node.
357 void SetType(wxXmlNodeType type
);
360 See the copy constructor for more info.
362 wxXmlNode
& operator=(const wxXmlNode
& node
);
368 @class wxXmlAttribute
370 Represents a node attribute.
372 Example: in <tt>\<img src="hello.gif" id="3"/\></tt>, @c src is an attribute
373 with value @c hello.gif and @c id is an attribute with value @c 3.
378 @see wxXmlDocument, wxXmlNode
389 Creates the attribute with given @a name and @a value.
390 If @a next is not @NULL, then sets it as sibling of this attribute.
392 wxXmlAttribute(const wxString
& name
, const wxString
& value
,
393 wxXmlAttribute
* next
= NULL
);
396 The virtual destructor.
398 virtual ~wxXmlAttribute();
401 Returns the name of this attribute.
403 wxString
GetName() const;
406 Returns the sibling of this attribute or @NULL if there are no siblings.
408 wxXmlAttribute
* GetNext() const;
411 Returns the value of this attribute.
413 wxString
GetValue() const;
416 Sets the name of this attribute.
418 void SetName(const wxString
& name
);
421 Sets the sibling of this attribute.
423 void SetNext(wxXmlAttribute
* next
);
426 Sets the value of this attribute.
428 void SetValue(const wxString
& value
);
436 This class holds XML data/document as parsed by XML parser in the root node.
438 wxXmlDocument internally uses the expat library which comes with wxWidgets to
439 parse the given stream.
441 A simple example of using XML classes is:
445 if (!doc.Load("myfile.xml"))
448 // start processing the XML file
449 if (doc.GetRoot()->GetName() != "myroot-node")
452 wxXmlNode *child = doc.GetRoot()->GetChildren();
455 if (child->GetName() == "tag1") {
457 // process text enclosed by tag1/tag1
458 wxString content = child->GetNodeContent();
462 // process attributes of tag1
463 wxString attrvalue1 =
464 child->GetAttribute("attr1", "default-value");
465 wxString attrvalue2 =
466 child->GetAttribute("attr2", "default-value");
470 } else if (child->GetName() == "tag2") {
475 child = child->GetNext();
479 Note that if you want to preserve the original formatting of the loaded file
480 including whitespaces and indentation, you need to turn off whitespace-only
481 textnode removal and automatic indentation:
485 doc.Load("myfile.xml", "UTF-8", wxXMLDOC_KEEP_WHITESPACE_NODES);
487 // myfile2.xml will be indentic to myfile.xml saving it this way:
488 doc.Save("myfile2.xml", wxXML_NO_INDENTATION);
491 Using default parameters, you will get a reformatted document which in general
492 is different from the original loaded content:
496 doc.Load("myfile.xml");
497 doc.Save("myfile2.xml"); // myfile2.xml != myfile.xml
503 @see wxXmlNode, wxXmlAttribute
505 class wxXmlDocument
: public wxObject
514 Copy constructor. Deep copies all the XML tree of the given document.
516 wxXmlDocument(const wxXmlDocument
& doc
);
519 Loads the given filename using the given encoding. See Load().
521 wxXmlDocument(const wxString
& filename
,
522 const wxString
& encoding
= "UTF-8"));
525 Loads the XML document from given stream using the given encoding. See Load().
527 wxXmlDocument(wxInputStream
& stream
,
528 const wxString
& encoding
= "UTF-8");
531 Virtual destructor. Frees the document root node.
533 virtual ~wxXmlDocument();
536 Detaches the document root node and returns it.
538 The document root node will be set to @NULL and thus IsOk() will
539 return @false after calling this function.
541 Note that the caller is reponsible for deleting the returned node in order
542 to avoid memory leaks.
544 wxXmlNode
* DetachRoot();
547 Returns encoding of in-memory representation of the document
548 (same as passed to Load() or constructor, defaults to UTF-8).
550 @note this is meaningless in Unicode build where data are stored as @c wchar_t*.
552 wxString
GetEncoding() const;
555 Returns encoding of document (may be empty).
557 @note This is the encoding original file was saved in, @b not the
558 encoding of in-memory representation!
560 const wxString
& GetFileEncoding() const;
563 Returns the root node of the document.
565 wxXmlNode
* GetRoot() const;
568 Returns the version of document.
570 This is the value in the @c \<?xml version="1.0"?\> header of the XML document.
571 If the version attribute was not explicitely given in the header, this function
572 returns an empty string.
574 const wxString
& GetVersion() const;
577 Returns @true if the document has been loaded successfully.
583 Parses @a filename as an xml document and loads its data.
585 If @a flags does not contain wxXMLDOC_KEEP_WHITESPACE_NODES, then, while loading,
586 all nodes of type @c wxXML_TEXT_NODE (see wxXmlNode) are automatically skipped
587 if they contain whitespaces only.
589 The removal of these nodes makes the load process slightly faster and requires
590 less memory however makes impossible to recreate exactly the loaded text with a
591 Save() call later. Read the initial description of this class for more info.
593 Returns true on success, false otherwise.
595 virtual bool Load(const wxString
& filename
,
596 const wxString
& encoding
= "UTF-8", int flags
= wxXMLDOC_NONE
);
599 Like Load(const wxString&, const wxString&, int) but takes the data from
602 virtual bool Load(wxInputStream
& stream
,
603 const wxString
& encoding
= "UTF-8", int flags
= wxXMLDOC_NONE
);
606 Saves XML tree creating a file named with given string.
608 If @a indentstep is greater than or equal to zero, then, while saving,
609 an automatic indentation is added with steps composed by indentstep spaces.
611 If @a indentstep is @c wxXML_NO_INDENTATION, then, automatic indentation
614 virtual bool Save(const wxString
& filename
, int indentstep
= 2) const;
617 Saves XML tree in the given output stream.
618 See Save(const wxString&, int) for a description of @a indentstep.
620 virtual bool Save(wxOutputStream
& stream
, int indentstep
= 2) const;
623 Sets the enconding of the document.
625 void SetEncoding(const wxString
& enc
);
628 Sets the enconding of the file which will be used to save the document.
630 void SetFileEncoding(const wxString
& encoding
);
633 Sets the root node of this document. Deletes previous root node.
634 Use DetachRoot() and then SetRoot() if you want to replace the root
635 node without deleting the old document tree.
637 void SetRoot(wxXmlNode
* node
);
640 Sets the version of the XML file which will be used to save the document.
642 void SetVersion(const wxString
& version
);
645 Deep copies the given document.
647 wxXmlDocument
& operator=(const wxXmlDocument
& doc
);
650 Get expat library version information.
655 static wxVersionInfo
GetLibraryVersionInfo();