Resolve ambiguity between GetClientXXX() methods in wxOSX wxComboBox.

[wxWidgets.git] / interface / wx / xml / xml.h

diff --git a/interface/wx/xml/xml.h b/interface/wx/xml/xml.h
index c66ce74ca5912bbd0785e1d082a6bd25ef61e3d1..8605491dd16c63ac8eff3832c4767148305f8869 100644 (file)
--- 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$
 // 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)
     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).
 
     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.
 
     /**
         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.
     */
         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;
 
     /**
     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
 
         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;
 
     */
     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.
     */
     /**
         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
         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_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
 
         |-- 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.
 
         @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
         @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.
 
         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);
         to avoid memory leaks.
     */
     virtual bool RemoveChild(wxXmlNode* child);


@@ -297,7 +313,7 @@ public:
     /**
         Sets as first attribute the given wxXmlAttribute object.
 
     /**
         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);
         attached to this node.
     */
     void SetAttributes(wxXmlAttribute* attr);


@@ -305,7 +321,7 @@ public:
     /**
         Sets as first child the given node.
 
     /**
         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);
 
     */
     void SetChildren(wxXmlNode* child);
 


@@ -322,14 +338,21 @@ public:
     /**
         Sets as sibling the given node.
 
     /**
         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);
 
     */
     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.
 
     /**
         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);
 
     */
     void SetParent(wxXmlNode* parent);
 


@@ -351,8 +374,8 @@ public:
 
     Represents a node attribute.
 
 
     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}
 
     @library{wxxml}
     @category{xml}


@@ -424,39 +447,51 @@ public:
 
     @code
     wxXmlDocument doc;
 
     @code
     wxXmlDocument doc;

-    if (!doc.Load(wxT("myfile.xml")))
-        return @false;
+    if (!doc.Load("myfile.xml"))
+        return false;

 
     // start processing the XML file
 
     // 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) {
 
     while (child) {
 

-        if (child-GetName() == wxT("tag1")) {
+        if (child->GetName() == "tag1") {

 
             // process text enclosed by tag1/tag1
 
             // process text enclosed by tag1/tag1

-            wxString content = child-GetNodeContent();
+            wxString content = child->GetNodeContent();

 
             ...
 
             // process attributes of tag1
             wxString attrvalue1 =
 
             ...
 
             // process attributes of tag1
             wxString attrvalue1 =

-                child-GetAttribute(wxT("attr1"),
-                                  wxT("default-value"));
+                child->GetAttribute("attr1", "default-value");

             wxString attrvalue2 =
             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 ...
         }
 
 
             // process tag2 ...
         }
 

-        child = child-GetNext();
+        child = child->GetNext();

     }
     @endcode
 
     }
     @endcode
 


@@ -466,10 +501,10 @@ public:
 
     @code
     wxXmlDocument doc;
 
     @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
     @endcode
 
     Using default parameters, you will get a reformatted document which in general


@@ -477,8 +512,8 @@ public:
 
     @code
     wxXmlDocument doc;
 
     @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}
     @endcode
 
     @library{wxxml}


@@ -503,13 +538,13 @@ public:
         Loads the given filename using the given encoding. See Load().
     */
     wxXmlDocument(const wxString& filename,
         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,
 
     /**
         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 destructor. Frees the document root node.


@@ -517,11 +552,35 @@ public:
     virtual ~wxXmlDocument();
 
     /**
     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.
 
         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 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;
 
     /**
     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;
 
     */
     wxXmlNode* GetRoot() const;
 


@@ -552,7 +618,7 @@ public:
         Returns the version of document.
 
         This is the value in the @c \<?xml version="1.0"?\> header of the XML document.
         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.
     */
     const wxString& GetVersion() const;
         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,
         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,
 
     /**
         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.
 
     /**
         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.
     */
         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.
     */
 
     /**
         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 SetEncoding(const wxString& enc);
 


@@ -614,9 +691,10 @@ public:
     void SetFileEncoding(const wxString& encoding);
 
     /**
     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);
 
     */
     void SetRoot(wxXmlNode* node);
 


@@ -629,5 +707,13 @@ public:
         Deep copies the given document.
     */
     wxXmlDocument& operator=(const wxXmlDocument& doc);
         Deep copies the given document.
     */
     wxXmlDocument& operator=(const wxXmlDocument& doc);

+
+    /**
+       Get expat library version information.
+
+       @since 2.9.2
+       @see wxVersionInfo
+    */
+    static wxVersionInfo GetLibraryVersionInfo();

 };
 
 };