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 = wxEmptyString) 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 immediately before @a followingNode in the
 161         children list.
 162
 163         @return @true if @a followingNode has been found and the @a child
 164                 node has been inserted.
 165
 166         @note
 167         For historical reasons, @a followingNode may be @NULL. In that case,
 168         then @a child is prepended to the list of children and becomes the
 169         first child of this node, i.e. it behaves identically to using the
 170         first children (as returned by GetChildren()) for @a followingNode).
 171     */
 172     bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode);
 173
 174     /**
 175         Returns @true if the content of this node is a string containing only
 176         whitespaces (spaces,
 177         tabs, new lines, etc). Note that this function is locale-independent since the
 178         parsing of XML
 179         documents must always produce the exact same tree regardless of the locale it
 180         runs under.
 181     */
 182     bool IsWhitespaceOnly() const;
 183
 184     /**
 185         Removes the given node from the children list. Returns @true if the node was
 186         found and removed
 187         or @false if the node could not be found.
 188         Note that the caller is reponsible for deleting the removed node in order to
 189         avoid memory leaks.
 190     */
 191     bool RemoveChild(wxXmlNode* child);
 192
 193     /**
 194         Sets as first attribute the given wxXmlAttribute object.
 195         The caller is responsible to delete any previously present attributes attached
 196         to this node.
 197     */
 198     void SetAttributes(wxXmlAttribute* attr);
 199
 200     /**
 201         Sets as first child the given node. The caller is responsible to delete any
 202         previously present
 203         children node.
 204     */
 205     void SetChildren(wxXmlNode* child);
 206
 207     /**
 208         Sets the content of this node.
 209     */
 210     void SetContent(const wxString& con);
 211
 212     /**
 213         Sets the name of this node.
 214     */
 215     void SetName(const wxString& name);
 216
 217     /**
 218         Sets as sibling the given node. The caller is responsible to delete any
 219         previously present
 220         sibling node.
 221     */
 222     void SetNext(wxXmlNode* next);
 223
 224     /**
 225         Sets as parent the given node. The caller is responsible to delete any
 226         previously present
 227         parent node.
 228     */
 229     void SetParent(wxXmlNode* parent);
 230
 231     /**
 232         Sets the type of this node.
 233     */
 234     void SetType(wxXmlNodeType type);
 235
 236     /**
 237         See the copy constructor for more info.
 238     */
 239     wxXmlNode operator=(const wxXmlNode& node);
 240 };
 241
 242
 243
 244 /**
 245     @class wxXmlAttribute
 246     @headerfile xml.h wx/xml/xml.h
 247
 248     Represents a node attribute.
 249
 250     Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value
 251     @c "hello.gif" and @c "id" is a attribute with value @c "3".
 252
 253     @library{wxxml}
 254     @category{xml}
 255
 256     @see wxXmlDocument, wxXmlNode
 257 */
 258 class wxXmlAttribute
 259 {
 260 public:
 261     //@{
 262     /**
 263         Creates the attribute with given @a name and @e value.
 264         If @a next is not @NULL, then sets it as sibling of this attribute.
 265     */
 266     wxXmlAttribute();
 267     wxXmlAttribute(const wxString& name, const wxString& value,
 268                    wxXmlAttribute* next = NULL);
 269     //@}
 270
 271     /**
 272         The virtual destructor.
 273     */
 274     ~wxXmlAttribute();
 275
 276     /**
 277         Returns the name of this attribute.
 278     */
 279     wxString GetName() const;
 280
 281     /**
 282         Returns the sibling of this attribute or @NULL if there are no siblings.
 283     */
 284     wxXmlAttribute* GetNext() const;
 285
 286     /**
 287         Returns the value of this attribute.
 288     */
 289     wxString GetValue() const;
 290
 291     /**
 292         Sets the name of this attribute.
 293     */
 294     void SetName(const wxString& name);
 295
 296     /**
 297         Sets the sibling of this attribute.
 298     */
 299     void SetNext(wxXmlAttribute* next);
 300
 301     /**
 302         Sets the value of this attribute.
 303     */
 304     void SetValue(const wxString& value);
 305 };
 306
 307
 308
 309 /**
 310     @class wxXmlDocument
 311     @headerfile xml.h wx/xml/xml.h
 312
 313     This class holds XML data/document as parsed by XML parser in the root node.
 314
 315     wxXmlDocument internally uses the expat library which comes with wxWidgets to
 316     parse the given stream.
 317
 318     A simple example of using XML classes is:
 319
 320     @code
 321     wxXmlDocument doc;
 322     if (!doc.Load(wxT("myfile.xml")))
 323         return @false;
 324
 325     // start processing the XML file
 326     if (doc.GetRoot()-GetName() != wxT("myroot-node"))
 327         return @false;
 328
 329     wxXmlNode *child = doc.GetRoot()-GetChildren();
 330     while (child) {
 331
 332         if (child-GetName() == wxT("tag1")) {
 333
 334             // process text enclosed by tag1/tag1
 335             wxString content = child-GetNodeContent();
 336
 337             ...
 338
 339             // process attributes of tag1
 340             wxString attrvalue1 =
 341                 child-GetAttribute(wxT("attr1"),
 342                                   wxT("default-value"));
 343             wxString attrvalue2 =
 344                 child-GetAttribute(wxT("attr2"),
 345                                   wxT("default-value"));
 346
 347             ...
 348
 349         } else if (child-GetName() == wxT("tag2")) {
 350
 351             // process tag2 ...
 352         }
 353
 354         child = child-GetNext();
 355     }
 356     @endcode
 357
 358     @b Note: if you want to preserve the original formatting of the loaded file
 359     including whitespaces
 360     and indentation, you need to turn off whitespace-only textnode removal and
 361     automatic indentation:
 362
 363     @code
 364     wxXmlDocument doc;
 365     doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES);
 366
 367     // myfile2.xml will be indentic to myfile.xml saving it this way:
 368     doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION);
 369     @endcode
 370
 371     Using default parameters, you will get a reformatted document which in general
 372     is different from
 373     the original loaded content:
 374
 375     @code
 376     wxXmlDocument doc;
 377     doc.Load(wxT("myfile.xml"));
 378     doc.Save(wxT("myfile2.xml"));  // myfile2.xml != myfile.xml
 379     @endcode
 380
 381     @library{wxxml}
 382     @category{xml}
 383
 384     @see wxXmlNode, wxXmlAttribute
 385 */
 386 class wxXmlDocument : public wxObject
 387 {
 388 public:
 389     //@{
 390     /**
 391         Copy constructor. Deep copies all the XML tree of the given document.
 392     */
 393     wxXmlDocument();
 394     wxXmlDocument(const wxString& filename);
 395     wxXmlDocument(wxInputStream& stream);
 396     wxXmlDocument(const wxXmlDocument& doc);
 397     //@}
 398
 399     /**
 400         Virtual destructor. Frees the document root node.
 401     */
 402     ~wxXmlDocument();
 403
 404     /**
 405         Detaches the document root node and returns it. The document root node will be
 406         set to @NULL
 407         and thus IsOk() will return @false after calling this function.
 408         Note that the caller is reponsible for deleting the returned node in order to
 409         avoid memory leaks.
 410     */
 411     wxXmlNode* DetachRoot();
 412
 413     /**
 414         Returns encoding of in-memory representation of the document
 415         (same as passed to Load() or constructor, defaults to UTF-8).
 416         NB: this is meaningless in Unicode build where data are stored as @c wchar_t*.
 417     */
 418     wxString GetEncoding() const;
 419
 420     /**
 421         Returns encoding of document (may be empty).
 422         Note: this is the encoding original file was saved in, @b not the
 423         encoding of in-memory representation!
 424     */
 425     wxString GetFileEncoding() const;
 426
 427     /**
 428         Returns the root node of the document.
 429     */
 430     wxXmlNode* GetRoot() const;
 431
 432     /**
 433         Returns the version of document.
 434         This is the value in the @c ?xml version="1.0"? header of the XML document.
 435         If the version attribute was not explicitely given in the header, this function
 436         returns an empty string.
 437     */
 438     wxString GetVersion() const;
 439
 440     /**
 441         Returns @true if the document has been loaded successfully.
 442     */
 443     bool IsOk() const;
 444
 445     //@{
 446     /**
 447         , @b int@e flags = wxXMLDOC_NONE)
 448         Like above but takes the data from given input stream.
 449     */
 450     bool Load(const wxString& filename);
 451     int bool Load(wxInputStream& stream);
 452     //@}
 453
 454     //@{
 455     /**
 456         Saves XML tree in the given output stream. See other overload for a description
 457         of @c indentstep.
 458     */
 459     bool Save(const wxString& filename, int indentstep = 1) const;
 460     const bool Save(wxOutputStream& stream, int indentstep = 1) const;
 461     //@}
 462
 463     /**
 464         Sets the enconding of the document.
 465     */
 466     void SetEncoding(const wxString& enc);
 467
 468     /**
 469         Sets the enconding of the file which will be used to save the document.
 470     */
 471     void SetFileEncoding(const wxString& encoding);
 472
 473     /**
 474         Sets the root node of this document. Deletes previous root node.
 475         Use DetachRoot() and then
 476         SetRoot() if you want
 477         to replace the root node without deleting the old document tree.
 478     */
 479     void SetRoot(wxXmlNode* node);
 480
 481     /**
 482         Sets the version of the XML file which will be used to save the document.
 483     */
 484     void SetVersion(const wxString& version);
 485
 486     /**
 487         Deep copies the given document.
 488     */
 489     wxXmlDocument& operator operator=(const wxXmlDocument& doc);
 490 };
 491