/////////////////////////////////////////////////////////////////////////////
// Name: xml/xml.h
-// Purpose: interface of wxXmlNode
+// Purpose: interface of wxXmlNode, wxXmlAttribute, wxXmlDocument
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+
+/// Represents XML node type.
+enum wxXmlNodeType
+{
+ // note: values are synchronized with xmlElementType from libxml
+ wxXML_ELEMENT_NODE = 1,
+ wxXML_ATTRIBUTE_NODE = 2,
+ wxXML_TEXT_NODE = 3,
+ wxXML_CDATA_SECTION_NODE = 4,
+ wxXML_ENTITY_REF_NODE = 5,
+ wxXML_ENTITY_NODE = 6,
+ wxXML_PI_NODE = 7,
+ wxXML_COMMENT_NODE = 8,
+ wxXML_DOCUMENT_NODE = 9,
+ wxXML_DOCUMENT_TYPE_NODE = 10,
+ wxXML_DOCUMENT_FRAG_NODE = 11,
+ wxXML_NOTATION_NODE = 12,
+ wxXML_HTML_DOCUMENT_NODE = 13
+};
+
/**
@class wxXmlNode
- @headerfile xml.h wx/xml/xml.h
Represents a node in an XML document. See wxXmlDocument.
- Node has a name and may have content and attributes. Most common node types are
- @c wxXML_TEXT_NODE (name and attributes are irrelevant) and
- @c wxXML_ELEMENT_NODE (e.g. in @c titlehi/title there is an element
- with name="title", irrelevant content and one child (@c wxXML_TEXT_NODE
- with content="hi").
+ Node has a name and may have content and attributes.
+
+ Most common node types are @c wxXML_TEXT_NODE (name and attributes are irrelevant)
+ and @c wxXML_ELEMENT_NODE.
+
+ Example: in <tt>\<title\>hi\</title\></tt> there is an element with the name
+ @c title and irrelevant content and one child of type @c wxXML_TEXT_NODE
+ with @c hi as content.
+
+ The @c wxXML_PI_NODE type sets the name to the PI target and the contents to
+ the instructions. Note that whilst the PI instructions are often in the form
+ of pseudo-attributes these do not use the nodes attribute system. It is the users
+ responsibility to code and decode the instruction text.
If @c wxUSE_UNICODE is 0, all strings are encoded in the encoding given to
wxXmlDocument::Load (default is UTF-8).
class wxXmlNode
{
public:
- //@{
/**
- A simplified version of the first constructor form, assuming a @NULL parent.
+ Creates this XML node and eventually insert it into an existing XML tree.
+
+ @param parent
+ The parent node to which append this node instance.
+ If this argument is @NULL this new node will be floating and it can
+ be appended later to another one using the AddChild() or InsertChild()
+ functions. Otherwise the child is already added to the XML tree by
+ this constructor and it shouldn't be done again.
+ @param type
+ One of the ::wxXmlNodeType enumeration value.
+ @param name
+ The name of the node. This is the string which appears between angular brackets.
+ @param content
+ The content of the node.
+ Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
+ @param attrs
+ If not @NULL, this wxXmlAttribute object and its eventual siblings are attached to the node.
+ @param next
+ If not @NULL, this node and its eventual siblings are attached to the node.
+ @param lineNo
+ Number of line this node was present at in input file or -1.
*/
wxXmlNode(wxXmlNode* parent, wxXmlNodeType type,
const wxString& name,
const wxString& content = wxEmptyString,
wxXmlAttribute* attrs = NULL,
wxXmlNode* next = NULL, int lineNo = -1);
- wxXmlNode(const wxXmlNode& node);
+
+ /**
+ A simplified version of the first constructor form, assuming a @NULL parent.
+
+ @param type
+ One of the ::wxXmlNodeType enumeration value.
+ @param name
+ The name of the node. This is the string which appears between angular brackets.
+ @param content
+ The content of the node.
+ Only meaningful when type is @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE.
+ @param lineNo
+ Number of line this node was present at in input file or -1.
+ */
wxXmlNode(wxXmlNodeType type, const wxString& name,
const wxString& content = wxEmptyString,
int lineNo = -1);
- //@}
+
+ /**
+ Copy constructor.
+
+ Note that this does NOT copy siblings and parent pointer, i.e. GetParent()
+ and GetNext() will return @NULL after using copy ctor and are never unmodified by operator=().
+ On the other hand, it DOES copy children and attributes.
+ */
+ wxXmlNode(const wxXmlNode& node);
/**
The virtual destructor. Deletes attached children and attributes.
*/
- ~wxXmlNode();
+ virtual ~wxXmlNode();
+
+ /**
+ Appends a attribute with given @a name and @a value to the list of
+ attributes for this node.
+ */
+ virtual void AddAttribute(const wxString& name, const wxString& value);
- //@{
/**
Appends given attribute to the list of attributes for this node.
*/
- void AddAttribute(const wxString& name, const wxString& value);
- void AddAttribute(wxXmlAttribute* attr);
- //@}
+ virtual void AddAttribute(wxXmlAttribute* attr);
/**
Adds node @a child as the last child of this node.
@see InsertChild(), InsertChildAfter()
*/
- void AddChild(wxXmlNode* child);
+ virtual void AddChild(wxXmlNode* child);
/**
Removes the first attributes which has the given @a name from the list of
attributes for this node.
*/
- bool DeleteAttribute(const wxString& name);
+ virtual bool DeleteAttribute(const wxString& name);
+
+ /**
+ Returns true if a attribute named attrName could be found.
+ The value of that attribute is saved in value (which must not be @NULL).
+ */
+ bool GetAttribute(const wxString& attrName, wxString* value) const;
- //@{
/**
Returns the value of the attribute named @a attrName if it does exist.
If it does not exist, the @a defaultVal is returned.
*/
- bool GetAttribute(const wxString& attrName, wxString* value) const;
- const wxString GetAttribute(const wxString& attrName,
- const wxString& defaultVal = wxEmptyString) const;
- //@}
+ wxString GetAttribute(const wxString& attrName,
+ const wxString& defaultVal = wxEmptyString) const;
/**
Return a pointer to the first attribute of this node.
/**
Returns the content of this node. Can be an empty string.
Be aware that for nodes of type @c wxXML_ELEMENT_NODE (the most used node type)
- the
- content is an empty string. See GetNodeContent() for more details.
+ the content is an empty string. See GetNodeContent() for more details.
*/
- wxString GetContent() const;
+ const wxString& GetContent() const;
/**
- Returns the number of nodes which separe this node from @c grandparent.
- This function searches only the parents of this node until it finds @c
- grandparent
- or the @NULL node (which is the parent of non-linked nodes or the parent of a
- wxXmlDocument's root node).
+ Returns the number of nodes which separate this node from @c grandparent.
+
+ This function searches only the parents of this node until it finds
+ @a grandparent or the @NULL node (which is the parent of non-linked
+ nodes or the parent of a wxXmlDocument's root element node).
*/
int GetDepth(wxXmlNode* grandparent = NULL) const;
/**
- Returns line number of the node in the input XML file or -1 if it is unknown.
+ Returns a flag indicating whether encoding conversion is necessary when saving. The default is @false.
+
+ You can improve saving efficiency considerably by setting this value.
+ */
+ bool GetNoConversion() const;
+
+ /**
+ Returns line number of the node in the input XML file or @c -1 if it is unknown.
*/
int GetLineNumber() const;
/**
- Returns the name of this node. Can be an empty string (e.g. for nodes of type
- @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE).
+ Returns the name of this node.
+ Can be an empty string (e.g. for nodes of type @c wxXML_TEXT_NODE or
+ @c wxXML_CDATA_SECTION_NODE).
*/
- wxString GetName() const;
+ const wxString& GetName() const;
/**
Returns a pointer to the sibling of this node or @NULL if there are no
wxXmlNode* GetNext() const;
/**
- Returns the content of the first child node of type @c wxXML_TEXT_NODE or @c
- wxXML_CDATA_SECTION_NODE.
- This function is very useful since the XML snippet @c
- "tagnametagcontent/tagname" is represented by
- expat with the following tag tree:
+ Returns the content of the first child node of type @c wxXML_TEXT_NODE
+ or @c wxXML_CDATA_SECTION_NODE.
+ This function is very useful since the XML snippet @c "tagnametagcontent/tagname"
+ is represented by expat with the following tag tree:
+
+ @code
+ wxXML_ELEMENT_NODE name="tagname", content=""
+ |-- wxXML_TEXT_NODE name="", content="tagcontent"
+ @endcode
or eventually:
- An empty string is returned if the node has no children of type @c
- wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content of the first child of such types is empty.
+ @code
+ wxXML_ELEMENT_NODE name="tagname", content=""
+ |-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
+ @endcode
+
+ An empty string is returned if the node has no children of type
+ @c wxXML_TEXT_NODE or @c wxXML_CDATA_SECTION_NODE, or if the content
+ of the first child of such types is empty.
*/
wxString GetNodeContent() const;
wxXmlNodeType GetType() const;
/**
- Returns @true if this node has a attribute named @e attrName.
+ Returns @true if this node has a attribute named @a attrName.
*/
bool HasAttribute(const wxString& attrName) const;
@see AddChild(), InsertChildAfter()
*/
- bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode);
+ virtual bool InsertChild(wxXmlNode* child, wxXmlNode* followingNode);
/**
Inserts the @a child node immediately after @a precedingNode in the
@return @true if @a precedingNode has been found and the @a child
node has been inserted.
+ @param child
+ The child to insert.
@param precedingNode
The node to insert @a child after. As a special case, this can be
@NULL if this node has no children yet -- in that case, @a child
@see InsertChild(), AddChild()
*/
- bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode);
+ virtual bool InsertChildAfter(wxXmlNode* child, wxXmlNode* precedingNode);
/**
Returns @true if the content of this node is a string containing only
- whitespaces (spaces,
- tabs, new lines, etc). Note that this function is locale-independent since the
- parsing of XML
- documents must always produce the exact same tree regardless of the locale it
- runs under.
+ whitespaces (spaces, tabs, new lines, etc).
+
+ Note that this function is locale-independent since the parsing of XML
+ documents must always produce the exact same tree regardless of the
+ locale it runs under.
*/
bool IsWhitespaceOnly() const;
/**
- Removes the given node from the children list. Returns @true if the node was
- found and removed
- or @false if the node could not be found.
- Note that the caller is reponsible for deleting the removed node in order to
- avoid memory leaks.
+ Removes the given node from the children list.
+
+ Returns @true if the node was found and removed or @false if the node
+ could not be found.
+ Note that the caller is responsible for deleting the removed node in order
+ to avoid memory leaks.
*/
- bool RemoveChild(wxXmlNode* child);
+ virtual bool RemoveChild(wxXmlNode* child);
/**
Sets as first attribute the given wxXmlAttribute object.
- The caller is responsible to delete any previously present attributes attached
- to this node.
+
+ The caller is responsible for deleting any previously present attributes
+ attached to this node.
*/
void SetAttributes(wxXmlAttribute* attr);
/**
- Sets as first child the given node. The caller is responsible to delete any
- previously present
- children node.
+ Sets as first child the given node.
+
+ The caller is responsible for deleting any previously present children node.
*/
void SetChildren(wxXmlNode* child);
void SetName(const wxString& name);
/**
- Sets as sibling the given node. The caller is responsible to delete any
- previously present
- sibling node.
+ Sets as sibling the given node.
+
+ The caller is responsible for deleting any previously present sibling node.
*/
void SetNext(wxXmlNode* next);
/**
- Sets as parent the given node. The caller is responsible to delete any
- previously present
- parent node.
+ Sets a flag to indicate whether encoding conversion is necessary when saving. The default is @false.
+
+ You can improve saving efficiency considerably by setting this value.
+ */
+ void SetNoConversion(bool noconversion);
+
+ /**
+ Sets as parent the given node.
+
+ The caller is responsible for deleting any previously present parent node.
*/
void SetParent(wxXmlNode* parent);
/**
See the copy constructor for more info.
*/
- wxXmlNode operator=(const wxXmlNode& node);
+ wxXmlNode& operator=(const wxXmlNode& node);
};
/**
@class wxXmlAttribute
- @headerfile xml.h wx/xml/xml.h
Represents a node attribute.
- Example: in @c img src="hello.gif" id="3"/, @c "src" is attribute with value
- @c "hello.gif" and @c "id" is a attribute with value @c "3".
+ Example: in <tt>\<img src="hello.gif" id="3"/\></tt>, @c src is an attribute
+ with value @c hello.gif and @c id is an attribute with value @c 3.
@library{wxxml}
@category{xml}
class wxXmlAttribute
{
public:
- //@{
/**
- Creates the attribute with given @a name and @e value.
- If @a next is not @NULL, then sets it as sibling of this attribute.
+ Default constructor.
*/
wxXmlAttribute();
+
+ /**
+ Creates the attribute with given @a name and @a value.
+ If @a next is not @NULL, then sets it as sibling of this attribute.
+ */
wxXmlAttribute(const wxString& name, const wxString& value,
wxXmlAttribute* next = NULL);
- //@}
/**
The virtual destructor.
*/
- ~wxXmlAttribute();
+ virtual ~wxXmlAttribute();
/**
Returns the name of this attribute.
/**
@class wxXmlDocument
- @headerfile xml.h wx/xml/xml.h
This class holds XML data/document as parsed by XML parser in the root node.
@code
wxXmlDocument doc;
- if (!doc.Load(wxT("myfile.xml")))
- return @false;
+ if (!doc.Load("myfile.xml"))
+ return false;
// start processing the XML file
- if (doc.GetRoot()-GetName() != wxT("myroot-node"))
- return @false;
+ if (doc.GetRoot()->GetName() != "myroot-node")
+ return false;
+
+ // examine prologue
+ wxXmlNode *prolog = doc.GetDocumentNode()->GetChildren();
+ while (prolog) {
+
+ if (prolog->GetType() == wxXML_PI_NODE && prolog->GetName() == "target") {
+
+ // process Process Instruction contents
+ wxString pi = prolog->GetContent();
+
+ ...
- wxXmlNode *child = doc.GetRoot()-GetChildren();
+ }
+ }
+
+ wxXmlNode *child = doc.GetRoot()->GetChildren();
while (child) {
- if (child-GetName() == wxT("tag1")) {
+ if (child->GetName() == "tag1") {
// process text enclosed by tag1/tag1
- wxString content = child-GetNodeContent();
+ wxString content = child->GetNodeContent();
...
// process attributes of tag1
wxString attrvalue1 =
- child-GetAttribute(wxT("attr1"),
- wxT("default-value"));
+ child->GetAttribute("attr1", "default-value");
wxString attrvalue2 =
- child-GetAttribute(wxT("attr2"),
- wxT("default-value"));
+ child->GetAttribute("attr2", "default-value");
...
- } else if (child-GetName() == wxT("tag2")) {
+ } else if (child->GetName() == "tag2") {
// process tag2 ...
}
- child = child-GetNext();
+ child = child->GetNext();
}
@endcode
- @note if you want to preserve the original formatting of the loaded file
- including whitespaces
- and indentation, you need to turn off whitespace-only textnode removal and
- automatic indentation:
+ Note that if you want to preserve the original formatting of the loaded file
+ including whitespaces and indentation, you need to turn off whitespace-only
+ textnode removal and automatic indentation:
@code
wxXmlDocument doc;
- doc.Load(wxT("myfile.xml"), wxT("UTF-8"), wxXMLDOC_KEEP_WHITESPACE_NODES);
+ doc.Load("myfile.xml", "UTF-8", wxXMLDOC_KEEP_WHITESPACE_NODES);
- // myfile2.xml will be indentic to myfile.xml saving it this way:
- doc.Save(wxT("myfile2.xml"), wxXML_NO_INDENTATION);
+ // myfile2.xml will be identical to myfile.xml saving it this way:
+ doc.Save("myfile2.xml", wxXML_NO_INDENTATION);
@endcode
Using default parameters, you will get a reformatted document which in general
- is different from
- the original loaded content:
+ is different from the original loaded content:
@code
wxXmlDocument doc;
- doc.Load(wxT("myfile.xml"));
- doc.Save(wxT("myfile2.xml")); // myfile2.xml != myfile.xml
+ doc.Load("myfile.xml");
+ doc.Save("myfile2.xml"); // myfile2.xml != myfile.xml
@endcode
@library{wxxml}
class wxXmlDocument : public wxObject
{
public:
- //@{
/**
- Copy constructor. Deep copies all the XML tree of the given document.
+ Default constructor.
*/
wxXmlDocument();
- wxXmlDocument(const wxString& filename);
- wxXmlDocument(wxInputStream& stream);
+
+ /**
+ Copy constructor. Deep copies all the XML tree of the given document.
+ */
wxXmlDocument(const wxXmlDocument& doc);
- //@}
+
+ /**
+ Loads the given filename using the given encoding. See Load().
+ */
+ wxXmlDocument(const wxString& filename,
+ const wxString& encoding = "UTF-8"));
+
+ /**
+ Loads the XML document from given stream using the given encoding. See Load().
+ */
+ wxXmlDocument(wxInputStream& stream,
+ const wxString& encoding = "UTF-8");
/**
Virtual destructor. Frees the document root node.
*/
- ~wxXmlDocument();
+ virtual ~wxXmlDocument();
/**
- Detaches the document root node and returns it. The document root node will be
- set to @NULL
- and thus IsOk() will return @false after calling this function.
- Note that the caller is reponsible for deleting the returned node in order to
- avoid memory leaks.
+ Appends a Process Instruction or Comment node to the document prologue.
+
+ Calling this function will create a prologue or attach the node to the
+ end of an existing prologue.
+
+ @since 2.9.2
+ */
+ void AppendToProlog(wxXmlNode* node);
+
+ /**
+ Detaches the document node and returns it.
+
+ The document node will be set to @NULL and thus IsOk() will
+ return @false after calling this function.
+
+ Note that the caller is responsible for deleting the returned node in order
+ to avoid memory leaks.
+
+ @since 2.9.2
+ */
+ wxXmlNode* DetachDocumentNode();
+
+ /**
+ Detaches the root entity node and returns it.
+
+ After calling this function, the document node will remain together with
+ any prologue nodes, but IsOk() will return @false since the root entity
+ will be missing.
+
+ Note that the caller is reponsible for deleting the returned node in order
+ to avoid memory leaks.
*/
wxXmlNode* DetachRoot();
/**
Returns encoding of in-memory representation of the document
(same as passed to Load() or constructor, defaults to UTF-8).
+
@note this is meaningless in Unicode build where data are stored as @c wchar_t*.
*/
wxString GetEncoding() const;
/**
Returns encoding of document (may be empty).
- Note: this is the encoding original file was saved in, @b not the
- encoding of in-memory representation!
+
+ @note This is the encoding original file was saved in, @b not the
+ encoding of in-memory representation!
*/
- wxString GetFileEncoding() const;
+ const wxString& GetFileEncoding() const;
/**
- Returns the root node of the document.
+ Returns the document node of the document.
+
+ @since 2.9.2
+ */
+ wxXmlNode* GetDocumentNode() const;
+
+ /**
+ Returns the root element node of the document.
*/
wxXmlNode* GetRoot() const;
/**
Returns the version of document.
- This is the value in the @c ?xml version="1.0"? header of the XML document.
- If the version attribute was not explicitely given in the header, this function
+
+ This is the value in the @c \<?xml version="1.0"?\> header of the XML document.
+ If the version attribute was not explicitly given in the header, this function
returns an empty string.
*/
- wxString GetVersion() const;
+ const wxString& GetVersion() const;
/**
Returns @true if the document has been loaded successfully.
*/
bool IsOk() const;
- //@{
+
+ /**
+ Parses @a filename as an xml document and loads its data.
+
+ If @a flags does not contain wxXMLDOC_KEEP_WHITESPACE_NODES, then, while loading,
+ all nodes of type @c wxXML_TEXT_NODE (see wxXmlNode) are automatically skipped
+ if they contain whitespaces only.
+
+ The removal of these nodes makes the load process slightly faster and requires
+ less memory however makes impossible to recreate exactly the loaded text with a
+ Save() call later. Read the initial description of this class for more info.
+
+ Returns true on success, false otherwise.
+ */
+ virtual bool Load(const wxString& filename,
+ const wxString& encoding = "UTF-8", int flags = wxXMLDOC_NONE);
+
+ /**
+ Like Load(const wxString&, const wxString&, int) but takes the data from
+ given input stream.
+ */
+ virtual bool Load(wxInputStream& stream,
+ const wxString& encoding = "UTF-8", int flags = wxXMLDOC_NONE);
+
+ /**
+ Saves XML tree creating a file named with given string.
+
+ If @a indentstep is greater than or equal to zero, then, while saving,
+ an automatic indentation is added with steps composed by indentstep spaces.
+
+ If @a indentstep is @c wxXML_NO_INDENTATION, then, automatic indentation
+ is turned off.
+ */
+ virtual bool Save(const wxString& filename, int indentstep = 2) const;
+
/**
- , @b int@e flags = wxXMLDOC_NONE)
- Like above but takes the data from given input stream.
+ Saves XML tree in the given output stream.
+ See Save(const wxString&, int) for a description of @a indentstep.
*/
- bool Load(const wxString& filename);
- int bool Load(wxInputStream& stream);
- //@}
+ virtual bool Save(wxOutputStream& stream, int indentstep = 2) const;
- //@{
/**
- Saves XML tree in the given output stream. See other overload for a description
- of @c indentstep.
+ Sets the document node of this document.
+
+ Deletes any previous document node.
+ Use DetachDocumentNode() and then SetDocumentNode() if you want to
+ replace the document node without deleting the old document tree.
+
+ @since 2.9.2
*/
- bool Save(const wxString& filename, int indentstep = 1) const;
- const bool Save(wxOutputStream& stream, int indentstep = 1) const;
- //@}
+ void SetDocumentNode(wxXmlNode* node);
/**
- Sets the enconding of the document.
+ Sets the encoding of the document.
*/
void SetEncoding(const wxString& enc);
void SetFileEncoding(const wxString& encoding);
/**
- Sets the root node of this document. Deletes previous root node.
- Use DetachRoot() and then
- SetRoot() if you want
- to replace the root node without deleting the old document tree.
+ Sets the root element node of this document.
+
+ Will create the document node if necessary. Any previous
+ root element node is deleted.
*/
void SetRoot(wxXmlNode* node);
/**
Deep copies the given document.
*/
- wxXmlDocument& operator operator=(const wxXmlDocument& doc);
+ wxXmlDocument& operator=(const wxXmlDocument& doc);
+
+ /**
+ Get expat library version information.
+
+ @since 2.9.2
+ @see wxVersionInfo
+ */
+ static wxVersionInfo GetLibraryVersionInfo();
};
projects / wxWidgets.git / blobdiff