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 @e child node.
  65     */
  66     void AddChild(wxXmlNode* child);
  67
  68     /**
  69         Removes the first attributes which has the given @e 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 @e attrName if it does exist.
  77         If it does not exist, the @e defaultVal is returned.
  78     */
  79     bool GetAttribute(const wxString& attrName, wxString* value);
  80         wxString GetAttribute(const wxString& attrName,
  81                               const wxString& defaultVal);
  82     //@}
  83
  84     /**
  85         Return a pointer to the first attribute of this node.
  86     */
  87     wxXmlAttribute * GetAttributes();
  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();
  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();
 103
 104     /**
 105         Returns the number of nodes which separe this node from @c grandparent.
 106
 107         This function searches only the parents of this node until it finds @c
 108         grandparent
 109         or the @NULL node (which is the parent of non-linked nodes or the parent of a
 110         wxXmlDocument's root node).
 111     */
 112     int GetDepth(wxXmlNode* grandparent = @NULL);
 113
 114     /**
 115         Returns line number of the node in the input XML file or -1 if it is unknown.
 116     */
 117     int GetLineNumber();
 118
 119     /**
 120         Returns the name of this node. Can be an empty string (e.g. for nodes of type
 121         @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE).
 122     */
 123     wxString GetName();
 124
 125     /**
 126         Returns a pointer to the sibling of this node or @NULL if there are no
 127         siblings.
 128     */
 129     wxXmlNode* GetNext();
 130
 131     /**
 132         Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c
 133         wxXML_CDATA_SECTION_NODE.
 134         This function is very useful since the XML snippet @c
 135         "tagnametagcontent/tagname" is represented by
 136         expat with the following tag tree:
 137         or eventually:
 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();
 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();
 148
 149     /**
 150         Returns the type of this node.
 151     */
 152     wxXmlNodeType GetType();
 153
 154     /**
 155         Returns @true if this node has a attribute named @e attrName.
 156     */
 157     bool HasAttribute(const wxString& attrName);
 158
 159     /**
 160         Inserts the @e child node after @e before_node in the children list.
 161         If @e before_node is @NULL, then @e child is prepended to the list of
 162         children and
 163         becomes the first child of this node.
 164         Returns @true if @e before_node has been found and the @e 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();
 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
 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 @e name and @e value.
 260         If @e 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();
 276
 277     /**
 278         Returns the sibling of this attribute or @NULL if there are no siblings.
 279     */
 280     wxXmlAttribute* GetNext();
 281
 282     /**
 283         Returns the value of this attribute.
 284     */
 285     wxString GetValue();
 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
 405         Note that the caller is reponsible for deleting the returned node in order to
 406         avoid memory leaks.
 407     */
 408     wxXmlNode* DetachRoot();
 409
 410     /**
 411         Returns encoding of in-memory representation of the document
 412         (same as passed to Load() or constructor, defaults to UTF-8).
 413
 414         NB: this is meaningless in Unicode build where data are stored as @c wchar_t*.
 415     */
 416     wxString GetEncoding();
 417
 418     /**
 419         Returns encoding of document (may be empty).
 420
 421         Note: this is the encoding original file was saved in, @b not the
 422         encoding of in-memory representation!
 423     */
 424     wxString GetFileEncoding();
 425
 426     /**
 427         Returns the root node of the document.
 428     */
 429     wxXmlNode* GetRoot();
 430
 431     /**
 432         Returns the version of document.
 433         This is the value in the @c ?xml version="1.0"? header of the XML document.
 434         If the version attribute was not explicitely given in the header, this function
 435         returns an empty string.
 436     */
 437     wxString GetVersion();
 438
 439     /**
 440         Returns @true if the document has been loaded successfully.
 441     */
 442 #define bool IsOk()     /* implementation is private */
 443
 444     //@{
 445     /**
 446         , @b int@e flags = wxXMLDOC_NONE)
 447
 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);
 460         bool Save(wxOutputStream& stream, int indentstep = 1);
 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 };