// Purpose: interface of wxXmlNode, wxXmlAttribute, wxXmlDocument
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
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 \<title\>hi\</title\> there is an element
- with name="title", irrelevant content and one child @c wxXML_TEXT_NODE
- with content="hi").
+ 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).
/**
Copy constructor.
- Note that this does NOT copy syblings and parent pointer, i.e. GetParent()
+ 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.
*/
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.
*/
- wxString GetContent() const;
+ const wxString& GetContent() const;
/**
- Returns the number of nodes which separe this node from @c grandparent.
+ 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 node).
+ nodes or the parent of a wxXmlDocument's root element node).
*/
int GetDepth(wxXmlNode* grandparent = NULL) const;
+ /**
+ 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.
*/
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
is represented by expat with the following tag tree:
@code
- wxXML_ENTITY_NODE name="tagname", content=""
+ wxXML_ELEMENT_NODE name="tagname", content=""
|-- wxXML_TEXT_NODE name="", content="tagcontent"
@endcode
or eventually:
@code
- wxXML_ENTITY_NODE name="tagname", content=""
+ wxXML_ELEMENT_NODE name="tagname", content=""
|-- wxXML_CDATA_SECTION_NODE name="", content="tagcontent"
@endcode
@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
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
+ Note that the caller is responsible for deleting the removed node in order
to avoid memory leaks.
*/
virtual bool RemoveChild(wxXmlNode* child);
/**
Sets as first attribute the given wxXmlAttribute object.
- The caller is responsible to delete any previously present attributes
+ 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.
+ The caller is responsible for deleting any previously present children node.
*/
void SetChildren(wxXmlNode* child);
/**
Sets as sibling the given node.
- The caller is responsible to delete any previously present sibling node.
+ The caller is responsible for deleting any previously present sibling node.
*/
void SetNext(wxXmlNode* next);
+ /**
+ 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 to delete any previously present parent node.
+ The caller is responsible for deleting any previously present parent node.
*/
void SetParent(wxXmlNode* parent);
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}
@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) {
- wxXmlNode *child = doc.GetRoot()-GetChildren();
+ if (prolog->GetType() == wxXML_PI_NODE && prolog->GetName() == "target") {
+
+ // process Process Instruction contents
+ wxString pi = prolog->GetContent();
+
+ ...
+
+ }
+ }
+
+ 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
@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
@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}
Loads the given filename using the given encoding. See Load().
*/
wxXmlDocument(const wxString& filename,
- const wxString& encoding = wxT("UTF-8"));
+ const wxString& encoding = "UTF-8"));
/**
Loads the XML document from given stream using the given encoding. See Load().
*/
wxXmlDocument(wxInputStream& stream,
- const wxString& encoding = wxT("UTF-8"));
+ const wxString& encoding = "UTF-8");
/**
Virtual destructor. Frees the document root node.
virtual ~wxXmlDocument();
/**
- Detaches the document root node and returns it.
+ 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.
- The document root node will be set to @NULL and thus IsOk() will
+ @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.
*/
@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 document node of the document.
+
+ @since 2.9.2
+ */
+ wxXmlNode* GetDocumentNode() const;
/**
- Returns the root node of the document.
+ 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
+ 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.
Returns true on success, false otherwise.
*/
virtual bool Load(const wxString& filename,
- const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
+ 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 = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
+ const wxString& encoding = "UTF-8", int flags = wxXMLDOC_NONE);
/**
Saves XML tree creating a file named with given string.
If @a indentstep is @c wxXML_NO_INDENTATION, then, automatic indentation
is turned off.
*/
- virtual bool Save(const wxString& filename, int indentstep = 1) const;
+ virtual bool Save(const wxString& filename, int indentstep = 2) const;
/**
Saves XML tree in the given output stream.
See Save(const wxString&, int) for a description of @a indentstep.
*/
- virtual bool Save(wxOutputStream& stream, int indentstep = 1) const;
+ virtual bool Save(wxOutputStream& stream, int indentstep = 2) const;
+
+ /**
+ 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
+ */
+ 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=(const wxXmlDocument& doc);
+
+ /**
+ Get expat library version information.
+
+ @since 2.9.2
+ @see wxVersionInfo
+ */
+ static wxVersionInfo GetLibraryVersionInfo();
};
projects / wxWidgets.git / blobdiff