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}{\param{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::GetNodeContent}\label{wxxmlnodegetnodecontent}
 143
 144 \constfunc{wxString}{GetNodeContent}{\void}
 145
 146 Returns the content of the first child node of type \texttt{wxXML_TEXT_NODE} or \texttt{wxXML_CDATA_SECTION_NODE}.
 147 This function is very useful since the XML snippet \texttt{``<tagname>tagcontent</tagname>"} is represented by
 148 expat with the following tag tree:
 149
 150 \begin{verbatim}
 151 wxXML_ENTITY_NODE name="tagname", content=""
 152 |-- wxXML_TEXT_NODE name="", content="tagcontent"
 153 \end{verbatim}
 154
 155 or eventually:
 156
 157 \begin{verbatim}
 158 wxXML_ENTITY_NODE name="tagname", content=""
 159 |-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
 160 \end{verbatim}
 161
 162 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.
 163
 164
 165 \membersection{wxXmlNode::GetName}\label{wxxmlnodegetname}
 166
 167 \constfunc{wxString}{GetName}{\void}
 168
 169 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}).
 170
 171 \membersection{wxXmlNode::GetNext}\label{wxxmlnodegetnext}
 172
 173 \constfunc{wxXmlNode*}{GetNext}{\void}
 174
 175 Returns a pointer to the sibling of this node or \NULL if there are no siblings.
 176
 177 \membersection{wxXmlNode::GetParent}\label{wxxmlnodegetparent}
 178
 179 \constfunc{wxXmlNode*}{GetParent}{\void}
 180
 181 Returns a pointer to the parent of this node or \NULL if this node has no parent.
 182
 183 \membersection{wxXmlNode::GetPropVal}\label{wxxmlnodegetpropval}
 184
 185 \constfunc{bool}{GetPropVal}{\param{const wxString\& }{propName}, \param{wxString* }{value}}
 186
 187 Returns \true if a property named {\it propName} could be found.
 188 If the {\it value} pointer is not \NULL, the value of that property is saved there.
 189
 190 \constfunc{wxString}{GetPropVal}{\param{const wxString\& }{propName}, \param{const wxString\& }{defaultVal}}
 191
 192 Returns the value of the property named {\it propName} if it does exist.
 193 If it does not exist, the {\it defaultVal} is returned.
 194
 195 \membersection{wxXmlNode::GetProperties}\label{wxxmlnodegetproperties}
 196
 197 \constfunc{wxXmlProperty *}{GetProperties}{\void}
 198
 199 Return a pointer to the first property of this node.
 200
 201 \membersection{wxXmlNode::GetType}\label{wxxmlnodegettype}
 202
 203 \constfunc{wxXmlNodeType}{GetType}{\void}
 204
 205 Returns the type of this node.
 206
 207
 208 \membersection{wxXmlNode::HasProp}\label{wxxmlnodehasprop}
 209
 210 \constfunc{bool}{HasProp}{\param{const wxString\& }{propName}}
 211
 212 Returns \true if this node has a property named {\it propName}.
 213
 214 \membersection{wxXmlNode::InsertChild}\label{wxxmlnodeinsertchild}
 215
 216 \func{void}{InsertChild}{\param{wxXmlNode* }{child}, \param{wxXmlNode* }{before\_node}}
 217
 218 Inserts the {\it child} node after {\it before\_node} in the children list.
 219
 220 \membersection{wxXmlNode::RemoveChild}\label{wxxmlnoderemovechild}
 221
 222 \func{bool}{RemoveChild}{\param{wxXmlNode* }{child}}
 223
 224 Removes the given node from the children list. Returns \true if the node was found and removed
 225 or \false if the node could not be found.
 226
 227 \membersection{wxXmlNode::SetChildren}\label{wxxmlnodesetchildren}
 228
 229 \func{void}{SetChildren}{\param{wxXmlNode* }{child}}
 230
 231 Sets as first child the given node. The caller is responsible to delete any previously present
 232 children node.
 233
 234 \membersection{wxXmlNode::SetContent}\label{wxxmlnodesetcontent}
 235
 236 \func{void}{SetContent}{\param{const wxString\& }{con}}
 237
 238 Sets the content of this node.
 239
 240 \membersection{wxXmlNode::SetName}\label{wxxmlnodesetname}
 241
 242 \func{void}{SetName}{\param{const wxString\& }{name}}
 243
 244 Sets the name of this node.
 245
 246 \membersection{wxXmlNode::SetNext}\label{wxxmlnodesetnext}
 247
 248 \func{void}{SetNext}{\param{wxXmlNode* }{next}}
 249
 250 Sets as sibling the given node. The caller is responsible to delete any previously present
 251 sibling node.
 252
 253 \membersection{wxXmlNode::SetParent}\label{wxxmlnodesetparent}
 254
 255 \func{void}{SetParent}{\param{wxXmlNode* }{parent}}
 256
 257 Sets as parent the given node. The caller is responsible to delete any previously present
 258 parent node.
 259
 260 \membersection{wxXmlNode::SetProperties}\label{wxxmlnodesetproperties}
 261
 262 \func{void}{SetProperties}{\param{wxXmlProperty* }{prop}}
 263
 264 Sets as first property the given wxXmlProperty object.
 265 The caller is responsible to delete any previously present properties attached to this node.
 266
 267 \membersection{wxXmlNode::SetType}\label{wxxmlnodesettype}
 268
 269 \func{void}{SetType}{\param{wxXmlNodeType }{type}}
 270
 271 Sets the type of this node.
 272
 273 \membersection{wxXmlNode::operator=}\label{wxxmlnodeoperatorassign}
 274
 275 \func{wxXmlNode\&}{operator=}{\param{const wxXmlNode\& }{node}}
 276
 277 See the copy constructor for more info.
 278