--- /dev/null
+/////////////////////////////////////////////////////////////////////////////
+// Name: xml/xml.h
+// Purpose: documentation for wxXmlNode class
+// 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}
+
+ @seealso
+ 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 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.
+ */
+ void AddChild(wxXmlNode* child);
+
+ /**
+ Removes the first attributes which has the given @e 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.
+ */
+ bool GetAttribute(const wxString& attrName, wxString* value);
+ wxString GetAttribute(const wxString& attrName,
+ const wxString& defaultVal);
+ //@}
+
+ /**
+ Return a pointer to the first attribute of this node.
+ */
+ wxXmlAttribute * GetAttributes();
+
+ /**
+ 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();
+
+ /**
+ 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();
+
+ /**
+ 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);
+
+ /**
+ Returns line number of the node in the input XML file or -1 if it is unknown.
+ */
+ int GetLineNumber();
+
+ /**
+ 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();
+
+ /**
+ Returns a pointer to the sibling of this node or @NULL if there are no
+ siblings.
+ */
+ wxXmlNode* GetNext();
+
+ /**
+ 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();
+
+ /**
+ Returns a pointer to the parent of this node or @NULL if this node has no
+ parent.
+ */
+ wxXmlNode* GetParent();
+
+ /**
+ Returns the type of this node.
+ */
+ wxXmlNodeType GetType();
+
+ /**
+ Returns @true if this node has a attribute named @e attrName.
+ */
+ bool HasAttribute(const wxString& attrName);
+
+ /**
+ 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.
+ */
+ bool InsertChild(wxXmlNode* child, wxXmlNode* before_node);
+
+ /**
+ 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();
+
+ /**
+ 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}
+
+ @seealso
+ 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.
+ */
+ wxXmlAttribute();
+ wxXmlAttribute(const wxString& name, const wxString& value,
+ wxXmlAttribute* next = @NULL);
+ //@}
+
+ /**
+ The virtual destructor.
+ */
+ ~wxXmlAttribute();
+
+ /**
+ Returns the name of this attribute.
+ */
+ wxString GetName();
+
+ /**
+ Returns the sibling of this attribute or @NULL if there are no siblings.
+ */
+ wxXmlAttribute* GetNext();
+
+ /**
+ Returns the value of this attribute.
+ */
+ wxString GetValue();
+
+ /**
+ 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
+
+ @b 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
+*/
+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).
+
+ NB: this is meaningless in Unicode build where data are stored as @c wchar_t*.
+ */
+ wxString GetEncoding();
+
+ /**
+ 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();
+
+ /**
+ Returns the root node of the document.
+ */
+ wxXmlNode* GetRoot();
+
+ /**
+ 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();
+
+ /**
+ Returns @true if the document has been loaded successfully.
+ */
+#define bool IsOk() /* implementation is private */
+
+ //@{
+ /**
+ , @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);
+ bool Save(wxOutputStream& stream, int indentstep = 1);
+ //@}
+
+ /**
+ 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);
+};
projects / wxWidgets.git / blobdiff