X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/92b6654b661cf8438d191872de3b3c07e4eeb035..ae3c17b4013e80b99976c750c19fca47729517f6:/interface/wx/xml/xml.h diff --git a/interface/wx/xml/xml.h b/interface/wx/xml/xml.h new file mode 100644 index 0000000000..bbc63c62ed --- /dev/null +++ b/interface/wx/xml/xml.h @@ -0,0 +1,518 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: xml/xml.h +// Purpose: interface of wxXmlNode +// 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} + + @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 + @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} + + @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 + @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 + + @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); +}; +