X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..de536319f16406adf967003637b2655c61f6cb09:/interface/xml/xml.h diff --git a/interface/xml/xml.h b/interface/xml/xml.h index 46ce11466c..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 @@ -24,8 +24,7 @@ @library{wxxml} @category{xml} - @seealso - wxXmlDocument, wxXmlAttribute + @see wxXmlDocument, wxXmlAttribute */ class wxXmlNode { @@ -37,8 +36,8 @@ public: wxXmlNode(wxXmlNode* parent, wxXmlNodeType type, const wxString& name, const wxString& content = wxEmptyString, - wxXmlAttribute* attrs = @NULL, - wxXmlNode* next = @NULL, 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, @@ -59,39 +58,46 @@ public: //@} /** - 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 @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 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* before_node); + 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 @@ -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,6 +267,7 @@ public: }; + /** @class wxXmlAttribute @headerfile xml.h wx/xml/xml.h @@ -248,20 +280,19 @@ public: @library{wxxml} @category{xml} - @seealso - wxXmlDocument, wxXmlNode + @see 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. + 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* 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,6 +332,7 @@ public: }; + /** @class wxXmlDocument @headerfile xml.h wx/xml/xml.h @@ -350,7 +382,7 @@ public: } @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: @@ -376,8 +408,7 @@ public: @library{wxxml} @category{xml} - @seealso - wxXmlNode, wxXmlAttribute + @see wxXmlNode, wxXmlAttribute */ class wxXmlDocument : public wxObject { @@ -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,17 +462,16 @@ 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); @@ -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; //@} /** @@ -488,3 +515,4 @@ public: */ wxXmlDocument& operator operator=(const wxXmlDocument& doc); }; +