/////////////////////////////////////////////////////////////////////////////
// Name: xml/xml.h
-// Purpose: documentation for wxXmlNode class
+// 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
+
+ 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:
//@{
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);
//@}
/**
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.
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
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
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.
*/
};
+
/**
@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);
//@}
/**
/**
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.
};
+
/**
@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
{
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);
//@}
/**
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.
*/
/**
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.
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);
//@}
//@{
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;
//@}
/**
/**
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.
*/
*/
wxXmlDocument& operator operator=(const wxXmlDocument& doc);
};
+
projects / wxWidgets.git / blobdiff