X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4ce846b17c9a1ad71c749253cc8b73d492ed9634..c29c95fe24973b94fd724db767193171ca7c513d:/interface/wx/xml/xml.h diff --git a/interface/wx/xml/xml.h b/interface/wx/xml/xml.h index cabd080e2f..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 ///////////////////////////////////////////////////////////////////////////// @@ -40,6 +40,11 @@ enum wxXmlNodeType @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). @@ -100,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. */ @@ -175,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. */ @@ -208,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 @@ -293,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); @@ -301,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); @@ -309,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); @@ -326,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); @@ -435,6 +454,20 @@ public: 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(); while (child) { @@ -470,7 +503,7 @@ public: wxXmlDocument doc; doc.Load("myfile.xml", "UTF-8", wxXMLDOC_KEEP_WHITESPACE_NODES); - // myfile2.xml will be indentic to myfile.xml saving it this way: + // myfile2.xml will be identical to myfile.xml saving it this way: doc.Save("myfile2.xml", wxXML_NO_INDENTATION); @endcode @@ -511,7 +544,7 @@ public: 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. @@ -519,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. */ @@ -546,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; @@ -554,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; @@ -579,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. @@ -597,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 enconding of the document. + 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 encoding of the document. */ void SetEncoding(const wxString& enc); @@ -616,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); @@ -631,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(); };