interface/wx/xml/xml.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        xml/xml.h
   3 // Purpose:     interface of wxXmlNode
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxXmlNode
  11
  12     Represents a node in an XML document. See wxXmlDocument.
  13
  14     Node has a name and may have content and attributes. Most common node types are
  15     @c wxXML_TEXT_NODE (name and attributes are irrelevant) and
  16     @c wxXML_ELEMENT_NODE (e.g. in @c titlehi/title there is an element
  17     with name="title", irrelevant content and one child (@c wxXML_TEXT_NODE
  18     with content="hi").
  19
  20     If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to
  21     wxXmlDocument::Load (default is UTF-8).
  22
  23     @library{wxxml}
  24     @category{xml}
  25
  26     @see wxXmlDocument, wxXmlAttribute
  27 */
  28 class wxXmlNode
  29 {
  30 public:
  31     //@{
  32     /**
  33         A simplified version of the first constructor form, assuming a @NULL parent.
  34     */
  35     wxXmlNode(wxXmlNode* parent, wxXmlNodeType type,
  36               const wxString& name,
  37               const wxString& content = wxEmptyString,
  38               wxXmlAttribute* attrs = NULL,
  39               wxXmlNode* next = NULL, int lineNo = -1);
  40     wxXmlNode(const wxXmlNode& node);
  41     wxXmlNode(wxXmlNodeType type, const wxString& name,
  42               const wxString& content = wxEmptyString,
  43               int lineNo = -1);
  44     //@}
  45
  46     /**
  47         The virtual destructor. Deletes attached children and attributes.
  48     */
  49     ~wxXmlNode();
  50
  51     //@{
  52     /**
  53         Appends given attribute to the list of attributes for this node.
  54     */
  55     void AddAttribute(const wxString& name, const wxString& value);
  56     void AddAttribute(wxXmlAttribute* attr);
  57     //@}
  58
  59     /**
  60         Adds node @a child as the last child of this node.
  61
  62         @note
  63         Note that this function works in O(n) time where @e n is the number
  64         of existing children. Consequently, adding large number of child
  65         nodes using this method can be expensive, because it has O(n^2) time
  66         complexity in number of nodes to be added. Use InsertChildAfter() to
  67         populate XML tree in linear time.
  68
  69         @see InsertChild(), InsertChildAfter()
  70     */
  71     void AddChild(wxXmlNode* child);
  72
  73     /**
  74         Removes the first attributes which has the given @a name from the list of
  75         attributes for this node.
  76     */
  77     bool DeleteAttribute(const wxString& name);
  78
  79     //@{
  80     /**
  81         Returns the value of the attribute named @a attrName if it does exist.
  82         If it does not exist, the @a defaultVal is returned.
  83     */
  84     bool GetAttribute(const wxString& attrName, wxString* value) const;
  85     const wxString  GetAttribute(const wxString& attrName,
  86                                  const wxString& defaultVal = wxEmptyString) const;
  87     //@}
  88
  89     /**
  90         Return a pointer to the first attribute of this node.
  91     */
  92     wxXmlAttribute* GetAttributes() const;
  93
  94     /**
  95         Returns the first child of this node.
  96         To get a pointer to the second child of this node (if it does exist), use the
  97         GetNext() function on the returned value.
  98     */
  99     wxXmlNode* GetChildren() const;
 100
 101     /**
 102         Returns the content of this node. Can be an empty string.
 103         Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type)
 104         the
 105         content is an empty string. See GetNodeContent() for more details.
 106     */
 107     wxString GetContent() const;
 108
 109     /**
 110         Returns the number of nodes which separe this node from @c grandparent.
 111         This function searches only the parents of this node until it finds @c
 112         grandparent
 113         or the @NULL node (which is the parent of non-linked nodes or the parent of a
 114         wxXmlDocument's root node).
 115     */
 116     int GetDepth(wxXmlNode* grandparent = NULL) const;
 117
 118     /**
 119         Returns line number of the node in the input XML file or -1 if it is unknown.
 120     */
 121     int GetLineNumber() const;
 122
 123     /**
 124         Returns the name of this node. Can be an empty string (e.g. for nodes of type
 125         @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE).
 126     */
 127     wxString GetName() const;
 128
 129     /**
 130         Returns a pointer to the sibling of this node or @NULL if there are no
 131         siblings.
 132     */
 133     wxXmlNode* GetNext() const;
 134
 135     /**
 136         Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c
 137         wxXML_CDATA_SECTION_NODE.
 138         This function is very useful since the XML snippet @c
 139         "tagnametagcontent/tagname" is represented by
 140         expat with the following tag tree:
 141
 142         or eventually:
 143
 144         An empty string is returned if the node has no children of type @c
 145         wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty.
 146     */
 147     wxString GetNodeContent() const;
 148
 149     /**
 150         Returns a pointer to the parent of this node or @NULL if this node has no
 151         parent.
 152     */
 153     wxXmlNode* GetParent() const;
 154
 155     /**
 156         Returns the type of this node.
 157     */
 158     wxXmlNodeType GetType() const;
 159
 160     /**
 161         Returns @true if this node has a attribute named @e attrName.
 162     */
 163     bool HasAttribute(const wxString& attrName) const;
 164
 165     /**
 166         Inserts the @a child node immediately before @a followingNode in the
 167         children list.
 168
 169         @return @true if @a followingNode has been found and the @a child
 170                 node has been inserted.
 171
 172         @note
 173         For historical reasons, @a followingNode may be @NULL. In that case,
 174         then @a child is prepended to the list of children and becomes the
 175         first child of this node, i.e. it behaves identically to using the
 176         first children (as returned by GetChildren()) for @a followingNode).
 177
 178         @see AddChild(), InsertChildAfter()
 179     */
 180     bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode);
 181
 182     /**
 183         Inserts the @a child node immediately after @a precedingNode in the
 184         children list.
 185
 186         @return @true if @a precedingNode has been found and the @a child
 187                 node has been inserted.
 188
 189         @param precedingNode
 190             The node to insert @a child after. As a special case, this can be
 191             @NULL if this node has no children yet -- in that case, @a child
 192             will become this node's only child node.
 193
 194         @since 2.8.8
 195
 196         @see InsertChild(), AddChild()
 197     */
 198     bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode);
 199
 200     /**
 201         Returns @true if the content of this node is a string containing only
 202         whitespaces (spaces,
 203         tabs, new lines, etc). Note that this function is locale-independent since the
 204         parsing of XML
 205         documents must always produce the exact same tree regardless of the locale it
 206         runs under.
 207     */
 208     bool IsWhitespaceOnly() const;
 209
 210     /**
 211         Removes the given node from the children list. Returns @true if the node was
 212         found and removed
 213         or @false if the node could not be found.
 214         Note that the caller is reponsible for deleting the removed node in order to
 215         avoid memory leaks.
 216     */
 217     bool RemoveChild(wxXmlNode* child);
 218
 219     /**
 220         Sets as first attribute the given wxXmlAttribute object.
 221         The caller is responsible to delete any previously present attributes attached
 222         to this node.
 223     */
 224     void SetAttributes(wxXmlAttribute* attr);
 225
 226     /**
 227         Sets as first child the given node. The caller is responsible to delete any
 228         previously present
 229         children node.
 230     */
 231     void SetChildren(wxXmlNode* child);
 232
 233     /**
 234         Sets the content of this node.
 235     */
 236     void SetContent(const wxString& con);
 237
 238     /**
 239         Sets the name of this node.
 240     */
 241     void SetName(const wxString& name);
 242
 243     /**
 244         Sets as sibling the given node. The caller is responsible to delete any
 245         previously present
 246         sibling node.
 247     */
 248     void SetNext(wxXmlNode* next);
 249
 250     /**
 251         Sets as parent the given node. The caller is responsible to delete any
 252         previously present
 253         parent node.
 254     */
 255     void SetParent(wxXmlNode* parent);
 256
 257     /**
 258         Sets the type of this node.
 259     */
 260     void SetType(wxXmlNodeType type);
 261
 262     /**
 263         See the copy constructor for more info.
 264     */
 265     wxXmlNode operator=(const wxXmlNode& node);
 266 };
 267
 268
 269
 270 /**
 271     @class wxXmlAttribute
 272
 273     Represents a node attribute.
 274
 275     Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value
 276     @c "hello.gif" and @c "id" is a attribute with value @c "3".
 277
 278     @library{wxxml}
 279     @category{xml}
 280
 281     @see wxXmlDocument, wxXmlNode
 282 */
 283 class wxXmlAttribute
 284 {
 285 public:
 286     //@{
 287     /**
 288         Creates the attribute with given @a name and @e value.
 289         If @a next is not @NULL, then sets it as sibling of this attribute.
 290     */
 291     wxXmlAttribute();
 292     wxXmlAttribute(const wxString& name, const wxString& value,
 293                    wxXmlAttribute* next = NULL);
 294     //@}
 295
 296     /**
 297         The virtual destructor.
 298     */
 299     ~wxXmlAttribute();
 300
 301     /**
 302         Returns the name of this attribute.
 303     */
 304     wxString GetName() const;
 305
 306     /**
 307         Returns the sibling of this attribute or @NULL if there are no siblings.
 308     */
 309     wxXmlAttribute* GetNext() const;
 310
 311     /**
 312         Returns the value of this attribute.
 313     */
 314     wxString GetValue() const;
 315
 316     /**
 317         Sets the name of this attribute.
 318     */
 319     void SetName(const wxString& name);
 320
 321     /**
 322         Sets the sibling of this attribute.
 323     */
 324     void SetNext(wxXmlAttribute* next);
 325
 326     /**
 327         Sets the value of this attribute.
 328     */
 329     void SetValue(const wxString& value);
 330 };
 331
 332
 333
 334 /**
 335     @class wxXmlDocument
 336
 337     This class holds XML data/document as parsed by XML parser in the root node.
 338
 339     wxXmlDocument internally uses the expat library which comes with wxWidgets to
 340     parse the given stream.
 341
 342     A simple example of using XML classes is:
 343
 344     @code
 345     wxXmlDocument doc;
 346     if (!doc.Load(wxT("myfile.xml")))
 347         return @false;
 348
 349     // start processing the XML file
 350     if (doc.GetRoot()-GetName() != wxT("myroot-node"))
 351         return @false;
 352
 353     wxXmlNode *child = doc.GetRoot()-GetChildren();
 354     while (child) {
 355
 356         if (child-GetName() == wxT("tag1")) {
 357
 358             // process text enclosed by tag1/tag1
 359             wxString content = child-GetNodeContent();
 360
 361             ...
 362
 363             // process attributes of tag1
 364             wxString attrvalue1 =
 365                 child-GetAttribute(wxT("attr1"),
 366                                   wxT("default-value"));
 367             wxString attrvalue2 =
 368                 child-GetAttribute(wxT("attr2"),
 369                                   wxT("default-value"));
 370
 371             ...
 372
 373         } else if (child-GetName() == wxT("tag2")) {
 374
 375             // process tag2 ...
 376         }
 377
 378         child = child-GetNext();
 379     }
 380     @endcode
 381
 382     @note if you want to preserve the original formatting of the loaded file
 383     including whitespaces
 384     and indentation, you need to turn off whitespace-only textnode removal and
 385     automatic indentation:
 386
 387     @code
 388     wxXmlDocument doc;
 389     doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES);
 390
 391     // myfile2.xml will be indentic to myfile.xml saving it this way:
 392     doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION);
 393     @endcode
 394
 395     Using default parameters, you will get a reformatted document which in general
 396     is different from
 397     the original loaded content:
 398
 399     @code
 400     wxXmlDocument doc;
 401     doc.Load(wxT("myfile.xml"));
 402     doc.Save(wxT("myfile2.xml"));  // myfile2.xml != myfile.xml
 403     @endcode
 404
 405     @library{wxxml}
 406     @category{xml}
 407
 408     @see wxXmlNode, wxXmlAttribute
 409 */
 410 class wxXmlDocument : public wxObject
 411 {
 412 public:
 413     //@{
 414     /**
 415         Copy constructor. Deep copies all the XML tree of the given document.
 416     */
 417     wxXmlDocument();
 418     wxXmlDocument(const wxString& filename);
 419     wxXmlDocument(wxInputStream& stream);
 420     wxXmlDocument(const wxXmlDocument& doc);
 421     //@}
 422
 423     /**
 424         Virtual destructor. Frees the document root node.
 425     */
 426     ~wxXmlDocument();
 427
 428     /**
 429         Detaches the document root node and returns it. The document root node will be
 430         set to @NULL
 431         and thus IsOk() will return @false after calling this function.
 432         Note that the caller is reponsible for deleting the returned node in order to
 433         avoid memory leaks.
 434     */
 435     wxXmlNode* DetachRoot();
 436
 437     /**
 438         Returns encoding of in-memory representation of the document
 439         (same as passed to Load() or constructor, defaults to UTF-8).
 440         @note this is meaningless in Unicode build where data are stored as @c wchar_t*.
 441     */
 442     wxString GetEncoding() const;
 443
 444     /**
 445         Returns encoding of document (may be empty).
 446         Note: this is the encoding original file was saved in, @b not the
 447         encoding of in-memory representation!
 448     */
 449     wxString GetFileEncoding() const;
 450
 451     /**
 452         Returns the root node of the document.
 453     */
 454     wxXmlNode* GetRoot() const;
 455
 456     /**
 457         Returns the version of document.
 458         This is the value in the @c ?xml version="1.0"? header of the XML document.
 459         If the version attribute was not explicitely given in the header, this function
 460         returns an empty string.
 461     */
 462     wxString GetVersion() const;
 463
 464     /**
 465         Returns @true if the document has been loaded successfully.
 466     */
 467     bool IsOk() const;
 468
 469     //@{
 470     /**
 471         , @b int@e flags = wxXMLDOC_NONE)
 472         Like above but takes the data from given input stream.
 473     */
 474     bool Load(const wxString& filename);
 475     int bool Load(wxInputStream& stream);
 476     //@}
 477
 478     //@{
 479     /**
 480         Saves XML tree in the given output stream. See other overload for a description
 481         of @c indentstep.
 482     */
 483     bool Save(const wxString& filename, int indentstep = 1) const;
 484     const bool Save(wxOutputStream& stream, int indentstep = 1) const;
 485     //@}
 486
 487     /**
 488         Sets the enconding of the document.
 489     */
 490     void SetEncoding(const wxString& enc);
 491
 492     /**
 493         Sets the enconding of the file which will be used to save the document.
 494     */
 495     void SetFileEncoding(const wxString& encoding);
 496
 497     /**
 498         Sets the root node of this document. Deletes previous root node.
 499         Use DetachRoot() and then
 500         SetRoot() if you want
 501         to replace the root node without deleting the old document tree.
 502     */
 503     void SetRoot(wxXmlNode* node);
 504
 505     /**
 506         Sets the version of the XML file which will be used to save the document.
 507     */
 508     void SetVersion(const wxString& version);
 509
 510     /**
 511         Deep copies the given document.
 512     */
 513     wxXmlDocument& operator operator=(const wxXmlDocument& doc);
 514 };
 515