X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/95b4a59e67af301bb6ff061055ac5a9a09b96d6c..fe8aae41abf98f090ff59cdaec70ced89f8318fd:/interface/wx/xml/xml.h?ds=sidebyside diff --git a/interface/wx/xml/xml.h b/interface/wx/xml/xml.h index c66ce74ca5..8605491dd1 100644 --- a/interface/wx/xml/xml.h +++ b/interface/wx/xml/xml.h @@ -3,7 +3,7 @@ // Purpose: interface of wxXmlNode, wxXmlAttribute, wxXmlDocument // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -34,9 +34,16 @@ enum wxXmlNodeType 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 \hi\ 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 \hi\ 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). @@ -98,7 +105,7 @@ public: /** 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. */ @@ -173,14 +180,21 @@ public: 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. */ @@ -206,14 +220,14 @@ public: 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 @@ -263,6 +277,8 @@ public: @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 @@ -289,7 +305,7 @@ public: 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); @@ -297,7 +313,7 @@ public: /** 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); @@ -305,7 +321,7 @@ public: /** 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); @@ -322,14 +338,21 @@ public: /** 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); @@ -351,8 +374,8 @@ public: Represents a node attribute. - Example: in @c "\", @c "src" is attribute with value - @c "hello.gif" and @c "id" is a attribute with value @c "3". + Example: in \, @c src is an attribute + with value @c hello.gif and @c id is an attribute with value @c 3. @library{wxxml} @category{xml} @@ -424,39 +447,51 @@ public: @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 @@ -466,10 +501,10 @@ public: @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 @@ -477,8 +512,8 @@ public: @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} @@ -503,13 +538,13 @@ public: 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. @@ -517,11 +552,35 @@ public: 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. + + @since 2.9.2 + */ + void AppendToProlog(wxXmlNode* node); + + /** + Detaches the document node and returns it. - The document root node will be set to @NULL and thus IsOk() will + 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. */ @@ -544,7 +603,14 @@ public: 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; @@ -552,7 +618,7 @@ public: Returns the version of document. This is the value in the @c \ 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. */ const wxString& GetVersion() const; @@ -577,14 +643,14 @@ public: 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. @@ -595,16 +661,27 @@ public: 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); @@ -614,9 +691,10 @@ public: 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); @@ -629,5 +707,13 @@ public: Deep copies the given document. */ wxXmlDocument& operator=(const wxXmlDocument& doc); + + /** + Get expat library version information. + + @since 2.9.2 + @see wxVersionInfo + */ + static wxVersionInfo GetLibraryVersionInfo(); };