#include <wx/xml/xml.h>

Detailed Description

Represents a node in an XML document.

Each node is named and depending on the node type it may also hold content or be given attributes.

The two most common node types are wxXML_ELEMENT_NODE and wxXML_TEXT_NODE. wxXML_ELEMENT_NODE represents a pair of XML element tags, whilst wxXML_TEXT_NODE represents the text value that can belong to the element.

A wxXML_ELEMENT_NODE has a title, and optionally attributes, but does not have any content. A wxXML_TEXT_NODE does not have a title or attributes but should normally have content.

For example: in the XML fragment <title>hi</title> there is an element node with the name title and a single text node child with the text hi as content.

A wxXML_PI_NODE represents a Processing Instruction (PI) node with the name parameter set as the target and the contents parameter set as the instructions. Note that whilst the PI instructions are often in the form of pseudo-attributes, these do not use the node's attribute member. It is the user's responsibility to code and decode the PI instruction text.

The wxXML_DOCUMENT_TYPE_NODE is not implemented at this time. Instead, you should get and set the DOCTYPE values using the wxXmlDocument class.

If wxUSE_UNICODE is 0, all strings are encoded in the encoding given to wxXmlDocument::Load (default is UTF-8).

Note: Once a wxXmlNode has been added to a wxXmlDocument it becomes owned by the document and this has two implications. Firstly, the wxXmlDocument takes responsibility for deleting the node so the user should not delete it; and secondly, a wxXmlNode must always be created on the heap and never on the stack.

Library: wxXML

Category: XML

See also: wxXmlDocument, wxXmlDoctype, wxXmlAttribute

Public Member Functions
	wxXmlNode (wxXmlNode parent, wxXmlNodeType type, const wxString &name, const wxString &content=wxEmptyString, wxXmlAttribute attrs=NULL, wxXmlNode *next=NULL, int lineNo=-1)
	Creates this XML node and inserts it into the XML tree as a child of the specified parent. More...

	wxXmlNode (wxXmlNodeType type, const wxString &name, const wxString &content=wxEmptyString, int lineNo=-1)
	A simplified version of the first constructor form, assuming a NULL parent. More...

	wxXmlNode (const wxXmlNode &node)
	Copy constructor. More...

virtual	~wxXmlNode ()
	The virtual destructor. More...

virtual void	AddAttribute (const wxString &name, const wxString &value)
	Appends a attribute with given name and value to the list of attributes for this node. More...

virtual void	AddAttribute (wxXmlAttribute *attr)
	Appends given attribute to the list of attributes for this node. More...

virtual void	AddChild (wxXmlNode *child)
	Adds node child as the last child of this node. More...

virtual bool	DeleteAttribute (const wxString &name)
	Removes the first attributes which has the given name from the list of attributes for this node. More...

bool	GetAttribute (const wxString &attrName, wxString *value) const
	Returns true if a attribute named attrName could be found. More...

wxString	GetAttribute (const wxString &attrName, const wxString &defaultVal=wxEmptyString) const
	Returns the value of the attribute named attrName if it does exist. More...

wxXmlAttribute *	GetAttributes () const
	Return a pointer to the first attribute of this node. More...

wxXmlNode *	GetChildren () const
	Returns the first child of this node. More...

const wxString &	GetContent () const
	Returns the content of this node. More...

int	GetDepth (wxXmlNode *grandparent=NULL) const
	Returns the number of nodes which separate this node from `grandparent`. More...

bool	GetNoConversion () const
	Returns a flag indicating whether encoding conversion is necessary when saving. More...

int	GetLineNumber () const
	Returns line number of the node in the input XML file or `-1` if it is unknown. More...

const wxString &	GetName () const
	Returns the name of this node. More...

wxXmlNode *	GetNext () const
	Returns a pointer to the sibling of this node or NULL if there are no siblings. More...

wxString	GetNodeContent () const
	Returns the content of the first child node of type `wxXML_TEXT_NODE` or `wxXML_CDATA_SECTION_NODE`. More...

wxXmlNode *	GetParent () const
	Returns a pointer to the parent of this node or NULL if this node has no parent. More...

wxXmlNodeType	GetType () const
	Returns the type of this node. More...

bool	HasAttribute (const wxString &attrName) const
	Returns true if this node has a attribute named attrName. More...

virtual bool	InsertChild (wxXmlNode child, wxXmlNode followingNode)
	Inserts the child node immediately before followingNode in the children list. More...

virtual bool	InsertChildAfter (wxXmlNode child, wxXmlNode precedingNode)
	Inserts the child node immediately after precedingNode in the children list. More...

