Add empty EnableCloseButton() into wxTLW base class.

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

diff --git a/docs/latex/wx/xmlnode.tex b/docs/latex/wx/xmlnode.tex
index 19c62b2423a69ff102eb157f8b117df051acdb78..2e00889722d3e6bcb5ac680a980c1f389d25b7e4 100644 (file)
--- a/docs/latex/wx/xmlnode.tex
+++ b/docs/latex/wx/xmlnode.tex
@@ -1,3 +1,13 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% 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}.
 \section{\class{wxXmlNode}}\label{wxxmlnode}
 
 Represents a node in an XML document. See \helpref{wxXmlDocument}{wxxmldocument}.


@@ -8,8 +18,8 @@ properties are irrelevant) and {\tt wxXML\_ELEMENT\_NODE} (e.g. in {\tt <title>h
 an element with name="title", irrelevant content and one child ({\tt wxXML\_TEXT\_NODE}
 with content="hi").
 
 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{Derived from}


@@ -22,7 +32,7 @@ No base class
 
 \wxheading{Constants}
 
 
 \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}
 
 {\small
 \begin{verbatim}


@@ -56,23 +66,23 @@ enum wxXmlNodeType
 \membersection{wxXmlNode::wxXmlNode}\label{wxxmlnodewxxmlnode}
 
 
 \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}
 
 
 \wxheading{Parameters}
 

-\docparam{parent}{The parent node. Can be NULL.}
+\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{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
+\docparam{props}{If not \NULL, this wxXmlProperty object and its eventual siblings are attached to

 the node.}
 the node.}

-\docparam{next}{If not NULL, this node and its eventual siblings are attached to
+\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
 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
+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.
 after using copy ctor and are never unmodified by operator=.
 
 On the other hand, it DOES copy children and properties.


@@ -125,6 +135,43 @@ To get a pointer to the second child of this node (if it does exist), use the
 \constfunc{wxString}{GetContent}{\void}
 
 Returns the content of this node. Can be an empty string.
 \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}
 
 
 \membersection{wxXmlNode::GetName}\label{wxxmlnodegetname}
 


@@ -136,20 +183,20 @@ Returns the name of this node. Can be an empty string (e.g. for nodes of type {\
 
 \constfunc{wxXmlNode*}{GetNext}{\void}
 
 
 \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}
 
 
 \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.
 
 \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}}
 
 
 \constfunc{wxString}{GetPropVal}{\param{const wxString\& }{propName}, \param{const wxString\& }{defaultVal}}
 


@@ -158,7 +205,7 @@ If it does not exist, the {\it defaultVal} is returned.
 
 \membersection{wxXmlNode::GetProperties}\label{wxxmlnodegetproperties}
 
 
 \membersection{wxXmlNode::GetProperties}\label{wxxmlnodegetproperties}
 

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

 
 Return a pointer to the first property of this node.
 
 
 Return a pointer to the first property of this node.
 


@@ -177,9 +224,20 @@ Returns \true if this node has a property named {\it propName}.
 
 \membersection{wxXmlNode::InsertChild}\label{wxxmlnodeinsertchild}
 
 
 \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.
 
 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}
 
 
 \membersection{wxXmlNode::RemoveChild}\label{wxxmlnoderemovechild}
 


@@ -188,6 +246,8 @@ Inserts the {\it child} node after {\it before\_node} in the children list.
 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.
 
 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::SetChildren}\label{wxxmlnodesetchildren}
 
 \func{void}{SetChildren}{\param{wxXmlNode* }{child}}


@@ -236,7 +296,7 @@ Sets the type of this node.
 
 \membersection{wxXmlNode::operator=}\label{wxxmlnodeoperatorassign}
 
 
 \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.
 
 
 See the copy constructor for more info.