///////////////////////////////////////////////////////////////////////////// // Name: xml/xml.h // Purpose: interface of wxXmlNode // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// /** @class wxXmlNode 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} @see 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 node @a child as the last child of this node. @note Note that this function works in O(n) time where @e n is the number of existing children. Consequently, adding large number of child nodes using this method can be expensive, because it has O(n^2) time complexity in number of nodes to be added. Use InsertChildAfter() to populate XML tree in linear time. @see InsertChild(), InsertChildAfter() */ void AddChild(wxXmlNode* child); /** Removes the first attributes which has the given @a name from the list of attributes for this node. */ bool DeleteAttribute(const wxString& name); //@{ /** Returns the value of the attribute named @a attrName if it does exist. If it does not exist, the @a defaultVal is returned. */ bool GetAttribute(const wxString& attrName, wxString* value) const; const wxString GetAttribute(const wxString& attrName, const wxString& defaultVal = wxEmptyString) const; //@} /** Return a pointer to the first attribute of this node. */ wxXmlAttribute* GetAttributes() const; /** 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() const; /** 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() const; /** 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) const; /** Returns line number of the node in the input XML file or -1 if it is unknown. */ int GetLineNumber() const; /** 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() const; /** Returns a pointer to the sibling of this node or @NULL if there are no siblings. */ wxXmlNode* GetNext() const; /** 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() const; /** Returns a pointer to the parent of this node or @NULL if this node has no parent. */ wxXmlNode* GetParent() const; /** Returns the type of this node. */ wxXmlNodeType GetType() const; /** Returns @true if this node has a attribute named @e attrName. */ bool HasAttribute(const wxString& attrName) const; /** Inserts the @a child node immediately before @a followingNode in the children list. @return @true if @a followingNode has been found and the @a child node has been inserted. @note For historical reasons, @a followingNode may be @NULL. In that case, then @a child is prepended to the list of children and becomes the first child of this node, i.e. it behaves identically to using the first children (as returned by GetChildren()) for @a followingNode). @see AddChild(), InsertChildAfter() */ bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode); /** Inserts the @a child node immediately after @a precedingNode in the children list. @return @true if @a precedingNode has been found and the @a child node has been inserted. @param precedingNode The node to insert @a child after. As a special case, this can be @NULL if this node has no children yet -- in that case, @a child will become this node's only child node. @since 2.8.8 @see InsertChild(), AddChild() */ bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode); /** 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() const; /** 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 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} @see wxXmlDocument, wxXmlNode */ class wxXmlAttribute { public: //@{ /** Creates the attribute with given @a name and @e value. If @a 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() const; /** Returns the sibling of this attribute or @NULL if there are no siblings. */ wxXmlAttribute* GetNext() const; /** Returns the value of this attribute. */ wxString GetValue() const; /** 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 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 @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} @see 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). @note this is meaningless in Unicode build where data are stored as @c wchar_t*. */ wxString GetEncoding() const; /** 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() const; /** Returns the root node of the document. */ wxXmlNode* GetRoot() const; /** 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() const; /** Returns @true if the document has been loaded successfully. */ bool IsOk() const; //@{ /** , @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) const; const bool Save(wxOutputStream& stream, int indentstep = 1) const; //@} /** 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); };