1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: xmlnode.tex 3%% Purpose: wxXmlNode documentation 4%% Author: Francesco Montorsi 5%% Created: 2006-04-18 6%% RCS-ID: $Id: xmlnode.tex 52976 2008-04-02 10:06:54Z VS $ 7%% Copyright: (c) 2006 Francesco Montorsi 8%% License: wxWindows license 9%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 10 11\section{\class{wxXmlNode}}\label{wxxmlnode} 12 13Represents a node in an XML document. See \helpref{wxXmlDocument}{wxxmldocument}. 14 15Node has a name and may have content 16and properties. Most common node types are {\tt wxXML\_TEXT\_NODE} (name and 17properties are irrelevant) and {\tt wxXML\_ELEMENT\_NODE} (e.g. in {\tt <title>hi</title>} there is 18an element with name="title", irrelevant content and one child ({\tt wxXML\_TEXT\_NODE} 19with content="hi"). 20 21If \texttt{wxUSE\_UNICODE} is 0, all strings are encoded in the encoding given to 22\helpref{wxXmlDocument::Load}{wxxmldocumentload} (default is UTF-8). 23 24 25\wxheading{Derived from} 26 27No base class 28 29\wxheading{Include files} 30 31<wx/xml/xml.h> 32 33\wxheading{Constants} 34 35The following are the node types supported by \helpref{wxXmlNode}{wxxmlnode}: 36 37{\small 38\begin{verbatim} 39enum wxXmlNodeType 40{ 41 wxXML_ELEMENT_NODE, 42 wxXML_ATTRIBUTE_NODE, 43 wxXML_TEXT_NODE, 44 wxXML_CDATA_SECTION_NODE, 45 wxXML_ENTITY_REF_NODE, 46 wxXML_ENTITY_NODE, 47 wxXML_PI_NODE, 48 wxXML_COMMENT_NODE, 49 wxXML_DOCUMENT_NODE, 50 wxXML_DOCUMENT_TYPE_NODE, 51 wxXML_DOCUMENT_FRAG_NODE, 52 wxXML_NOTATION_NODE, 53 wxXML_HTML_DOCUMENT_NODE 54} 55\end{verbatim} 56} 57 58\wxheading{See also} 59 60\helpref{wxXmlDocument}{wxxmldocument}, \helpref{wxXmlProperty}{wxxmlproperty} 61 62 63\latexignore{\rtfignore{\wxheading{Members}}} 64 65 66\membersection{wxXmlNode::wxXmlNode}\label{wxxmlnodewxxmlnode} 67 68 69\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}} 70 71\wxheading{Parameters} 72 73\docparam{parent}{The parent node. Can be \NULL.} 74\docparam{type}{One of the wxXmlNodeType enumeration value.} 75\docparam{name}{The name of the node. This is the string which appears between angular brackets.} 76\docparam{content}{The content of the node. Only meaningful when {\it type} is {\tt wxXML\_TEXT\_NODE} or {\tt wxXML\_CDATA\_SECTION\_NODE}.} 77\docparam{props}{If not \NULL, this wxXmlProperty object and its eventual siblings are attached to 78the node.} 79\docparam{next}{If not \NULL, this node and its eventual siblings are attached to 80the node.} 81 82\func{}{wxXmlNode}{\param{const wxXmlNode\& }{node}} 83 84Copy constructor. Note that this does NOT copy syblings 85and parent pointer, i.e. \helpref{GetParent()}{wxxmlnodegetparent} and \helpref{GetNext()}{wxxmlnodegetnext} will return \NULL 86after using copy ctor and are never unmodified by operator=. 87 88On the other hand, it DOES copy children and properties. 89 90 91\func{}{wxXmlNode}{\param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}} 92 93A simplified version of the first constructor form. 94 95 96\membersection{wxXmlNode::\destruct{wxXmlNode}}\label{wxxmlnodedtor} 97 98\func{}{\destruct{wxXmlNode}}{\void} 99 100The virtual destructor. Deletes attached children and properties. 101 102\membersection{wxXmlNode::AddChild}\label{wxxmlnodeaddchild} 103 104\func{void}{AddChild}{\param{wxXmlNode* }{child}} 105 106Adds the given node as child of this node. To attach a second children to this node, use the 107\helpref{SetNext()}{wxxmlnodesetnext} function of the {\it child} node. 108 109\membersection{wxXmlNode::AddProperty}\label{wxxmlnodeaddproperty} 110 111\func{void}{AddProperty}{\param{const wxString\& }{name}, \param{const wxString\& }{value}} 112 113Appends a property with given {\it name} and {\it value} to the list of properties for this node. 114 115\func{void}{AddProperty}{\param{wxXmlProperty* }{prop}} 116 117Appends the given property to the list of properties for this node. 118 119\membersection{wxXmlNode::DeleteProperty}\label{wxxmlnodedeleteproperty} 120 121\func{bool}{DeleteProperty}{\param{const wxString\& }{name}} 122 123Removes the first properties which has the given {\it name} from the list of properties for this node. 124 125\membersection{wxXmlNode::GetChildren}\label{wxxmlnodegetchildren} 126 127\constfunc{wxXmlNode*}{GetChildren}{\void} 128 129Returns the first child of this node. 130To get a pointer to the second child of this node (if it does exist), use the 131\helpref{GetNext()}{wxxmlnodegetnext} function on the returned value. 132 133\membersection{wxXmlNode::GetContent}\label{wxxmlnodegetcontent} 134 135\constfunc{wxString}{GetContent}{\void} 136 137Returns the content of this node. Can be an empty string. 138Be aware that for nodes of type \texttt{wxXML\_ELEMENT\_NODE} (the most used node type) the 139content is an empty string. See \helpref{GetNodeContent()}{wxxmlnodegetnodecontent} for more details. 140 141 142\membersection{wxXmlNode::GetDepth}\label{wxxmlnodegetdepth} 143 144\constfunc{int}{GetDepth}{\param{wxXmlNode* }{grandparent = NULL}} 145 146Returns the number of nodes which separe this node from {\tt grandparent}. 147 148This function searches only the parents of this node until it finds {\tt grandparent} 149or the \NULL node (which is the parent of non-linked nodes or the parent of a 150\helpref{wxXmlDocument}{wxxmldocument}'s root node). 151 152 153\membersection{wxXmlNode::GetNodeContent}\label{wxxmlnodegetnodecontent} 154 155\constfunc{wxString}{GetNodeContent}{\void} 156 157Returns the content of the first child node of type \texttt{wxXML\_TEXT\_NODE} or \texttt{wxXML\_CDATA\_SECTION\_NODE}. 158This function is very useful since the XML snippet \texttt{``<tagname>tagcontent</tagname>"} is represented by 159expat with the following tag tree: 160 161\begin{verbatim} 162wxXML_ENTITY_NODE name="tagname", content="" 163|-- wxXML_TEXT_NODE name="", content="tagcontent" 164\end{verbatim} 165 166or eventually: 167 168\begin{verbatim} 169wxXML_ENTITY_NODE name="tagname", content="" 170|-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent" 171\end{verbatim} 172 173An 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. 174 175 176\membersection{wxXmlNode::GetName}\label{wxxmlnodegetname} 177 178\constfunc{wxString}{GetName}{\void} 179 180Returns 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}). 181 182\membersection{wxXmlNode::GetNext}\label{wxxmlnodegetnext} 183 184\constfunc{wxXmlNode*}{GetNext}{\void} 185 186Returns a pointer to the sibling of this node or \NULL if there are no siblings. 187 188\membersection{wxXmlNode::GetParent}\label{wxxmlnodegetparent} 189 190\constfunc{wxXmlNode*}{GetParent}{\void} 191 192Returns a pointer to the parent of this node or \NULL if this node has no parent. 193 194\membersection{wxXmlNode::GetPropVal}\label{wxxmlnodegetpropval} 195 196\constfunc{bool}{GetPropVal}{\param{const wxString\& }{propName}, \param{wxString* }{value}} 197 198Returns \true if a property named {\it propName} could be found. 199The value of that property is saved in \arg{value} (which must not be \NULL). 200 201\constfunc{wxString}{GetPropVal}{\param{const wxString\& }{propName}, \param{const wxString\& }{defaultVal}} 202 203Returns the value of the property named {\it propName} if it does exist. 204If it does not exist, the {\it defaultVal} is returned. 205 206\membersection{wxXmlNode::GetProperties}\label{wxxmlnodegetproperties} 207 208\constfunc{wxXmlProperty *}{GetProperties}{\void} 209 210Return a pointer to the first property of this node. 211 212\membersection{wxXmlNode::GetType}\label{wxxmlnodegettype} 213 214\constfunc{wxXmlNodeType}{GetType}{\void} 215 216Returns the type of this node. 217 218 219\membersection{wxXmlNode::HasProp}\label{wxxmlnodehasprop} 220 221\constfunc{bool}{HasProp}{\param{const wxString\& }{propName}} 222 223Returns \true if this node has a property named {\it propName}. 224 225\membersection{wxXmlNode::InsertChild}\label{wxxmlnodeinsertchild} 226 227\func{bool}{InsertChild}{\param{wxXmlNode* }{child}, \param{wxXmlNode* }{followingNode}} 228 229Inserts the {\it child} node immediately before {\it followingNode} in the 230children list. If {\it followingNode} is \NULL, then {\it child} is prepended 231to the list of children and becomes the first child of this node. Returns 232\true if {\it followingNode} has been found and the {\it child} node has been 233inserted. 234 235\membersection{wxXmlNode::InsertChildAfter}\label{wxxmlnodeinsertchildafter} 236 237\func{bool}{InsertChildAfter}{\param{wxXmlNode* }{child}, \param{wxXmlNode* }{precedingNode}} 238 239Inserts the \arg{child} node immediately after \arg{precedingNode} in the 240children list. Returns \true if \arg{precedingNode} has been found and the 241\arg{child} node has been inserted. 242 243\wxheading{Parameters} 244 245\docparam{child}{Node to insert.} 246\docparam{precedingNode}{The node to insert \arg{child} after. 247 As a special case, this can be \NULL if this node has no children yet -- 248 in that case, \arg{child} will become this node's only child node.} 249 250\newsince{2.8.8} 251 252\membersection{wxXmlNode::IsWhitespaceOnly}\label{wxxmlnodecontainsiswhitespaceonly} 253 254\constfunc{bool}{IsWhitespaceOnly}{\void} 255 256Returns \true if the content of this node is a string containing only whitespaces (spaces, 257tabs, new lines, etc). Note that this function is locale-independent since the parsing of XML 258documents must always produce the exact same tree regardless of the locale it runs under. 259 260\membersection{wxXmlNode::RemoveChild}\label{wxxmlnoderemovechild} 261 262\func{bool}{RemoveChild}{\param{wxXmlNode* }{child}} 263 264Removes the given node from the children list. Returns \true if the node was found and removed 265or \false if the node could not be found. 266 267Note that the caller is reponsible for deleting the removed node in order to avoid memory leaks. 268 269\membersection{wxXmlNode::SetChildren}\label{wxxmlnodesetchildren} 270 271\func{void}{SetChildren}{\param{wxXmlNode* }{child}} 272 273Sets as first child the given node. The caller is responsible to delete any previously present 274children node. 275 276\membersection{wxXmlNode::SetContent}\label{wxxmlnodesetcontent} 277 278\func{void}{SetContent}{\param{const wxString\& }{con}} 279 280Sets the content of this node. 281 282\membersection{wxXmlNode::SetName}\label{wxxmlnodesetname} 283 284\func{void}{SetName}{\param{const wxString\& }{name}} 285 286Sets the name of this node. 287 288\membersection{wxXmlNode::SetNext}\label{wxxmlnodesetnext} 289 290\func{void}{SetNext}{\param{wxXmlNode* }{next}} 291 292Sets as sibling the given node. The caller is responsible to delete any previously present 293sibling node. 294 295\membersection{wxXmlNode::SetParent}\label{wxxmlnodesetparent} 296 297\func{void}{SetParent}{\param{wxXmlNode* }{parent}} 298 299Sets as parent the given node. The caller is responsible to delete any previously present 300parent node. 301 302\membersection{wxXmlNode::SetProperties}\label{wxxmlnodesetproperties} 303 304\func{void}{SetProperties}{\param{wxXmlProperty* }{prop}} 305 306Sets as first property the given wxXmlProperty object. 307The caller is responsible to delete any previously present properties attached to this node. 308 309\membersection{wxXmlNode::SetType}\label{wxxmlnodesettype} 310 311\func{void}{SetType}{\param{wxXmlNodeType }{type}} 312 313Sets the type of this node. 314 315\membersection{wxXmlNode::operator=}\label{wxxmlnodeoperatorassign} 316 317\func{wxXmlNode\&}{operator=}{\param{const wxXmlNode\& }{node}} 318 319See the copy constructor for more info. 320 321