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