+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% Name: xmlnode.tex
+%% Purpose: wxXmlNode documentation
+%% Author: Francesco Montorsi
+%% Created: 2006-04-18
+%% RCS-ID: $Id$
+%% Copyright: (c) 2006 Francesco Montorsi
+%% License: wxWindows license
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
\section{\class{wxXmlNode}}\label{wxxmlnode}
Represents a node in an XML document. See \helpref{wxXmlDocument}{wxxmldocument}.
-Node has a name and may have content
-and properties. Most common node types are {\tt wxXML\_TEXT\_NODE} (name and
-properties are irrelevant) and {\tt wxXML\_ELEMENT\_NODE} (e.g. in {\tt <title>hi</title>} there is
-an element with name="title", irrelevant content and one child ({\tt wxXML\_TEXT\_NODE}
+Node has a name and may have content and properties. Most common node types are
+{\tt wxXML\_TEXT\_NODE} (name and properties are irrelevant) and
+{\tt wxXML\_ELEMENT\_NODE} (e.g. in {\tt <title>hi</title>} there is an element
+with name="title", irrelevant content and one child ({\tt wxXML\_TEXT\_NODE}
with content="hi").
-If wxUSE\_UNICODE is 0, all strings are encoded in the encoding given to Load
-(default is UTF-8).
+If \texttt{wxUSE\_UNICODE} is 0, all strings are encoded in the encoding given to
+\helpref{wxXmlDocument::Load}{wxxmldocumentload} (default is UTF-8).
\wxheading{Derived from}
\wxheading{Constants}
-The following are the node types supported by wxXmlNode:
+The following are the node types supported by \helpref{wxXmlNode}{wxxmlnode}:
{\small
\begin{verbatim}
\membersection{wxXmlNode::wxXmlNode}\label{wxxmlnodewxxmlnode}
-
-\func{}{wxXmlNode}{\param{wxXmlNode* }{parent}, \param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}, \param{wxXmlProperty* }{props = NULL}, \param{wxXmlNode* }{next = NULL}}
+\func{}{wxXmlNode}{\param{wxXmlNode* }{parent}, \param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}, \param{wxXmlProperty* }{props = \NULL}, \param{wxXmlNode* }{next = \NULL}}
\wxheading{Parameters}
-\docparam{parent}{The parent node. Can be NULL.}
+\docparam{parent}{The parent node to which append this node instance.
+If this argument is \NULL this new node will be {\it floating} and it can be appended later to
+another one using the \helpref{AddChild}{wxxmlnodeaddchild} or \helpref{InsertChild}{wxxmlnodeinsertchild}
+functions. Otherwise the child is already added to the XML tree by this
+constructor and it shouldn't be done again.}
\docparam{type}{One of the wxXmlNodeType enumeration value.}
\docparam{name}{The name of the node. This is the string which appears between angular brackets.}
-\docparam{content}{The content of the node. Only meaningful when {\it type} is {\tt wxXML\_TEXT\_NODE} or {\tt wxXML\_CDATA\_SECTION\_NODE}.}
-\docparam{props}{If not NULL, this wxXmlProperty object and its eventual siblings are attached to
-the node.}
-\docparam{next}{If not NULL, this node and its eventual siblings are attached to
+\docparam{content}{The content of the node. Only meaningful when {\it type} is
+{\tt wxXML\_TEXT\_NODE} or {\tt wxXML\_CDATA\_SECTION\_NODE}.}
+\docparam{props}{If not \NULL, this \helpref{wxXmlProperty}{wxxmlproperty} object
+and its eventual siblings are attached to the node.}
+\docparam{next}{If not \NULL, this node and its eventual siblings are attached to
the node.}
+Creates this XML node and eventually insert it into an existing XML tree.
+
\func{}{wxXmlNode}{\param{const wxXmlNode\& }{node}}
Copy constructor. Note that this does NOT copy syblings
-and parent pointer, i.e. \helpref{GetParent()}{wxxmlnodegetparent} and \helpref{GetNext()}{wxxmlnodegetnext} will return NULL
+and parent pointer, i.e. \helpref{GetParent()}{wxxmlnodegetparent} and
+\helpref{GetNext()}{wxxmlnodegetnext} will return \NULL
after using copy ctor and are never unmodified by operator=.
On the other hand, it DOES copy children and properties.
\func{}{wxXmlNode}{\param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}}
-A simplified version of the first constructor form.
+A simplified version of the first constructor form, assuming a \NULL parent.
\membersection{wxXmlNode::\destruct{wxXmlNode}}\label{wxxmlnodedtor}
\constfunc{wxString}{GetContent}{\void}
Returns the content of this node. Can be an empty string.
+Be aware that for nodes of type \texttt{wxXML\_ELEMENT\_NODE} (the most used node type) the
+content is an empty string. See \helpref{GetNodeContent()}{wxxmlnodegetnodecontent} for more details.
+
+
+\membersection{wxXmlNode::GetDepth}\label{wxxmlnodegetdepth}
+
+\constfunc{int}{GetDepth}{\param{wxXmlNode* }{grandparent = NULL}}
+
+Returns the number of nodes which separe this node from {\tt grandparent}.
+
+This function searches only the parents of this node until it finds {\tt grandparent}
+or the \NULL node (which is the parent of non-linked nodes or the parent of a
+\helpref{wxXmlDocument}{wxxmldocument}'s root node).
+
+
+\membersection{wxXmlNode::GetNodeContent}\label{wxxmlnodegetnodecontent}
+
+\constfunc{wxString}{GetNodeContent}{\void}
+
+Returns the content of the first child node of type \texttt{wxXML\_TEXT\_NODE} or \texttt{wxXML\_CDATA\_SECTION\_NODE}.
+This function is very useful since the XML snippet \texttt{``<tagname>tagcontent</tagname>"} is represented by
+expat with the following tag tree:
+
+\begin{verbatim}
+wxXML_ENTITY_NODE name="tagname", content=""
+|-- wxXML_TEXT_NODE name="", content="tagcontent"
+\end{verbatim}
+
+or eventually:
+
+\begin{verbatim}
+wxXML_ENTITY_NODE name="tagname", content=""
+|-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
+\end{verbatim}
+
+An empty string is returned if the node has no children of type \texttt{wxXML\_TEXT\_NODE} or \texttt{wxXML\_CDATA\_SECTION\_NODE}, or if the content of the first child of such types is empty.
+
\membersection{wxXmlNode::GetName}\label{wxxmlnodegetname}
\constfunc{wxXmlNode*}{GetNext}{\void}
-Returns a pointer to the sibling of this node or NULL if there are no siblings.
+Returns a pointer to the sibling of this node or \NULL if there are no siblings.
\membersection{wxXmlNode::GetParent}\label{wxxmlnodegetparent}
\constfunc{wxXmlNode*}{GetParent}{\void}
-Returns a pointer to the parent of this node or NULL if this node has no parent.
+Returns a pointer to the parent of this node or \NULL if this node has no parent.
\membersection{wxXmlNode::GetPropVal}\label{wxxmlnodegetpropval}
\constfunc{bool}{GetPropVal}{\param{const wxString\& }{propName}, \param{wxString* }{value}}
Returns \true if a property named {\it propName} could be found.
-If the {\it value} pointer is not NULL, the value of that property is saved there.
+If the {\it value} pointer is not \NULL, the value of that property is saved there.
\constfunc{wxString}{GetPropVal}{\param{const wxString\& }{propName}, \param{const wxString\& }{defaultVal}}
\membersection{wxXmlNode::GetProperties}\label{wxxmlnodegetproperties}
-\constfunc{wxXmlProperty*}{GetProperties}{\void}
+\constfunc{wxXmlProperty *}{GetProperties}{\void}
Return a pointer to the first property of this node.
\membersection{wxXmlNode::InsertChild}\label{wxxmlnodeinsertchild}
-\func{void}{InsertChild}{\param{wxXmlNode* }{child}, \param{wxXmlNode* }{before\_node}}
+\func{bool}{InsertChild}{\param{wxXmlNode* }{child}, \param{wxXmlNode* }{before\_node}}
Inserts the {\it child} node after {\it before\_node} in the children list.
+If {\it before\_node} is \NULL, then {\it child} is prepended to the list of children and
+becomes the first child of this node.
+Returns \true if {\it before\_node} has been found and the {\it child} node has been inserted.
+
+\membersection{wxXmlNode::IsWhitespaceOnly}\label{wxxmlnodecontainsiswhitespaceonly}
+
+\constfunc{bool}{IsWhitespaceOnly}{\void}
+
+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.
\membersection{wxXmlNode::RemoveChild}\label{wxxmlnoderemovechild}
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.
+
\membersection{wxXmlNode::SetChildren}\label{wxxmlnodesetchildren}
\func{void}{SetChildren}{\param{wxXmlNode* }{child}}
\membersection{wxXmlNode::operator=}\label{wxxmlnodeoperatorassign}
-\func{wxXmlNode\& operator}{operator=}{\param{const wxXmlNode\& }{node}}
+\func{wxXmlNode\&}{operator=}{\param{const wxXmlNode\& }{node}}
See the copy constructor for more info.
projects / wxWidgets.git / blobdiff