bool	IsWhitespaceOnly () const
	Returns true if the content of this node is a string containing only whitespaces (spaces, tabs, new lines, etc). More...

virtual bool	RemoveChild (wxXmlNode *child)
	Removes the given node from the children list. More...

void	SetAttributes (wxXmlAttribute *attr)
	Sets as first attribute the given wxXmlAttribute object. More...

void	SetChildren (wxXmlNode *child)
	Sets as first child the given node. More...

void	SetContent (const wxString &con)
	Sets the content of this node. More...

void	SetName (const wxString &name)
	Sets the name of this node. More...

void	SetNext (wxXmlNode *next)
	Sets as sibling the given node. More...

void	SetNoConversion (bool noconversion)
	Sets a flag to indicate whether encoding conversion is necessary when saving. More...

void	SetParent (wxXmlNode *parent)
	Sets as parent the given node. More...

void	SetType (wxXmlNodeType type)
	Sets the type of this node. More...

wxXmlNode &	operator= (const wxXmlNode &node)
	See the copy constructor for more info. More...

Constructor & Destructor Documentation

wxXmlNode::wxXmlNode	(	wxXmlNode *	parent,
		wxXmlNodeType	type,
		const wxString &	name,
		const wxString &	content = `wxEmptyString`,
		wxXmlAttribute *	attrs = `NULL`,
		wxXmlNode *	next = `NULL`,
		int	lineNo = `-1`
	)

Creates this XML node and inserts it into the XML tree as a child of the specified parent.

Once added, the XML tree takes ownership of this object and there is no need to delete it.

Parameters

parent	The parent node to which append this node instance. If this argument is NULL this new node will be floating and it can be appended later to another one using the AddChild() or InsertChild() functions. Otherwise the child is added to the XML tree by this constructor and it shouldn't be done again.
type	One of the wxXmlNodeType enumeration value.
name	The name of the node. This is the string which appears between angular brackets.
content	The content of the node. Only meaningful when type is `wxXML_TEXT_NODE` or `wxXML_CDATA_SECTION_NODE`.
attrs	If not NULL, this wxXmlAttribute object and its eventual siblings are attached to the node.
next	If not NULL, this node and its eventual siblings are attached to the node.
lineNo	Number of line this node was present at in input file or -1.

wxXmlNode::wxXmlNode	(	wxXmlNodeType	type,
		const wxString &	name,
		const wxString &	content = `wxEmptyString`,
		int	lineNo = `-1`
	)

A simplified version of the first constructor form, assuming a NULL parent.

Parameters

type	One of the wxXmlNodeType enumeration value.
name	The name of the node. This is the string which appears between angular brackets.
content	The content of the node. Only meaningful when type is `wxXML_TEXT_NODE` or `wxXML_CDATA_SECTION_NODE`.
lineNo	Number of line this node was present at in input file or -1.

wxXmlNode::wxXmlNode ( const wxXmlNode & node )

Copy constructor.

Note that this does NOT copy siblings and parent pointer, i.e. GetParent() and GetNext() will return NULL after using copy ctor and are never unmodified by operator=(). On the other hand, it DOES copy children and attributes.

virtual wxXmlNode::~wxXmlNode ( )

virtual

The virtual destructor.

Deletes attached children and attributes.

Member Function Documentation

virtual void wxXmlNode::AddAttribute	(	const wxString &	name,
		const wxString &	value
	)

virtual

Appends a attribute with given name and value to the list of attributes for this node.

virtual void wxXmlNode::AddAttribute ( wxXmlAttribute * attr )

virtual

Appends given attribute to the list of attributes for this node.

virtual void wxXmlNode::AddChild ( wxXmlNode * child )

virtual

Adds node child as the last child of this node.

Once added, the XML tree takes ownership of this object and there is no need to delete it.

Note: Note that this function works in O(n) time where 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 also: InsertChild(), InsertChildAfter()

virtual bool wxXmlNode::DeleteAttribute ( const wxString & name )

virtual

Removes the first attributes which has the given name from the list of attributes for this node.

bool wxXmlNode::GetAttribute	(	const wxString &	attrName,
		wxString *	value
	)		const

Returns true if a attribute named attrName could be found.

The value of that attribute is saved in value (which must not be NULL).

wxString wxXmlNode::GetAttribute	(	const wxString &	attrName,
		const wxString &	defaultVal = `wxEmptyString`
	)		const

Returns the value of the attribute named attrName if it does exist.

If it does not exist, the defaultVal is returned.

wxXmlAttribute* wxXmlNode::GetAttributes ( ) const

Return a pointer to the first attribute of this node.

wxXmlNode* wxXmlNode::GetChildren ( ) 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.

