compilation fix for wxUSE_STL==1 in DoGetSibling()

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

diff --git a/docs/latex/wx/xmlnode.tex b/docs/latex/wx/xmlnode.tex
index a7e693e43bf90b7c547c3d9f5acd20192cb1380e..de6b34900832c1df5ec8d5129dc35497d00771ff 100644 (file)
--- a/docs/latex/wx/xmlnode.tex
+++ b/docs/latex/wx/xmlnode.tex
@@ -12,10 +12,10 @@
 
 Represents a node in an XML document. See \helpref{wxXmlDocument}{wxxmldocument}.
 
 
 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 attributes. Most common node types are 
+{\tt wxXML\_TEXT\_NODE} (name and attributes 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
 with content="hi").
 
 If \texttt{wxUSE\_UNICODE} is 0, all strings are encoded in the encoding given to


@@ -30,6 +30,10 @@ No base class
 
 <wx/xml/xml.h>
 
 
 <wx/xml/xml.h>
 

+\wxheading{Library}
+
+\helpref{wxXml}{librarieslist}
+

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


@@ -57,7 +61,7 @@ enum wxXmlNodeType
 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxXmlDocument}{wxxmldocument}, \helpref{wxXmlProperty}{wxxmlproperty}
+\helpref{wxXmlDocument}{wxxmldocument}, \helpref{wxXmlAttribute}{wxxmlattribute}

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


@@ -65,39 +69,47 @@ 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{wxXmlAttribute* }{attrs = \NULL}, \param{wxXmlNode* }{next = \NULL}, \param{int }{lineNo = -1}}

 
 \wxheading{Parameters}
 
 
 \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{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{content}{The content of the node. Only meaningful when {\it type} is 
+{\tt wxXML\_TEXT\_NODE} or {\tt wxXML\_CDATA\_SECTION\_NODE}.}
+\docparam{attrs}{If not \NULL, this \helpref{wxXmlAttribute}{wxxmlattribute} 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.}
 \docparam{next}{If not \NULL, this node and its eventual siblings are attached to
 the node.}

+\docparam{lineNo}{Number of line this node was present at in input file or -1.}
+
+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
 
 \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=.
 
 after using copy ctor and are never unmodified by operator=.
 

-On the other hand, it DOES copy children and properties.
+On the other hand, it DOES copy children and attributes.

 
 
 
 

-\func{}{wxXmlNode}{\param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}}
+\func{}{wxXmlNode}{\param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}, \param{int }{lineNo = -1}}

 
 

-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}
 
 \func{}{\destruct{wxXmlNode}}{\void}
 
 
 
 \membersection{wxXmlNode::\destruct{wxXmlNode}}\label{wxxmlnodedtor}
 
 \func{}{\destruct{wxXmlNode}}{\void}
 

-The virtual destructor. Deletes attached children and properties.
+The virtual destructor. Deletes attached children and attributes.

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


@@ -106,25 +118,25 @@ The virtual destructor. Deletes attached children and properties.
 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.
 
 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}
+\membersection{wxXmlNode::AddAttribute}\label{wxxmlnodeaddattribute}

 
 

-\func{void}{AddProperty}{\param{const wxString\& }{name}, \param{const wxString\& }{value}}
+\func{void}{AddAttribute}{\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.
+Appends a attribute with given {\it name} and {\it value} to the list of attributes for this node.

 
 

-\func{void}{AddProperty}{\param{wxXmlProperty* }{prop}}
+\func{void}{AddAttribute}{\param{wxXmlAttribute* }{attr}}

 
 

-Appends the given property to the list of properties for this node.
+Appends given attribute to the list of attributes for this node.

 
 

-\membersection{wxXmlNode::DeleteProperty}\label{wxxmlnodedeleteproperty}
+\membersection{wxXmlNode::DeleteAttribute}\label{wxxmlnodedeleteattribute}

 
 

-\func{bool}{DeleteProperty}{\param{const wxString\& }{name}}
+\func{bool}{DeleteAttribute}{\param{const wxString\& }{name}}

 
 

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

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

-\constfunc{wxXmlNode*}{GetChildren}{\param{void}{}}
+\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
 
 Returns the first child of this node.
 To get a pointer to the second child of this node (if it does exist), use the


@@ -135,15 +147,32 @@ 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
+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.
 
 
 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::GetLineNumber}\label{wxxmlnodegetlinenumber}
