interface/xml/xml.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        xml/xml.h
   3 // Purpose:     documentation for wxXmlNode class
   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     @seealso
  28     wxXmlDocument, wxXmlAttribute
  29 */
  30 class wxXmlNode
  31 {
  32 public:
  33     //@{
  34     /**
  35         A simplified version of the first constructor form, assuming a @NULL parent.
  36     */
  37     wxXmlNode(wxXmlNode* parent, wxXmlNodeType type,
  38               const wxString& name,
  39               const wxString& content = wxEmptyString,
  40               wxXmlAttribute* attrs = NULL,
  41               wxXmlNode* next = NULL, int lineNo = -1);
  42     wxXmlNode(const wxXmlNode& node);
  43     wxXmlNode(wxXmlNodeType type, const wxString& name,
  44               const wxString& content = wxEmptyString,
  45               int lineNo = -1);
  46     //@}
  47
  48     /**
  49         The virtual destructor. Deletes attached children and attributes.
  50     */
  51     ~wxXmlNode();
  52
  53     //@{
  54     /**
  55         Appends given attribute to the list of attributes for this node.
  56     */
  57     void AddAttribute(const wxString& name, const wxString& value);
  58     void AddAttribute(wxXmlAttribute* attr);
  59     //@}
  60
  61     /**
  62         Adds the given node as child of this node. To attach a second children to this
  63         node, use the
  64         SetNext() function of the @a child node.
  65     */
  66     void AddChild(wxXmlNode* child);
  67
  68     /**
  69         Removes the first attributes which has the given @a name from the list of
  70         attributes for this node.
  71     */
  72     bool DeleteAttribute(const wxString& name);
  73
  74     //@{
  75     /**
  76         Returns the value of the attribute named @a attrName if it does exist.
  77         If it does not exist, the @a defaultVal is returned.
  78     */
  79     bool GetAttribute(const wxString& attrName, wxString* value) const;
  80     const wxString  GetAttribute(const wxString& attrName,
  81                                  const wxString& defaultVal) const;
  82     //@}
  83
  84     /**
  85         Return a pointer to the first attribute of this node.
  86     */
  87     wxXmlAttribute* GetAttributes() const;
  88
  89     /**
  90         Returns the first child of this node.
  91         To get a pointer to the second child of this node (if it does exist), use the
  92         GetNext() function on the returned value.
  93     */
  94     wxXmlNode* GetChildren() const;
  95
  96     /**
  97         Returns the content of this node. Can be an empty string.
  98         Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type)
  99         the
 100         content is an empty string. See GetNodeContent() for more details.
 101     */
 102     wxString GetContent() const;
 103
 104     /**
 105         Returns the number of nodes which separe this node from @c grandparent.
 106         This function searches only the parents of this node until it finds @c
 107         grandparent
 108         or the @NULL node (which is the parent of non-linked nodes or the parent of a
 109         wxXmlDocument's root node).
 110     */
 111     int GetDepth(wxXmlNode* grandparent = NULL) const;
 112
 113     /**
 114         Returns line number of the node in the input XML file or -1 if it is unknown.
 115     */
 116     int GetLineNumber() const;
 117
 118     /**
 119         Returns the name of this node. Can be an empty string (e.g. for nodes of type
 120         @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE).
 121     */
 122     wxString GetName() const;
 123
 124     /**
 125         Returns a pointer to the sibling of this node or @NULL if there are no
 126         siblings.
 127     */
 128     wxXmlNode* GetNext() const;
 129
 130     /**
 131         Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c
 132         wxXML_CDATA_SECTION_NODE.
 133         This function is very useful since the XML snippet @c
 134         "tagnametagcontent/tagname" is represented by
 135         expat with the following tag tree:
 136
 137         or eventually:
 138
 139         An empty string is returned if the node has no children of type @c
 140         wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty.
 141     */
 142     wxString GetNodeContent() const;
 143
 144     /**
 145         Returns a pointer to the parent of this node or @NULL if this node has no
 146         parent.
 147     */
 148     wxXmlNode* GetParent() const;
 149
 150     /**
 151         Returns the type of this node.
 152     */
 153     wxXmlNodeType GetType() const;
 154
 155     /**
 156         Returns @true if this node has a attribute named @e attrName.
 157     */
 158     bool HasAttribute(const wxString& attrName) const;
 159
 160     /**
 161         Inserts the @a child node after @a before_node in the children list.
 162         If @a before_node is @NULL, then @a child is prepended to the list of
 163         children and
 164         becomes the first child of this node.
 165         Returns @true if @a before_node has been found and the @a child node has been
 166         inserted.
 167     */
 168     bool InsertChild(wxXmlNode* child, wxXmlNode* before_node);
 169
 170     /**
 171         Returns @true if the content of this node is a string containing only
 172         whitespaces (spaces,
 173         tabs, new lines, etc). Note that this function is locale-independent since the
 174         parsing of XML
 175         documents must always produce the exact same tree regardless of the locale it
 176         runs under.
 177     */
 178     bool IsWhitespaceOnly() const;
 179
 180     /**
 181         Removes the given node from the children list. Returns @true if the node was
 182         found and removed
 183         or @false if the node could not be found.
 184         Note that the caller is reponsible for deleting the removed node in order to
 185         avoid memory leaks.
 186     */
 187     bool RemoveChild(wxXmlNode* child);
 188
 189     /**
 190         Sets as first attribute the given wxXmlAttribute object.
 191         The caller is responsible to delete any previously present attributes attached
 192         to this node.
 193     */
 194     void SetAttributes(wxXmlAttribute* attr);
 195
 196     /**
 197         Sets as first child the given node. The caller is responsible to delete any
 198         previously present
 199         children node.
 200     */
 201     void SetChildren(wxXmlNode* child);
 202
 203     /**
 204         Sets the content of this node.
 205     */
 206     void SetContent(const wxString& con);
 207
 208     /**
 209         Sets the name of this node.
 210     */
 211     void SetName(const wxString& name);
 212
 213     /**
 214         Sets as sibling the given node. The caller is responsible to delete any
 215         previously present
 216         sibling node.
 217     */
 218     void SetNext(wxXmlNode* next);
 219
 220     /**
 221         Sets as parent the given node. The caller is responsible to delete any
 222         previously present
 223         parent node.
 224     */
 225     void SetParent(wxXmlNode* parent);
 226
 227     /**
 228         Sets the type of this node.
 229     */
 230     void SetType(wxXmlNodeType type);
 231
 232     /**
 233         See the copy constructor for more info.
 234     */
 235     wxXmlNode operator=(const wxXmlNode& node);
 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     @seealso
 252     wxXmlDocument, wxXmlNode
 253 */
 254 class wxXmlAttribute
 255 {
 256 public:
 257     //@{
 258     /**
 259         Creates the attribute with given @a name and @e value.
 260         If @a next is not @NULL, then sets it as sibling of this attribute.
 261     */
 262     wxXmlAttribute();
 263     wxXmlAttribute(const wxString& name, const wxString& value,
 264                    wxXmlAttribute* next = NULL);
 265     //@}
 266
 267     /**
 268         The virtual destructor.
 269     */
 270     ~wxXmlAttribute();
 271
 272     /**
 273         Returns the name of this attribute.
 274     */
 275     wxString GetName() const;
 276
 277     /**
 278         Returns the sibling of this attribute or @NULL if there are no siblings.
 279     */
 280     wxXmlAttribute* GetNext() const;
 281
 282     /**
 283         Returns the value of this attribute.
 284     */
 285     wxString GetValue() const;
 286
 287     /**
 288         Sets the name of this attribute.
 289     */
 290     void SetName(const wxString& name);
 291
 292     /**
 293         Sets the sibling of this attribute.
 294     */
 295     void SetNext(wxXmlAttribute* next);
 296
 297     /**
 298         Sets the value of this attribute.
 299     */
 300     void SetValue(const wxString& value);
 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     @seealso
 380     wxXmlNode, wxXmlAttribute
 381 */
 382 class wxXmlDocument : public wxObject
 383 {
 384 public:
 385     //@{
 386     /**
 387         Copy constructor. Deep copies all the XML tree of the given document.
 388     */
 389     wxXmlDocument();
 390     wxXmlDocument(const wxString& filename);
 391     wxXmlDocument(wxInputStream& stream);
 392     wxXmlDocument(const wxXmlDocument& doc);
 393     //@}
 394
 395     /**
 396         Virtual destructor. Frees the document root node.
 397     */
 398     ~wxXmlDocument();
 399
 400     /**
 401         Detaches the document root node and returns it. The document root node will be
 402         set to @NULL
 403         and thus IsOk() will return @false after calling this function.
 404         Note that the caller is reponsible for deleting the returned node in order to
 405         avoid memory leaks.
 406     */
 407     wxXmlNode* DetachRoot();
 408
 409     /**
 410         Returns encoding of in-memory representation of the document
 411         (same as passed to Load() or constructor, defaults to UTF-8).
 412         NB: this is meaningless in Unicode build where data are stored as @c wchar_t*.
 413     */
 414     wxString GetEncoding() const;
 415
 416     /**
 417         Returns encoding of document (may be empty).
 418         Note: this is the encoding original file was saved in, @b not the
 419         encoding of in-memory representation!
 420     */
 421     wxString GetFileEncoding() const;
 422
 423     /**
 424         Returns the root node of the document.
 425     */
 426     wxXmlNode* GetRoot() const;
 427
 428     /**
 429         Returns the version of document.
 430         This is the value in the @c ?xml version="1.0"? header of the XML document.
 431         If the version attribute was not explicitely given in the header, this function
 432         returns an empty string.
 433     */
 434     wxString GetVersion() const;
 435
 436     /**
 437         Returns @true if the document has been loaded successfully.
 438     */
 439     bool IsOk() const;
 440
 441     //@{
 442     /**
 443         , @b int@e flags = wxXMLDOC_NONE)
 444         Like above but takes the data from given input stream.
 445     */
 446     bool Load(const wxString& filename);
 447     int bool Load(wxInputStream& stream);
 448     //@}
 449
 450     //@{
 451     /**
 452         Saves XML tree in the given output stream. See other overload for a description
 453         of @c indentstep.
 454     */
 455     bool Save(const wxString& filename, int indentstep = 1) const;
 456     const bool Save(wxOutputStream& stream, int indentstep = 1) const;
 457     //@}
 458
 459     /**
 460         Sets the enconding of the document.
 461     */
 462     void SetEncoding(const wxString& enc);
 463
 464     /**
 465         Sets the enconding of the file which will be used to save the document.
 466     */
 467     void SetFileEncoding(const wxString& encoding);
 468
 469     /**
 470         Sets the root node of this document. Deletes previous root node.
 471         Use DetachRoot() and then
 472         SetRoot() if you want
 473         to replace the root node without deleting the old document tree.
 474     */
 475     void SetRoot(wxXmlNode* node);
 476
 477     /**
 478         Sets the version of the XML file which will be used to save the document.
 479     */
 480     void SetVersion(const wxString& version);
 481
 482     /**
 483         Deep copies the given document.
 484     */
 485     wxXmlDocument& operator operator=(const wxXmlDocument& doc);
 486 };