X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1707da0c3773be45553bdc4502a676613b1cfdb7..95aced61936dc40a90a306cff338cd4b629785b5:/interface/wx/xml/xml.h?ds=sidebyside diff --git a/interface/wx/xml/xml.h b/interface/wx/xml/xml.h index 17b77e5c65..7bb23cd54b 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 @@ -291,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); @@ -299,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); @@ -307,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); @@ -324,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); @@ -353,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} @@ -427,16 +448,30 @@ public: @code wxXmlDocument doc; if (!doc.Load("myfile.xml")) - return @false; + return false; // start processing the XML file if (doc.GetRoot()->GetName() != "myroot-node") - return @false; + 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) { - if (child-GetName() == "tag1") { + if (child->GetName() == "tag1") { // process text enclosed by tag1/tag1 wxString content = child->GetNodeContent(); @@ -468,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 @@ -509,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. @@ -517,12 +552,36 @@ 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 reponsible for deleting the returned node in order + 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 responsible for deleting the returned node in order to avoid memory leaks. */ wxXmlNode* DetachRoot(); @@ -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(); };