include/wx/xml/xml.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        xml.h
   3 // Purpose:     wxXmlDocument - XML parser & data holder class
   4 // Author:      Vaclav Slavik
   5 // Created:     2000/03/05
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2000 Vaclav Slavik
   8 // Licence:     wxWindows licence
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11
  12 #ifndef _WX_XML_H_
  13 #define _WX_XML_H_
  14
  15 #include "wx/defs.h"
  16
  17 #if wxUSE_XML
  18
  19 #include "wx/string.h"
  20 #include "wx/object.h"
  21 #include "wx/list.h"
  22
  23 #ifdef WXMAKINGDLL_XML
  24     #define WXDLLIMPEXP_XML WXEXPORT
  25 #elif defined(WXUSINGDLL)
  26     #define WXDLLIMPEXP_XML WXIMPORT
  27 #else // not making nor using DLL
  28     #define WXDLLIMPEXP_XML
  29 #endif
  30
  31 class WXDLLIMPEXP_FWD_XML wxXmlNode;
  32 class WXDLLIMPEXP_FWD_XML wxXmlAttribute;
  33 class WXDLLIMPEXP_FWD_XML wxXmlDocument;
  34 class WXDLLIMPEXP_FWD_XML wxXmlIOHandler;
  35 class WXDLLIMPEXP_FWD_BASE wxInputStream;
  36 class WXDLLIMPEXP_FWD_BASE wxOutputStream;
  37
  38
  39 // Represents XML node type.
  40 enum wxXmlNodeType
  41 {
  42     // note: values are synchronized with xmlElementType from libxml
  43     wxXML_ELEMENT_NODE       =  1,
  44     wxXML_ATTRIBUTE_NODE     =  2,
  45     wxXML_TEXT_NODE          =  3,
  46     wxXML_CDATA_SECTION_NODE =  4,
  47     wxXML_ENTITY_REF_NODE    =  5,
  48     wxXML_ENTITY_NODE        =  6,
  49     wxXML_PI_NODE            =  7,
  50     wxXML_COMMENT_NODE       =  8,
  51     wxXML_DOCUMENT_NODE      =  9,
  52     wxXML_DOCUMENT_TYPE_NODE = 10,
  53     wxXML_DOCUMENT_FRAG_NODE = 11,
  54     wxXML_NOTATION_NODE      = 12,
  55     wxXML_HTML_DOCUMENT_NODE = 13
  56 };
  57
  58
  59 // Represents node property(ies).
  60 // Example: in <img src="hello.gif" id="3"/> "src" is property with value
  61 //          "hello.gif" and "id" is prop. with value "3".
  62
  63 class WXDLLIMPEXP_XML wxXmlAttribute
  64 {
  65 public:
  66     wxXmlAttribute() : m_next(NULL) {}
  67     wxXmlAttribute(const wxString& name, const wxString& value,
  68                   wxXmlAttribute *next = NULL)
  69             : m_name(name), m_value(value), m_next(next) {}
  70     virtual ~wxXmlAttribute() {}
  71
  72     wxString GetName() const { return m_name; }
  73     wxString GetValue() const { return m_value; }
  74     wxXmlAttribute *GetNext() const { return m_next; }
  75
  76     void SetName(const wxString& name) { m_name = name; }
  77     void SetValue(const wxString& value) { m_value = value; }
  78     void SetNext(wxXmlAttribute *next) { m_next = next; }
  79
  80 private:
  81     wxString m_name;
  82     wxString m_value;
  83     wxXmlAttribute *m_next;
  84 };
  85
  86 #if WXWIN_COMPATIBILITY_2_8
  87     // NB: #define is used instead of typedef so that forward declarations
  88     //     continue to work
  89     #define wxXmlProperty wxXmlAttribute
  90 #endif
  91
  92
  93 // Represents node in XML document. Node has name and may have content and
  94 // attributes. Most common node types are wxXML_TEXT_NODE (name and attributes
  95 // are irrelevant) and wxXML_ELEMENT_NODE (e.g. in <title>hi</title> there is
  96 // element with name="title", irrelevant content and one child (wxXML_TEXT_NODE
  97 // with content="hi").
  98 //
  99 // If wxUSE_UNICODE is 0, all strings are encoded in the encoding given to Load
 100 // (default is UTF-8).
 101
 102 class WXDLLIMPEXP_XML wxXmlNode
 103 {
 104 public:
 105     wxXmlNode()
 106         : m_attrs(NULL), m_parent(NULL), m_children(NULL), m_next(NULL) {}
 107     wxXmlNode(wxXmlNode *parent, wxXmlNodeType type,
 108               const wxString& name, const wxString& content = wxEmptyString,
 109               wxXmlAttribute *attrs = NULL, wxXmlNode *next = NULL);
 110     virtual ~wxXmlNode();
 111
 112     // copy ctor & operator=. Note that this does NOT copy syblings
 113     // and parent pointer, i.e. m_parent and m_next will be NULL
 114     // after using copy ctor and are never unmodified by operator=.
 115     // On the other hand, it DOES copy children and attributes.
 116     wxXmlNode(const wxXmlNode& node);
 117     wxXmlNode& operator=(const wxXmlNode& node);
 118
 119     // user-friendly creation:
 120     wxXmlNode(wxXmlNodeType type, const wxString& name,
 121               const wxString& content = wxEmptyString);
 122     virtual void AddChild(wxXmlNode *child);
 123     virtual bool InsertChild(wxXmlNode *child, wxXmlNode *before_node);
 124     virtual bool RemoveChild(wxXmlNode *child);
 125     virtual void AddAttribute(const wxString& name, const wxString& value)
 126         { AddProperty(name, value); }
 127     virtual bool DeleteAttribute(const wxString& name)
 128         { return DeleteProperty(name); }
 129
 130     // access methods:
 131     wxXmlNodeType GetType() const { return m_type; }
 132     const wxString& GetName() const { return m_name; }
 133     const wxString& GetContent() const { return m_content; }
 134
 135     bool IsWhitespaceOnly() const;
 136     int GetDepth(wxXmlNode *grandparent = NULL) const;
 137
 138     // Gets node content from wxXML_ENTITY_NODE
 139     // The problem is, <tag>content<tag> is represented as
 140     // wxXML_ENTITY_NODE name="tag", content=""
 141     //    |-- wxXML_TEXT_NODE or
 142     //        wxXML_CDATA_SECTION_NODE name="" content="content"
 143     wxString GetNodeContent() const;
 144
 145     wxXmlNode *GetParent() const { return m_parent; }
 146     wxXmlNode *GetNext() const { return m_next; }
 147     wxXmlNode *GetChildren() const { return m_children; }
 148
 149     wxXmlAttribute *GetAttributes() const { return m_attrs; }
 150     bool GetAttribute(const wxString& attrName, wxString *value) const;
 151     wxString GetAttribute(const wxString& attrName,
 152                          const wxString& defaultVal) const;
 153     bool HasAttribute(const wxString& attrName) const;
 154
 155     void SetType(wxXmlNodeType type) { m_type = type; }
 156     void SetName(const wxString& name) { m_name = name; }
 157     void SetContent(const wxString& con) { m_content = con; }
 158
 159     void SetParent(wxXmlNode *parent) { m_parent = parent; }
 160     void SetNext(wxXmlNode *next) { m_next = next; }
 161     void SetChildren(wxXmlNode *child) { m_children = child; }
 162
 163     void SetAttributes(wxXmlAttribute *attr) { m_attrs = attr; }
 164     virtual void AddAttribute(wxXmlAttribute *attr)
 165         { AddProperty(attr); }
 166
 167 #if WXWIN_COMPATIBILITY_2_8
 168     wxDEPRECATED( inline wxXmlAttribute *GetProperties() const );
 169     wxDEPRECATED( inline bool GetPropVal(const wxString& propName,
 170                                          wxString *value) const );
 171     wxDEPRECATED( inline wxString GetPropVal(const wxString& propName,
 172                                              const wxString& defaultVal) const );
 173     wxDEPRECATED( inline bool HasProp(const wxString& propName) const );
 174
 175     wxDEPRECATED( inline void SetProperties(wxXmlAttribute *prop) );
 176 #endif // WXWIN_COMPATIBILITY_2_8
 177
 178     // The following three functions are backward compatibility, but because
 179     // they were virtual, we must make it possible to override them. This
 180     // is done by calling e.g. AddProperty() from AddAttribute(), so we have
 181     // to keep AddProperty() even if 2.8 compatibility is off. To prevent
 182     // old code from compiling in that case, we make them private and
 183     // non-virtual. (This can be removed when WXWIN_COMPATIBILITY_2_8 is
 184     // removed, we'll have just *Attribute versions then.)
 185 #if WXWIN_COMPATIBILITY_2_8
 186     wxDEPRECATED_BUT_USED_INTERNALLY(
 187         virtual void AddProperty(const wxString& name, const wxString& value) );
 188     wxDEPRECATED_BUT_USED_INTERNALLY(
 189         virtual bool DeleteProperty(const wxString& name) );
 190     wxDEPRECATED_BUT_USED_INTERNALLY(
 191         virtual void AddProperty(wxXmlAttribute *attr) );
 192 #else
 193 private:
 194     void AddProperty(const wxString& name, const wxString& value);
 195     bool DeleteProperty(const wxString& name);
 196     void AddProperty(wxXmlAttribute *attr);
 197 #endif // WXWIN_COMPATIBILITY_2_8/!WXWIN_COMPATIBILITY_2_8
 198
 199 private:
 200     wxXmlNodeType m_type;
 201     wxString m_name;
 202     wxString m_content;
 203     wxXmlAttribute *m_attrs;
 204     wxXmlNode *m_parent, *m_children, *m_next;
 205
 206     void DoCopy(const wxXmlNode& node);
 207 };
 208
 209 #if WXWIN_COMPATIBILITY_2_8
 210 inline wxXmlAttribute *wxXmlNode::GetProperties() const
 211     { return GetAttributes(); }
 212 inline bool wxXmlNode::GetPropVal(const wxString& propName,
 213                                   wxString *value) const
 214     { return GetAttribute(propName, value); }
 215 inline wxString wxXmlNode::GetPropVal(const wxString& propName,
 216                                       const wxString& defaultVal) const
 217     { return GetAttribute(propName, defaultVal); }
 218 inline bool wxXmlNode::HasProp(const wxString& propName) const
 219     { return HasAttribute(propName); }
 220 inline void wxXmlNode::SetProperties(wxXmlAttribute *prop)
 221     { SetAttributes(prop); }
 222 #endif // WXWIN_COMPATIBILITY_2_8
 223
 224
 225
 226 // special indentation value for wxXmlDocument::Save
 227 #define wxXML_NO_INDENTATION           (-1)
 228
 229 // flags for wxXmlDocument::Load
 230 enum wxXmlDocumentLoadFlag
 231 {
 232     wxXMLDOC_NONE = 0,
 233     wxXMLDOC_KEEP_WHITESPACE_NODES = 1
 234 };
 235
 236
 237 // This class holds XML data/document as parsed by XML parser.
 238
 239 class WXDLLIMPEXP_XML wxXmlDocument : public wxObject
 240 {
 241 public:
 242     wxXmlDocument();
 243     wxXmlDocument(const wxString& filename,
 244                   const wxString& encoding = wxT("UTF-8"));
 245     wxXmlDocument(wxInputStream& stream,
 246                   const wxString& encoding = wxT("UTF-8"));
 247     virtual ~wxXmlDocument() { wxDELETE(m_root); }
 248
 249     wxXmlDocument(const wxXmlDocument& doc);
 250     wxXmlDocument& operator=(const wxXmlDocument& doc);
 251
 252     // Parses .xml file and loads data. Returns TRUE on success, FALSE
 253     // otherwise.
 254     virtual bool Load(const wxString& filename,
 255                       const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
 256     virtual bool Load(wxInputStream& stream,
 257                       const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
 258
 259     // Saves document as .xml file.
 260     virtual bool Save(const wxString& filename, int indentstep = 1) const;
 261     virtual bool Save(wxOutputStream& stream, int indentstep = 1) const;
 262
 263     bool IsOk() const { return m_root != NULL; }
 264
 265     // Returns root node of the document.
 266     wxXmlNode *GetRoot() const { return m_root; }
 267
 268     // Returns version of document (may be empty).
 269     const wxString& GetVersion() const { return m_version; }
 270     // Returns encoding of document (may be empty).
 271     // Note: this is the encoding original file was saved in, *not* the
 272     // encoding of in-memory representation!
 273     const wxString& GetFileEncoding() const { return m_fileEncoding; }
 274
 275     // Write-access methods:
 276     wxXmlNode *DetachRoot() { wxXmlNode *old=m_root; m_root=NULL; return old; }
 277     void SetRoot(wxXmlNode *node) { wxDELETE(m_root); m_root = node; }
 278     void SetVersion(const wxString& version) { m_version = version; }
 279     void SetFileEncoding(const wxString& encoding) { m_fileEncoding = encoding; }
 280
 281 #if !wxUSE_UNICODE
 282     // Returns encoding of in-memory representation of the document
 283     // (same as passed to Load or ctor, defaults to UTF-8).
 284     // NB: this is meaningless in Unicode build where data are stored as wchar_t*
 285     wxString GetEncoding() const { return m_encoding; }
 286     void SetEncoding(const wxString& enc) { m_encoding = enc; }
 287 #endif
 288
 289 private:
 290     wxString   m_version;
 291     wxString   m_fileEncoding;
 292 #if !wxUSE_UNICODE
 293     wxString   m_encoding;
 294 #endif
 295     wxXmlNode *m_root;
 296
 297     void DoCopy(const wxXmlDocument& doc);
 298
 299     DECLARE_CLASS(wxXmlDocument)
 300 };
 301
 302 #endif // wxUSE_XML
 303
 304 #endif // _WX_XML_H_