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