]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/xmlnode.tex
Added newline for PDF RTF
[wxWidgets.git] / docs / latex / wx / xmlnode.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: xmlnode.tex
3 %% Purpose: wxXmlNode documentation
4 %% Author: Francesco Montorsi
5 %% Created: 2006-04-18
6 %% RCS-ID: $Id$
7 %% Copyright: (c) 2006 Francesco Montorsi
8 %% License: wxWindows license
9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10
11 \section{\class{wxXmlNode}}\label{wxxmlnode}
12
13 Represents a node in an XML document. See \helpref{wxXmlDocument}{wxxmldocument}.
14
15 Node has a name and may have content
16 and properties. Most common node types are {\tt wxXML\_TEXT\_NODE} (name and
17 properties are irrelevant) and {\tt wxXML\_ELEMENT\_NODE} (e.g. in {\tt <title>hi</title>} there is
18 an element with name="title", irrelevant content and one child ({\tt wxXML\_TEXT\_NODE}
19 with content="hi").
20
21 If \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
27 No base class
28
29 \wxheading{Include files}
30
31 <wx/xml/xml.h>
32
33 \wxheading{Constants}
34
35 The following are the node types supported by \helpref{wxXmlNode}{wxxmlnode}:
36
37 {\small
38 \begin{verbatim}
39 enum 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
78 the node.}
79 \docparam{next}{If not \NULL, this node and its eventual siblings are attached to
80 the node.}
81
82 \func{}{wxXmlNode}{\param{const wxXmlNode\& }{node}}
83
84 Copy constructor. Note that this does NOT copy syblings
85 and parent pointer, i.e. \helpref{GetParent()}{wxxmlnodegetparent} and \helpref{GetNext()}{wxxmlnodegetnext} will return \NULL
86 after using copy ctor and are never unmodified by operator=.
87
88 On 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
93 A simplified version of the first constructor form.
94
95
96 \membersection{wxXmlNode::\destruct{wxXmlNode}}\label{wxxmlnodedtor}
97
98 \func{}{\destruct{wxXmlNode}}{\void}
99
100 The virtual destructor. Deletes attached children and properties.
101
102 \membersection{wxXmlNode::AddChild}\label{wxxmlnodeaddchild}
103
104 \func{void}{AddChild}{\param{wxXmlNode* }{child}}
105
106 Adds 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
113 Appends 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
117 Appends 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
123 Removes 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
129 Returns the first child of this node.
130 To 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
137 Returns the content of this node. Can be an empty string.
138 Be aware that for nodes of type \texttt{wxXML\_ELEMENT\_NODE} (the most used node type) the
139 content 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
146 Returns the number of nodes which separe this node from {\tt grandparent}.
147
148 This function searches only the parents of this node until it finds {\tt grandparent}
149 or 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
157 Returns the content of the first child node of type \texttt{wxXML\_TEXT\_NODE} or \texttt{wxXML\_CDATA\_SECTION\_NODE}.
158 This function is very useful since the XML snippet \texttt{``<tagname>tagcontent</tagname>"} is represented by
159 expat with the following tag tree:
160
161 \begin{verbatim}
162 wxXML_ENTITY_NODE name="tagname", content=""
163 |-- wxXML_TEXT_NODE name="", content="tagcontent"
164 \end{verbatim}
165
166 or eventually:
167
168 \begin{verbatim}
169 wxXML_ENTITY_NODE name="tagname", content=""
170 |-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
171 \end{verbatim}
172
173 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.
174
175
176 \membersection{wxXmlNode::GetName}\label{wxxmlnodegetname}
177
178 \constfunc{wxString}{GetName}{\void}
179
180 Returns 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
186 Returns 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
192 Returns 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
198 Returns \true if a property named {\it propName} could be found.
199 If the {\it value} pointer is not \NULL, the value of that property is saved there.
200
201 \constfunc{wxString}{GetPropVal}{\param{const wxString\& }{propName}, \param{const wxString\& }{defaultVal}}
202
203 Returns the value of the property named {\it propName} if it does exist.
204 If it does not exist, the {\it defaultVal} is returned.
205
206 \membersection{wxXmlNode::GetProperties}\label{wxxmlnodegetproperties}
207
208 \constfunc{wxXmlProperty *}{GetProperties}{\void}
209
210 Return a pointer to the first property of this node.
211
212 \membersection{wxXmlNode::GetType}\label{wxxmlnodegettype}
213
214 \constfunc{wxXmlNodeType}{GetType}{\void}
215
216 Returns the type of this node.
217
218
219 \membersection{wxXmlNode::HasProp}\label{wxxmlnodehasprop}
220
221 \constfunc{bool}{HasProp}{\param{const wxString\& }{propName}}
222
223 Returns \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* }{before\_node}}
228
229 Inserts the {\it child} node after {\it before\_node} in the children list.
230 If {\it before\_node} is \NULL, then {\it child} is prepended to the list of children and
231 becomes the first child of this node.
232 Returns \true if {\it before\_node} has been found and the {\it child} node has been inserted.
233
234 \membersection{wxXmlNode::IsWhitespaceOnly}\label{wxxmlnodecontainsiswhitespaceonly}
235
236 \constfunc{bool}{IsWhitespaceOnly}{\void}
237
238 Returns \true if the content of this node is a string containing only whitespaces (spaces,
239 tabs, new lines, etc). Note that this function is locale-independent since the parsing of XML
240 documents must always produce the exact same tree regardless of the locale it runs under.
241
242 \membersection{wxXmlNode::RemoveChild}\label{wxxmlnoderemovechild}
243
244 \func{bool}{RemoveChild}{\param{wxXmlNode* }{child}}
245
246 Removes the given node from the children list. Returns \true if the node was found and removed
247 or \false if the node could not be found.
248
249 Note that the caller is reponsible for deleting the removed node in order to avoid memory leaks.
250
251 \membersection{wxXmlNode::SetChildren}\label{wxxmlnodesetchildren}
252
253 \func{void}{SetChildren}{\param{wxXmlNode* }{child}}
254
255 Sets as first child the given node. The caller is responsible to delete any previously present
256 children node.
257
258 \membersection{wxXmlNode::SetContent}\label{wxxmlnodesetcontent}
259
260 \func{void}{SetContent}{\param{const wxString\& }{con}}
261
262 Sets the content of this node.
263
264 \membersection{wxXmlNode::SetName}\label{wxxmlnodesetname}
265
266 \func{void}{SetName}{\param{const wxString\& }{name}}
267
268 Sets the name of this node.
269
270 \membersection{wxXmlNode::SetNext}\label{wxxmlnodesetnext}
271
272 \func{void}{SetNext}{\param{wxXmlNode* }{next}}
273
274 Sets as sibling the given node. The caller is responsible to delete any previously present
275 sibling node.
276
277 \membersection{wxXmlNode::SetParent}\label{wxxmlnodesetparent}
278
279 \func{void}{SetParent}{\param{wxXmlNode* }{parent}}
280
281 Sets as parent the given node. The caller is responsible to delete any previously present
282 parent node.
283
284 \membersection{wxXmlNode::SetProperties}\label{wxxmlnodesetproperties}
285
286 \func{void}{SetProperties}{\param{wxXmlProperty* }{prop}}
287
288 Sets as first property the given wxXmlProperty object.
289 The caller is responsible to delete any previously present properties attached to this node.
290
291 \membersection{wxXmlNode::SetType}\label{wxxmlnodesettype}
292
293 \func{void}{SetType}{\param{wxXmlNodeType }{type}}
294
295 Sets the type of this node.
296
297 \membersection{wxXmlNode::operator=}\label{wxxmlnodeoperatorassign}
298
299 \func{wxXmlNode\&}{operator=}{\param{const wxXmlNode\& }{node}}
300
301 See the copy constructor for more info.
302