+
+\constfunc{int}{GetLineNumber}{\void}
+
+Returns line number of the node in the input XML file or -1 if it is unknown.
+
+

 \membersection{wxXmlNode::GetNodeContent}\label{wxxmlnodegetnodecontent}
 
 \constfunc{wxString}{GetNodeContent}{\void}
 
 \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}.
+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:
 
 This function is very useful since the XML snippet \texttt{``<tagname>tagcontent</tagname>"} is represented by
 expat with the following tag tree:
 


@@ -159,7 +188,7 @@ wxXML_ENTITY_NODE name="tagname", content=""
 |-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
 \end{verbatim}
 
 |-- 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.
+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}


@@ -180,23 +209,24 @@ Returns a pointer to the sibling of this node or \NULL if there are no siblings.
 
 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}
+\membersection{wxXmlNode::GetAttribute}\label{wxxmlnodegetattribute}

 
 

-\constfunc{bool}{GetPropVal}{\param{const wxString\& }{propName}, \param{wxString* }{value}}
+\constfunc{bool}{GetAttribute}{\param{const wxString\& }{attrName}, \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.
+Returns \true if a attribute named {\it attrName} could be found.
+The value of that attribute is saved in \arg{value} (which
+must not be \NULL).

 
 

-\constfunc{wxString}{GetPropVal}{\param{const wxString\& }{propName}, \param{const wxString\& }{defaultVal}}
+\constfunc{wxString}{GetAttribute}{\param{const wxString\& }{attrName}, \param{const wxString\& }{defaultVal}}

 
 

-Returns the value of the property named {\it propName} if it does exist.
+Returns the value of the attribute named {\it attrName} if it does exist.

 If it does not exist, the {\it defaultVal} is returned.
 
 If it does not exist, the {\it defaultVal} is returned.
 

-\membersection{wxXmlNode::GetProperties}\label{wxxmlnodegetproperties}
+\membersection{wxXmlNode::GetAttributes}\label{wxxmlnodegetattributes}

 
 

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

 
 

-Return a pointer to the first property of this node.
+Return a pointer to the first attribute of this node.

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


@@ -205,17 +235,28 @@ Return a pointer to the first property of this node.
 Returns the type of this node.
 
 
 Returns the type of this node.
 
 

-\membersection{wxXmlNode::HasProp}\label{wxxmlnodehasprop}
+\membersection{wxXmlNode::HasAttribute}\label{wxxmlnodehasattribute}

 
 

-\constfunc{bool}{HasProp}{\param{const wxString\& }{propName}}
+\constfunc{bool}{HasAttribute}{\param{const wxString\& }{attrName}}

 
 

-Returns \true if this node has a property named {\it propName}.
+Returns \true if this node has a attribute named {\it attrName}.

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


@@ -224,6 +265,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}}


@@ -257,12 +300,12 @@ sibling node.
 Sets as parent the given node. The caller is responsible to delete any previously present
 parent node.
 
 Sets as parent the given node. The caller is responsible to delete any previously present
 parent node.
 

-\membersection{wxXmlNode::SetProperties}\label{wxxmlnodesetproperties}
+\membersection{wxXmlNode::SetAttributes}\label{wxxmlnodesetattributes}

 
 

-\func{void}{SetProperties}{\param{wxXmlProperty* }{prop}}
+\func{void}{SetAttributes}{\param{wxXmlAttribute* }{attr}}

 
 

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

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