Applied ref-couting patch.

[wxWidgets.git] / docs / latex / wx / xmlnode.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% 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}
with content="hi").

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}

No base class

\wxheading{Include files}

<wx/xml/xml.h>

\wxheading{Constants}

The following are the node types supported by \helpref{wxXmlNode}{wxxmlnode}:

{\small
\begin{verbatim}
enum wxXmlNodeType
{
    wxXML_ELEMENT_NODE,
    wxXML_ATTRIBUTE_NODE,
    wxXML_TEXT_NODE,
    wxXML_CDATA_SECTION_NODE,
    wxXML_ENTITY_REF_NODE,
    wxXML_ENTITY_NODE,
    wxXML_PI_NODE,
    wxXML_COMMENT_NODE,
    wxXML_DOCUMENT_NODE,
    wxXML_DOCUMENT_TYPE_NODE,
    wxXML_DOCUMENT_FRAG_NODE,
    wxXML_NOTATION_NODE,
    wxXML_HTML_DOCUMENT_NODE
}
\end{verbatim}
}

\wxheading{See also}

\helpref{wxXmlDocument}{wxxmldocument}, \helpref{wxXmlProperty}{wxxmlproperty}


\latexignore{\rtfignore{\wxheading{Members}}}


\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}}

\wxheading{Parameters}

\docparam{parent}{The parent node. Can be \NULL.}
\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
the node.}

\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
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.


\membersection{wxXmlNode::\destruct{wxXmlNode}}\label{wxxmlnodedtor}

\func{}{\destruct{wxXmlNode}}{\void}

The virtual destructor. Deletes attached children and properties.

\membersection{wxXmlNode::AddChild}\label{wxxmlnodeaddchild}

\func{void}{AddChild}{\param{wxXmlNode* }{child}}

Adds the given node as child of this node. To attach a second children to this node, use the
\helpref{SetNext()}{wxxmlnodesetnext} function of the {\it child} node.

\membersection{wxXmlNode::AddProperty}\label{wxxmlnodeaddproperty}

\func{void}{AddProperty}{\param{const wxString\& }{name}, \param{const wxString\& }{value}}

Appends a property with given {\it name} and {\it value} to the list of properties for this node.

\func{void}{AddProperty}{\param{wxXmlProperty* }{prop}}

Appends the given property to the list of properties for this node.

\membersection{wxXmlNode::DeleteProperty}\label{wxxmlnodedeleteproperty}

\func{bool}{DeleteProperty}{\param{const wxString\& }{name}}

Removes the first properties which has the given {\it name} from the list of properties for this node.

\membersection{wxXmlNode::GetChildren}\label{wxxmlnodegetchildren}

\constfunc{wxXmlNode*}{GetChildren}{\void}

Returns the first child of this node.
To get a pointer to the second child of this node (if it does exist), use the
\helpref{GetNext()}{wxxmlnodegetnext} function on the returned value.

\membersection{wxXmlNode::GetContent}\label{wxxmlnodegetcontent}

\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{wxString}{GetName}{\void}

Returns the name of this node. Can be an empty string (e.g. for nodes of type {\tt wxXML\_TEXT\_NODE} or {\tt wxXML\_CDATA\_SECTION\_NODE}).

\membersection{wxXmlNode::GetNext}\label{wxxmlnodegetnext}

\constfunc{wxXmlNode*}{GetNext}{\void}

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.

\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.

\constfunc{wxString}{GetPropVal}{\param{const wxString\& }{propName}, \param{const wxString\& }{defaultVal}}

Returns the value of the property named {\it propName} if it does exist.
If it does not exist, the {\it defaultVal} is returned.

\membersection{wxXmlNode::GetProperties}\label{wxxmlnodegetproperties}

\constfunc{wxXmlProperty *}{GetProperties}{\void}

Return a pointer to the first property of this node.

\membersection{wxXmlNode::GetType}\label{wxxmlnodegettype}

\constfunc{wxXmlNodeType}{GetType}{\void}

Returns the type of this node.


\membersection{wxXmlNode::HasProp}\label{wxxmlnodehasprop}

\constfunc{bool}{HasProp}{\param{const wxString\& }{propName}}

Returns \true if this node has a property named {\it propName}.

\membersection{wxXmlNode::InsertChild}\label{wxxmlnodeinsertchild}

\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}

\func{bool}{RemoveChild}{\param{wxXmlNode* }{child}}

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.

\membersection{wxXmlNode::SetChildren}\label{wxxmlnodesetchildren}

\func{void}{SetChildren}{\param{wxXmlNode* }{child}}

Sets as first child the given node. The caller is responsible to delete any previously present
children node.

\membersection{wxXmlNode::SetContent}\label{wxxmlnodesetcontent}

\func{void}{SetContent}{\param{const wxString\& }{con}}

Sets the content of this node.

\membersection{wxXmlNode::SetName}\label{wxxmlnodesetname}

\func{void}{SetName}{\param{const wxString\& }{name}}

Sets the name of this node.

\membersection{wxXmlNode::SetNext}\label{wxxmlnodesetnext}

\func{void}{SetNext}{\param{wxXmlNode* }{next}}

Sets as sibling the given node. The caller is responsible to delete any previously present
sibling node.

\membersection{wxXmlNode::SetParent}\label{wxxmlnodesetparent}

\func{void}{SetParent}{\param{wxXmlNode* }{parent}}

Sets as parent the given node. The caller is responsible to delete any previously present
parent node.

\membersection{wxXmlNode::SetProperties}\label{wxxmlnodesetproperties}

\func{void}{SetProperties}{\param{wxXmlProperty* }{prop}}

Sets as first property the given wxXmlProperty object.
The caller is responsible to delete any previously present properties attached to this node.

\membersection{wxXmlNode::SetType}\label{wxxmlnodesettype}

\func{void}{SetType}{\param{wxXmlNodeType }{type}}

Sets the type of this node.

\membersection{wxXmlNode::operator=}\label{wxxmlnodeoperatorassign}

\func{wxXmlNode\&}{operator=}{\param{const wxXmlNode\& }{node}}

See the copy constructor for more info.