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