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