X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/fa6a837300efb9d295b889a8308b74537c9d8677..c52b96359b639cda516615f9433d3b20b35443b5:/docs/latex/wx/xmlnode.tex?ds=sidebyside

diff --git a/docs/latex/wx/xmlnode.tex b/docs/latex/wx/xmlnode.tex
index 97d60ffa55..de6b349008 100644
--- 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}.
 
-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
@@ -30,6 +30,10 @@ No base class
 
 <wx/xml/xml.h>
 
+\wxheading{Library}
+
+\helpref{wxXml}{librarieslist}
+
 \wxheading{Constants}
 
 The following are the node types supported by \helpref{wxXmlNode}{wxxmlnode}:
@@ -57,7 +61,7 @@ enum wxXmlNodeType
 
 \wxheading{See also}
 
-\helpref{wxXmlDocument}{wxxmldocument}, \helpref{wxXmlProperty}{wxxmlproperty}
+\helpref{wxXmlDocument}{wxxmldocument}, \helpref{wxXmlAttribute}{wxxmlattribute}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
@@ -65,39 +69,47 @@ enum wxXmlNodeType
 
 \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}
 
-\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{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{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
-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.
+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}
 
-The virtual destructor. Deletes attached children and properties.
+The virtual destructor. Deletes attached children and attributes.
 
 \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.
 
-\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}
 
-\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
@@ -139,6 +151,23 @@ Be aware that for nodes of type \texttt{wxXML\_ELEMENT\_NODE} (the most used nod
 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}
@@ -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.
 
-\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.
 
-\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}
 
@@ -205,11 +235,11 @@ Return a pointer to the first property 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}
 
@@ -220,6 +250,14 @@ If {\it before\_node} is \NULL, then {\it child} is prepended to the list of chi
 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}}
@@ -227,6 +265,8 @@ Returns \true if {\it before\_node} has been found and the {\it child} node has
 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}}
@@ -260,12 +300,12 @@ sibling 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}