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 and properties. Most common node types are
  16 {\tt wxXML\_TEXT\_NODE} (name and properties are irrelevant) and
  17 {\tt wxXML\_ELEMENT\_NODE} (e.g. in {\tt <title>hi</title>} there is an element
  18 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 \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}}
  69
  70 \wxheading{Parameters}
  71
  72 \docparam{parent}{The parent node to which append this node instance.
  73 If this argument is \NULL this new node will be {\it floating} and it can be appended later to
  74 another one using the \helpref{AddChild}{wxxmlnodeaddchild} or \helpref{InsertChild}{wxxmlnodeinsertchild}
  75 functions. Otherwise the child is already added to the XML tree by this
  76 constructor and it shouldn't be done again.}
  77 \docparam{type}{One of the wxXmlNodeType enumeration value.}
  78 \docparam{name}{The name of the node. This is the string which appears between angular brackets.}
  79 \docparam{content}{The content of the node. Only meaningful when {\it type} is
  80 {\tt wxXML\_TEXT\_NODE} or {\tt wxXML\_CDATA\_SECTION\_NODE}.}
  81 \docparam{props}{If not \NULL, this \helpref{wxXmlProperty}{wxxmlproperty} object
  82 and its eventual siblings are attached to the node.}
  83 \docparam{next}{If not \NULL, this node and its eventual siblings are attached to
  84 the node.}
  85
  86 Creates this XML node and eventually insert it into an existing XML tree.
  87
  88 \func{}{wxXmlNode}{\param{const wxXmlNode\& }{node}}
  89
  90 Copy constructor. Note that this does NOT copy syblings
  91 and parent pointer, i.e. \helpref{GetParent()}{wxxmlnodegetparent} and
  92 \helpref{GetNext()}{wxxmlnodegetnext} will return \NULL
  93 after using copy ctor and are never unmodified by operator=.
  94
  95 On the other hand, it DOES copy children and properties.
  96
  97
  98 \func{}{wxXmlNode}{\param{wxXmlNodeType }{type}, \param{const wxString\& }{name}, \param{const wxString\& }{content = wxEmptyString}}
  99
 100 A simplified version of the first constructor form, assuming a \NULL parent.
 101
 102
 103 \membersection{wxXmlNode::\destruct{wxXmlNode}}\label{wxxmlnodedtor}
 104
 105 \func{}{\destruct{wxXmlNode}}{\void}
 106
 107 The virtual destructor. Deletes attached children and properties.
 108
 109 \membersection{wxXmlNode::AddChild}\label{wxxmlnodeaddchild}
 110
 111 \func{void}{AddChild}{\param{wxXmlNode* }{child}}
 112
 113 Adds the given node as child of this node. To attach a second children to this node, use the
 114 \helpref{SetNext()}{wxxmlnodesetnext} function of the {\it child} node.
 115
 116 \membersection{wxXmlNode::AddProperty}\label{wxxmlnodeaddproperty}
 117
 118 \func{void}{AddProperty}{\param{const wxString\& }{name}, \param{const wxString\& }{value}}
 119
 120 Appends a property with given {\it name} and {\it value} to the list of properties for this node.
 121
 122 \func{void}{AddProperty}{\param{wxXmlProperty* }{prop}}
 123
 124 Appends the given property to the list of properties for this node.
 125
 126 \membersection{wxXmlNode::DeleteProperty}\label{wxxmlnodedeleteproperty}
 127
 128 \func{bool}{DeleteProperty}{\param{const wxString\& }{name}}
 129
 130 Removes the first properties which has the given {\it name} from the list of properties for this node.
 131
 132 \membersection{wxXmlNode::GetChildren}\label{wxxmlnodegetchildren}
 133
 134 \constfunc{wxXmlNode*}{GetChildren}{\void}
 135
 136 Returns the first child of this node.
 137 To get a pointer to the second child of this node (if it does exist), use the
 138 \helpref{GetNext()}{wxxmlnodegetnext} function on the returned value.
 139
 140 \membersection{wxXmlNode::GetContent}\label{wxxmlnodegetcontent}
 141
 142 \constfunc{wxString}{GetContent}{\void}
 143
 144 Returns the content of this node. Can be an empty string.
 145 Be aware that for nodes of type \texttt{wxXML\_ELEMENT\_NODE} (the most used node type) the
 146 content is an empty string. See \helpref{GetNodeContent()}{wxxmlnodegetnodecontent} for more details.
 147
 148
 149 \membersection{wxXmlNode::GetDepth}\label{wxxmlnodegetdepth}
 150
 151 \constfunc{int}{GetDepth}{\param{wxXmlNode* }{grandparent = NULL}}
 152
 153 Returns the number of nodes which separe this node from {\tt grandparent}.
 154
 155 This function searches only the parents of this node until it finds {\tt grandparent}
 156 or the \NULL node (which is the parent of non-linked nodes or the parent of a
 157 \helpref{wxXmlDocument}{wxxmldocument}'s root node).
 158
 159
 160 \membersection{wxXmlNode::GetNodeContent}\label{wxxmlnodegetnodecontent}
 161
 162 \constfunc{wxString}{GetNodeContent}{\void}
 163
 164 Returns the content of the first child node of type \texttt{wxXML\_TEXT\_NODE} or \texttt{wxXML\_CDATA\_SECTION\_NODE}.
 165 This function is very useful since the XML snippet \texttt{``<tagname>tagcontent</tagname>"} is represented by
 166 expat with the following tag tree:
 167
 168 \begin{verbatim}
 169 wxXML_ENTITY_NODE name="tagname", content=""
 170 |-- wxXML_TEXT_NODE name="", content="tagcontent"
 171 \end{verbatim}
 172
 173 or eventually:
 174
 175 \begin{verbatim}
 176 wxXML_ENTITY_NODE name="tagname", content=""
 177 |-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
 178 \end{verbatim}
 179
 180 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.
 181
 182
 183 \membersection{wxXmlNode::GetName}\label{wxxmlnodegetname}
 184
 185 \constfunc{wxString}{GetName}{\void}
 186
 187 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}).
 188
 189 \membersection{wxXmlNode::GetNext}\label{wxxmlnodegetnext}
 190
 191 \constfunc{wxXmlNode*}{GetNext}{\void}
 192
 193 Returns a pointer to the sibling of this node or \NULL if there are no siblings.
 194
 195 \membersection{wxXmlNode::GetParent}\label{wxxmlnodegetparent}
 196
 197 \constfunc{wxXmlNode*}{GetParent}{\void}
 198
 199 Returns a pointer to the parent of this node or \NULL if this node has no parent.
 200
 201 \membersection{wxXmlNode::GetPropVal}\label{wxxmlnodegetpropval}
 202
 203 \constfunc{bool}{GetPropVal}{\param{const wxString\& }{propName}, \param{wxString* }{value}}
 204
 205 Returns \true if a property named {\it propName} could be found.
 206 If the {\it value} pointer is not \NULL, the value of that property is saved there.
 207
 208 \constfunc{wxString}{GetPropVal}{\param{const wxString\& }{propName}, \param{const wxString\& }{defaultVal}}
 209
 210 Returns the value of the property named {\it propName} if it does exist.
 211 If it does not exist, the {\it defaultVal} is returned.
 212
 213 \membersection{wxXmlNode::GetProperties}\label{wxxmlnodegetproperties}
 214
 215 \constfunc{wxXmlProperty *}{GetProperties}{\void}
 216
 217 Return a pointer to the first property of this node.
 218
 219 \membersection{wxXmlNode::GetType}\label{wxxmlnodegettype}
 220
 221 \constfunc{wxXmlNodeType}{GetType}{\void}
 222
 223 Returns the type of this node.
 224
 225
 226 \membersection{wxXmlNode::HasProp}\label{wxxmlnodehasprop}
 227
 228 \constfunc{bool}{HasProp}{\param{const wxString\& }{propName}}
 229
 230 Returns \true if this node has a property named {\it propName}.
 231
 232 \membersection{wxXmlNode::InsertChild}\label{wxxmlnodeinsertchild}
 233
 234 \func{bool}{InsertChild}{\param{wxXmlNode* }{child}, \param{wxXmlNode* }{before\_node}}
 235
 236 Inserts the {\it child} node after {\it before\_node} in the children list.
 237 If {\it before\_node} is \NULL, then {\it child} is prepended to the list of children and
 238 becomes the first child of this node.
 239 Returns \true if {\it before\_node} has been found and the {\it child} node has been inserted.
 240
 241 \membersection{wxXmlNode::IsWhitespaceOnly}\label{wxxmlnodecontainsiswhitespaceonly}
 242
 243 \constfunc{bool}{IsWhitespaceOnly}{\void}
 244
 245 Returns \true if the content of this node is a string containing only whitespaces (spaces,
 246 tabs, new lines, etc). Note that this function is locale-independent since the parsing of XML
 247 documents must always produce the exact same tree regardless of the locale it runs under.
 248
 249 \membersection{wxXmlNode::RemoveChild}\label{wxxmlnoderemovechild}
 250
 251 \func{bool}{RemoveChild}{\param{wxXmlNode* }{child}}
 252
 253 Removes the given node from the children list. Returns \true if the node was found and removed
 254 or \false if the node could not be found.
 255
 256 Note that the caller is reponsible for deleting the removed node in order to avoid memory leaks.
 257
 258 \membersection{wxXmlNode::SetChildren}\label{wxxmlnodesetchildren}
 259
 260 \func{void}{SetChildren}{\param{wxXmlNode* }{child}}
 261
 262 Sets as first child the given node. The caller is responsible to delete any previously present
 263 children node.
 264
 265 \membersection{wxXmlNode::SetContent}\label{wxxmlnodesetcontent}
 266
 267 \func{void}{SetContent}{\param{const wxString\& }{con}}
 268
 269 Sets the content of this node.
 270
 271 \membersection{wxXmlNode::SetName}\label{wxxmlnodesetname}
 272
 273 \func{void}{SetName}{\param{const wxString\& }{name}}
 274
 275 Sets the name of this node.
 276
 277 \membersection{wxXmlNode::SetNext}\label{wxxmlnodesetnext}
 278
 279 \func{void}{SetNext}{\param{wxXmlNode* }{next}}
 280
 281 Sets as sibling the given node. The caller is responsible to delete any previously present
 282 sibling node.
 283
 284 \membersection{wxXmlNode::SetParent}\label{wxxmlnodesetparent}
 285
 286 \func{void}{SetParent}{\param{wxXmlNode* }{parent}}
 287
 288 Sets as parent the given node. The caller is responsible to delete any previously present
 289 parent node.
 290
 291 \membersection{wxXmlNode::SetProperties}\label{wxxmlnodesetproperties}
 292
 293 \func{void}{SetProperties}{\param{wxXmlProperty* }{prop}}
 294
 295 Sets as first property the given wxXmlProperty object.
 296 The caller is responsible to delete any previously present properties attached to this node.
 297
 298 \membersection{wxXmlNode::SetType}\label{wxxmlnodesettype}
 299
 300 \func{void}{SetType}{\param{wxXmlNodeType }{type}}
 301
 302 Sets the type of this node.
 303
 304 \membersection{wxXmlNode::operator=}\label{wxxmlnodeoperatorassign}
 305
 306 \func{wxXmlNode\&}{operator=}{\param{const wxXmlNode\& }{node}}
 307
 308 See the copy constructor for more info.
 309