Deprecate "encoding" parameter of wxXmlDocument ctor and Load()

This parameter wasn't used for anything as it specified the encoding of
the data contents in memory and not the encoding of the XML file as
might be believed, so it only created unnecessary confusion.

See #24167.

include/wx/xml/xml.h

@@ -229,10 +229,8 @@ class WXDLLIMPEXP_XML wxXmlDocument : public wxObject
 {
 public:
     wxXmlDocument();
-    wxXmlDocument(const wxString& filename,
+    wxXmlDocument(const wxString& filename);
-                  const wxString& encoding = wxT("UTF-8"));
+    wxXmlDocument(wxInputStream& stream);
-    wxXmlDocument(wxInputStream& stream,
-                  const wxString& encoding = wxT("UTF-8"));
     ~wxXmlDocument() = default;
 
     wxXmlDocument(const wxXmlDocument& doc);
@@ -240,10 +238,8 @@ public:
 
     // Parses .xml file and loads data. Returns TRUE on success, FALSE
     // otherwise.
-    virtual bool Load(const wxString& filename,
+    bool Load(const wxString& filename, int flags = wxXMLDOC_NONE);
-                      const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
+    bool Load(wxInputStream& stream, int flags = wxXMLDOC_NONE);
-    virtual bool Load(wxInputStream& stream,
-                      const wxString& encoding = wxT("UTF-8"), int flags = wxXMLDOC_NONE);
 
     // Saves document as .xml file.
     virtual bool Save(const wxString& filename, int indentstep = 2) const;
@@ -281,6 +277,36 @@ public:
 
     static wxVersionInfo GetLibraryVersionInfo();
 
+#ifdef WXWIN_COMPATIBILITY_3_2
+    wxDEPRECATED_MSG("Remove encoding parameter from the call")
+    wxXmlDocument(const wxString& filename,
+                  const wxString& WXUNUSED(encoding))
+        : wxXmlDocument(filename)
+    {
+    }
+
+    wxDEPRECATED_MSG("Remove encoding parameter from the call")
+    wxXmlDocument(wxInputStream& stream,
+                  const wxString& WXUNUSED(encoding))
+        : wxXmlDocument(stream)
+    {
+    }
+
+    wxDEPRECATED_MSG("Remove encoding parameter from the call")
+    bool Load(const wxString& filename,
+              const wxString& WXUNUSED(encoding), int flags = wxXMLDOC_NONE)
+    {
+        return Load(filename, flags);
+    }
+
+    wxDEPRECATED_MSG("Remove encoding parameter from the call")
+    bool Load(wxInputStream& stream,
+              const wxString& WXUNUSED(encoding), int flags = wxXMLDOC_NONE)
+    {
+        return Load(stream, flags);
+    }
+#endif // WXWIN_COMPATIBILITY_3_2
+
 private:
     wxString   m_version;
     wxString   m_fileEncoding;

interface/wx/xml/xml.h

@@ -637,7 +637,7 @@ enum wxXmlDocumentLoadFlag
 
     @code
     wxXmlDocument doc;
-    doc.Load("myfile.xml", "UTF-8", wxXMLDOC_KEEP_WHITESPACE_NODES);
+    doc.Load("myfile.xml", wxXMLDOC_KEEP_WHITESPACE_NODES);
 
     // myfile2.xml will be identical to myfile.xml saving it this way:
     doc.Save("myfile2.xml", wxXML_NO_INDENTATION);
@@ -711,14 +711,12 @@ public:
     /**
         Loads the given filename using the given encoding. See Load().
     */
-    wxXmlDocument(const wxString& filename,
+    wxXmlDocument(const wxString& filename);
-                  const wxString& encoding = "UTF-8");
 
     /**
         Loads the XML document from given stream using the given encoding. See Load().
     */
-    wxXmlDocument(wxInputStream& stream,
+    wxXmlDocument(wxInputStream& stream);
-                  const wxString& encoding = "UTF-8");
 
     /**
         Virtual destructor. Frees the document root node.
@@ -831,15 +829,13 @@ public:
 
         Returns true on success, false otherwise.
     */
-    virtual bool Load(const wxString& filename,
+    bool Load(const wxString& filename, 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
+        Like Load(const wxString&, int) but takes the data from given input
-        given input stream.
+        stream.
     */
-    virtual bool Load(wxInputStream& stream,
+    bool Load(wxInputStream& stream, int flags = wxXMLDOC_NONE);
-                      const wxString& encoding = "UTF-8", int flags = wxXMLDOC_NONE);
 
     /**
         Saves XML tree creating a file named with given string.

src/richtext/richtextxml.cpp

@@ -76,10 +76,7 @@ bool wxRichTextXMLHandler::DoLoadFile(wxRichTextBuffer *buffer, wxInputStream& s
     wxXmlDocument* xmlDoc = new wxXmlDocument;
     bool success = true;
 
-    // This is the encoding to convert to (memory encoding rather than file encoding)
+    if (!xmlDoc->Load(stream))
-    wxString encoding(wxT("UTF-8"));
-
-    if (!xmlDoc->Load(stream, encoding))
     {
         buffer->ResetAndClearCommands();
         success = false;

src/xml/xml.cpp

@@ -444,16 +444,16 @@ wxXmlDocument::wxXmlDocument()
 {
 }
 
-wxXmlDocument::wxXmlDocument(const wxString& filename, const wxString& encoding)
+wxXmlDocument::wxXmlDocument(const wxString& filename)
               :wxObject()
 {
-    Load(filename, encoding);
+    Load(filename);
 }
 
-wxXmlDocument::wxXmlDocument(wxInputStream& stream, const wxString& encoding)
+wxXmlDocument::wxXmlDocument(wxInputStream& stream)
               :wxObject()
 {
-    Load(stream, encoding);
+    Load(stream);
 }
 
 wxXmlDocument::wxXmlDocument(const wxXmlDocument& doc)
@@ -482,12 +482,12 @@ void wxXmlDocument::DoCopy(const wxXmlDocument& doc)
         m_docNode.reset();
 }
 
-bool wxXmlDocument::Load(const wxString& filename, const wxString& encoding, int flags)
+bool wxXmlDocument::Load(const wxString& filename, int flags)
 {
     wxFileInputStream stream(filename);
     if (!stream.IsOk())
         return false;
-    return Load(stream, encoding, flags);
+    return Load(stream, flags);
 }
 
 bool wxXmlDocument::Save(const wxString& filename, int indentstep) const
@@ -820,10 +820,8 @@ static int UnknownEncodingHnd(void * WXUNUSED(encodingHandlerData),
 
 } // extern "C"
 
-bool wxXmlDocument::Load(wxInputStream& stream, const wxString& encoding, int flags)
+bool wxXmlDocument::Load(wxInputStream& stream, int flags)
 {
-    (void)encoding;
-
     const size_t BUFSIZE = 1024;
     char buf[BUFSIZE];
     wxXmlParsingContext ctx;

src/xrc/xmlres.cpp

@@ -800,10 +800,8 @@ wxXmlDocument *wxXmlResource::DoLoadFile(const wxString& filename)
         return nullptr;
     }
 
-    wxString encoding(wxT("UTF-8"));
-
     std::unique_ptr<wxXmlDocument> doc(new wxXmlDocument);
-    if (!doc->Load(*stream, encoding))
+    if (!doc->Load(*stream))
     {
         wxLogError(_("Cannot load resources from file '%s'."), filename);
         return nullptr;

tests/xml/xmltest.cpp

@@ -223,7 +223,7 @@ void XmlTestCase::LoadSave()
     ;
 
     wxStringInputStream sisp(xmlTextProlog);
-    CPPUNIT_ASSERT( doc.Load(sisp, "UTF-8") );
+    CPPUNIT_ASSERT( doc.Load(sisp) );
 
     wxStringOutputStream sosp;
     CPPUNIT_ASSERT( doc.Save(sosp) );

tests/xml/xrctest.cpp

@@ -45,7 +45,7 @@ static const char *TEST_XRC_FILE = "test.xrc";
 void LoadXrcFrom(const wxString& xrcText)
 {
     wxStringInputStream sis(xrcText);
-    std::unique_ptr<wxXmlDocument> xmlDoc(new wxXmlDocument(sis, "UTF-8"));
+    std::unique_ptr<wxXmlDocument> xmlDoc(new wxXmlDocument(sis));
     REQUIRE( xmlDoc->IsOk() );
 
     // Load the xrc we've just created
@@ -294,7 +294,7 @@ TEST_CASE("XRC::EnvVarInPath", "[xrc]")
         "<root><bitmap>$(WX_TEST_ENV_IN_PATH).bmp</bitmap></root>"
 #endif
     );
-    wxXmlDocument xmlDoc(sis, "UTF-8");
+    wxXmlDocument xmlDoc(sis);
     REQUIRE( xmlDoc.IsOk() );
 
     class wxTestEnvXmlHandler : public wxXmlResourceHandler