const wxString& wxXmlNode::GetContent ( ) const

Returns the content of this node.

Can be an empty string. Be aware that for nodes of type wxXML_ELEMENT_NODE (the most used node type) the content is an empty string. See GetNodeContent() for more details.

int wxXmlNode::GetDepth ( wxXmlNode * grandparent = NULL ) const

Returns the number of nodes which separate this node from grandparent.

This function searches only the parents of this node until it finds grandparent or the NULL node (which is the parent of non-linked nodes or the parent of a wxXmlDocument's root element node).

int wxXmlNode::GetLineNumber ( ) const

Returns line number of the node in the input XML file or -1 if it is unknown.

const wxString& wxXmlNode::GetName ( ) const

Returns the name of this node.

Can be an empty string (e.g. for nodes of type wxXML_TEXT_NODE or wxXML_CDATA_SECTION_NODE).

wxXmlNode* wxXmlNode::GetNext ( ) const

Returns a pointer to the sibling of this node or NULL if there are no siblings.

bool wxXmlNode::GetNoConversion ( ) const

Returns a flag indicating whether encoding conversion is necessary when saving.

The default is false.

You can improve saving efficiency considerably by setting this value.

wxString wxXmlNode::GetNodeContent ( ) const

Returns the content of the first child node of type wxXML_TEXT_NODE or wxXML_CDATA_SECTION_NODE.

This function is very useful since the XML snippet "tagnametagcontent/tagname" is represented by expat with the following tag tree:

wxXML_ELEMENT_NODE name="tagname", content=""

|-- wxXML_TEXT_NODE name="", content="tagcontent"

or eventually:

wxXML_ELEMENT_NODE name="tagname", content=""

|-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"

An empty string is returned if the node has no children of type wxXML_TEXT_NODE or wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty.

wxXmlNode* wxXmlNode::GetParent ( ) const

Returns a pointer to the parent of this node or NULL if this node has no parent.

wxXmlNodeType wxXmlNode::GetType ( ) const

Returns the type of this node.

bool wxXmlNode::HasAttribute ( const wxString & attrName ) const

Returns true if this node has a attribute named attrName.

virtual bool wxXmlNode::InsertChild	(	wxXmlNode *	child,
		wxXmlNode *	followingNode
	)

virtual

Inserts the child node immediately before followingNode in the children list.

Once inserted, the XML tree takes ownership of the new child and there is no need to delete it.

Returns: true if followingNode has been found and the child node has been inserted.

Note: For historical reasons, followingNode may be NULL. In that case, then 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 followingNode).

See also: AddChild(), InsertChildAfter()

virtual bool wxXmlNode::InsertChildAfter	(	wxXmlNode *	child,
		wxXmlNode *	precedingNode
	)

virtual

Inserts the child node immediately after precedingNode in the children list.

Once inserted, the XML tree takes ownership of the new child and there is no need to delete it.

Returns: true if precedingNode has been found and the child node has been inserted.

Parameters

child	The child to insert.
precedingNode	The node to insert child after. As a special case, this can be NULL if this node has no children yet – in that case, child will become this node's only child node.

Since: 2.8.8

See also: InsertChild(), AddChild()

bool wxXmlNode::IsWhitespaceOnly ( ) const

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.

wxXmlNode& wxXmlNode::operator= ( const wxXmlNode & node )

See the copy constructor for more info.

virtual bool wxXmlNode::RemoveChild ( wxXmlNode * child )

virtual

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 responsible for deleting the removed node in order to avoid memory leaks.

void wxXmlNode::SetAttributes ( wxXmlAttribute * attr )

Sets as first attribute the given wxXmlAttribute object.

The caller is responsible for deleting any previously present attributes attached to this node.

void wxXmlNode::SetChildren ( wxXmlNode * child )

Sets as first child the given node.

The caller is responsible for deleting any previously present children node.

void wxXmlNode::SetContent ( const wxString & con )

Sets the content of this node.

void wxXmlNode::SetName ( const wxString & name )

Sets the name of this node.

void wxXmlNode::SetNext ( wxXmlNode * next )

Sets as sibling the given node.

The caller is responsible for deleting any previously present sibling node.

void wxXmlNode::SetNoConversion ( bool noconversion )

Sets a flag to indicate whether encoding conversion is necessary when saving.

The default is false.

You can improve saving efficiency considerably by setting this value.

void wxXmlNode::SetParent ( wxXmlNode * parent )

Sets as parent the given node.

The caller is responsible for deleting any previously present parent node.

void wxXmlNode::SetType ( wxXmlNodeType type )

Sets the type of this node.

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation