X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..592584e4e9c3c01a05fda770dcd1f88a8a8d69f1:/interface/xml/xml.h diff --git a/interface/xml/xml.h b/interface/xml/xml.h index 46ce11466c..c584e3e5ea 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, @@ -61,37 +60,37 @@ 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. + SetNext() function of the @a child node. */ 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 +98,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,34 +132,36 @@ 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 + Inserts the @a child node after @a before_node in the children list. + If @a before_node is @NULL, then @a 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 + Returns @true if @a before_node has been found and the @a child node has been inserted. */ bool InsertChild(wxXmlNode* child, wxXmlNode* before_node); @@ -174,13 +174,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 +235,7 @@ public: }; + /** @class wxXmlAttribute @headerfile xml.h wx/xml/xml.h @@ -248,20 +248,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 +271,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 +300,7 @@ public: }; + /** @class wxXmlDocument @headerfile xml.h wx/xml/xml.h @@ -376,8 +376,7 @@ public: @library{wxxml} @category{xml} - @seealso - wxXmlNode, wxXmlAttribute + @see wxXmlNode, wxXmlAttribute */ class wxXmlDocument : public wxObject { @@ -401,7 +400,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 +408,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*. */ - 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 +430,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 +451,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 +483,4 @@ public: */ wxXmlDocument& operator operator=(const wxXmlDocument& doc); }; +