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