X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/23324ae1c7938ba904770fc456d3c07764b9c5e9..40c53d1b49569facfd71e30ef56d26df790621c4:/interface/xml/xml.h diff --git a/interface/xml/xml.h b/interface/xml/xml.h index 3925e340f3..bbc63c62ed 100644 --- a/interface/xml/xml.h +++ b/interface/xml/xml.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: xml/xml.h -// Purpose: documentation for wxXmlNode class +// Purpose: interface of wxXmlNode // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -9,25 +9,24 @@ /** @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 + + 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 + + @see wxXmlDocument, wxXmlAttribute */ -class wxXmlNode +class wxXmlNode { public: //@{ @@ -37,12 +36,12 @@ public: 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); + 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); //@} /** @@ -55,43 +54,50 @@ public: Appends given attribute to the list of attributes for this node. */ void AddAttribute(const wxString& name, const wxString& value); - void AddAttribute(wxXmlAttribute* attr); + 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. + 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 @e name from the list of + 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 @e attrName if it does exist. - If it does not exist, the @e defaultVal is returned. + 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); - wxString GetAttribute(const wxString& attrName, - const wxString& defaultVal); + 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(); + 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(); + wxXmlNode* GetChildren() const; /** Returns the content of this node. Can be an empty string. @@ -99,34 +105,33 @@ public: the content is an empty string. See GetNodeContent() for more details. */ - wxString GetContent(); + 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); + 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(); + 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(); + wxString GetName() const; /** Returns a pointer to the sibling of this node or @NULL if there are no siblings. */ - wxXmlNode* GetNext(); + wxXmlNode* GetNext() const; /** Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c @@ -134,37 +139,64 @@ public: 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(); + wxString GetNodeContent() const; /** Returns a pointer to the parent of this node or @NULL if this node has no parent. */ - wxXmlNode* GetParent(); + wxXmlNode* GetParent() const; /** Returns the type of this node. */ - wxXmlNodeType GetType(); + wxXmlNodeType GetType() const; /** Returns @true if this node has a attribute named @e attrName. */ - bool HasAttribute(const wxString& 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 @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. + 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 InsertChild(wxXmlNode* child, wxXmlNode* before_node); + bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode); /** Returns @true if the content of this node is a string containing only @@ -174,13 +206,12 @@ public: documents must always produce the exact same tree regardless of the locale it runs under. */ - bool IsWhitespaceOnly(); + 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. */ @@ -236,32 +267,32 @@ public: }; + /** @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 + + @see wxXmlDocument, wxXmlNode */ -class wxXmlAttribute +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. + 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); + wxXmlAttribute(const wxString& name, const wxString& value, + wxXmlAttribute* next = NULL); //@} /** @@ -272,17 +303,17 @@ public: /** Returns the name of this attribute. */ - wxString GetName(); + wxString GetName() const; /** Returns the sibling of this attribute or @NULL if there are no siblings. */ - wxXmlAttribute* GetNext(); + wxXmlAttribute* GetNext() const; /** Returns the value of this attribute. */ - wxString GetValue(); + wxString GetValue() const; /** Sets the name of this attribute. @@ -301,83 +332,83 @@ public: }; + /** @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"), + wxString attrvalue1 = + child-GetAttribute(wxT("attr1"), wxT("default-value")); - wxString attrvalue2 = - child-GetAttribute(wxT("attr2"), + 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 + + @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 + + @see wxXmlNode, wxXmlAttribute */ class wxXmlDocument : public wxObject { @@ -387,9 +418,9 @@ 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); + wxXmlDocument(const wxString& filename); + wxXmlDocument(wxInputStream& stream); + wxXmlDocument(const wxXmlDocument& doc); //@} /** @@ -401,7 +432,6 @@ public: 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. */ @@ -410,23 +440,21 @@ public: /** 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*. + @note this is meaningless in Unicode build where data are stored as @c wchar_t*. */ - wxString GetEncoding(); + 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(); + wxString GetFileEncoding() const; /** Returns the root node of the document. */ - wxXmlNode* GetRoot(); + wxXmlNode* GetRoot() const; /** Returns the version of document. @@ -434,21 +462,20 @@ public: If the version attribute was not explicitely given in the header, this function returns an empty string. */ - wxString GetVersion(); + wxString GetVersion() const; /** Returns @true if the document has been loaded successfully. */ -#define bool IsOk() /* implementation is private */ + 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); + int bool Load(wxInputStream& stream); //@} //@{ @@ -456,8 +483,8 @@ public: 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); + bool Save(const wxString& filename, int indentstep = 1) const; + const bool Save(wxOutputStream& stream, int indentstep = 1) const; //@} /** @@ -472,7 +499,7 @@ public: /** Sets the root node of this document. Deletes previous root node. - Use DetachRoot() and then + Use DetachRoot() and then SetRoot() if you want to replace the root node without deleting the old document tree. */ @@ -488,3 +515,4 @@ public: */ wxXmlDocument& operator operator=(const wxXmlDocument& doc); }; +