Add wxDEPRECATED_MSG() and use it in a couple of places.

This macro should be used instead of wxDEPRECATED() for the new deprecations
as it allows to give a helpful explanatory message (if supported by the
compiler) and also is simpler to use as it doesn't require wrapping the entire
declaration in it but can be simply used before it.

Also add wxDEPRECATED() support for clang as a side effect.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@74754 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/changes.txt b/docs/changes.txt
index 9a3493850f41978b449a925534af9a9434dc224f..2d108769d36aec54b3f21400e561157601520ef7 100644 (file)
--- a/docs/changes.txt
+++ b/docs/changes.txt
@@ -565,6 +565,7 @@ All:
 - Allow using custom HTTP methods with wxHTTP (Kolya Kosenko).
 - Add wxFileName::SetPermissions() (Catalin Raceanu).
 - Fix build with wxUSE_FFILE==0 (jroemmler).
+- Add wxDEPRECATED_MSG() and use it in a few places.
 
 All (GUI):
 

diff --git a/include/wx/app.h b/include/wx/app.h
index 7d180bd248d72f8c01d4c54b7a6c93126c1777bd..60e02b35cc4d0c86eb4651f710c22820d12e9e5c 100644 (file)
--- a/include/wx/app.h
+++ b/include/wx/app.h
@@ -658,10 +658,9 @@ public:
     virtual void SetActive(bool isActive, wxWindow *lastFocus);
 
 #if WXWIN_COMPATIBILITY_2_6
-    // OBSOLETE: don't use, always returns true
-    //
     // returns true if the program is successfully initialized
-    wxDEPRECATED( bool Initialized() );
+    wxDEPRECATED_MSG("always returns true now, don't call")
+    bool Initialized();
 #endif // WXWIN_COMPATIBILITY_2_6
 
 protected:

diff --git a/include/wx/defs.h b/include/wx/defs.h
index 25cd7b1b1f450e6e980060f5e2c072520ef5515a..00c6427636e09a398549f6acd69ba47f732d2a2c 100644 (file)
--- a/include/wx/defs.h
+++ b/include/wx/defs.h
@@ -558,15 +558,53 @@ typedef short int WXTYPE;
     #define WX_ATTRIBUTE_UNUSED
 #endif
 
-/*  Macro to issue warning when using deprecated functions with gcc3 or MSVC7: */
-#if wxCHECK_GCC_VERSION(3, 1)
-    #define wxDEPRECATED(x) __attribute__((deprecated)) x
+/*
+    Macros for marking functions as being deprecated.
+
+    The preferred macro in the new code is wxDEPRECATED_MSG() which allows to
+    explain why is the function deprecated. Almost all the existing code uses
+    the older wxDEPRECATED() or its variants currently, but this will hopefully
+    change in the future.
+ */
+
+/* The basic compiler-specific construct to generate a deprecation warning. */
+#ifdef __clang__
+    #define wxDEPRECATED_DECL __attribute__((deprecated))
+#elif wxCHECK_GCC_VERSION(3, 1)
+    #define wxDEPRECATED_DECL __attribute__((deprecated))
 #elif defined(__VISUALC__) && (__VISUALC__ >= 1300)
-    #define wxDEPRECATED(x) __declspec(deprecated) x
+    #define wxDEPRECATED_DECL __declspec(deprecated)
 #else
-    #define wxDEPRECATED(x) x
+    #define wxDEPRECATED_DECL
 #endif
 
+/*
+    Macro taking the deprecation message. It applies to the next declaration.
+
+    If the compiler doesn't support showing the message, this degrades to a
+    simple wxDEPRECATED(), i.e. at least gives a warning, if possible.
+ */
+#if defined(__clang__) && defined(__has_extension)
+    #if __has_extension(attribute_deprecated_with_message)
+        #define wxDEPRECATED_MSG(msg) __attribute__((deprecated(msg)))
+    #else
+        #define wxDEPRECATED_MSG(msg) __attribute__((deprecated))
+    #endif
+#elif wxCHECK_GCC_VERSION(4, 5)
+    #define wxDEPRECATED_MSG(msg) __attribute__((deprecated(msg)))
+#elif wxCHECK_VISUALC_VERSION(8)
+    #define wxDEPRECATED_MSG(msg) __declspec(deprecated("deprecated: " msg))
+#else
+    #define wxDEPRECATED_MSG(msg) wxDEPRECATED_DECL
+#endif
+
+/*
+    Macro taking the declaration that it deprecates. Prefer to use
+    wxDEPRECATED_MSG() instead as it's simpler (wrapping the entire declaration
+    makes the code unclear) and allows to specify the explanation.
+ */
+#define wxDEPRECATED(x) wxDEPRECATED_DECL x
+
 #if defined(__GNUC__) && !wxCHECK_GCC_VERSION(3, 4)
     /*
         We need to add dummy "inline" to allow gcc < 3.4 to handle the

diff --git a/include/wx/string.h b/include/wx/string.h
index 1aafbe15f60ddf2e3120824c1ff7b1e88c6ecd44..ef1a8d9aa85a5abed3dfa70bc96af54be47185b0 100644 (file)
--- a/include/wx/string.h
+++ b/include/wx/string.h
@@ -129,16 +129,16 @@ namespace wxPrivate
 // backwards compatibility only.
 
 // checks whether the passed in pointer is NULL and if the string is empty
-wxDEPRECATED( inline bool IsEmpty(const char *p) );
+wxDEPRECATED_MSG("use wxIsEmpty() instead")
 inline bool IsEmpty(const char *p) { return (!p || !*p); }
 
 // safe version of strlen() (returns 0 if passed NULL pointer)
-wxDEPRECATED( inline size_t Strlen(const char *psz) );
+wxDEPRECATED_MSG("use wxStrlen() instead")
 inline size_t Strlen(const char *psz)
   { return psz ? strlen(psz) : 0; }
 
 // portable strcasecmp/_stricmp
-wxDEPRECATED( inline int Stricmp(const char *psz1, const char *psz2) );
+wxDEPRECATED_MSG("use wxStricmp() instead")
 inline int Stricmp(const char *psz1, const char *psz2)
     { return wxCRT_StricmpA(psz1, psz2); }
 

diff --git a/include/wx/window.h b/include/wx/window.h
index 199c4b7ef3d76b29220b7fd8ab05ef909609b648..fc37b81944cfee21facab79f3e7dad30611961aa 100644 (file)
--- a/include/wx/window.h
+++ b/include/wx/window.h
@@ -399,13 +399,18 @@ public:
         // minimum size, giving priority to the min size components, and
         // returns the results.
     virtual wxSize GetEffectiveMinSize() const;
-    wxDEPRECATED( wxSize GetBestFittingSize() const );  // replaced by GetEffectiveMinSize
-    wxDEPRECATED( wxSize GetAdjustedMinSize() const );  // replaced by GetEffectiveMinSize
+
+    wxDEPRECATED_MSG("use GetEffectiveMinSize() instead")
+    wxSize GetBestFittingSize() const;
+    wxDEPRECATED_MSG("use GetEffectiveMinSize() instead")
+    wxSize GetAdjustedMinSize() const;
 
         // A 'Smart' SetSize that will fill in default size values with 'best'
         // size.  Sets the minsize to what was passed in.
     void SetInitialSize(const wxSize& size=wxDefaultSize);
-    wxDEPRECATED( void SetBestFittingSize(const wxSize& size=wxDefaultSize) );  // replaced by SetInitialSize
+
+    wxDEPRECATED_MSG("use SetInitialSize() instead")
+    void SetBestFittingSize(const wxSize& size=wxDefaultSize);
 
 
         // the generic centre function - centers the window on parent by`
@@ -1681,8 +1686,10 @@ protected:
     // recalculated each time the value is needed.
     wxSize m_bestSizeCache;
 
-    wxDEPRECATED( void SetBestSize(const wxSize& size) );  // use SetInitialSize
-    wxDEPRECATED( virtual void SetInitialBestSize(const wxSize& size) );  // use SetInitialSize
+    wxDEPRECATED_MSG("use SetInitialSize() instead.")
+    void SetBestSize(const wxSize& size);
+    wxDEPRECATED_MSG("use SetInitialSize() instead.")
+    virtual void SetInitialBestSize(const wxSize& size);
 
 
 
@@ -1960,8 +1967,7 @@ extern WXDLLIMPEXP_CORE wxWindow *wxGetActiveWindow();
 WXDLLIMPEXP_CORE wxWindow* wxGetTopLevelParent(wxWindow *win);
 
 #if WXWIN_COMPATIBILITY_2_6
-    // deprecated (doesn't start with 'wx' prefix), use wxWindow::NewControlId()
-    wxDEPRECATED( wxWindowID NewControlId() );
+    wxDEPRECATED_MSG("use wxWindow::NewControlId() instead")
     inline wxWindowID NewControlId() { return wxWindowBase::NewControlId(); }
 #endif // WXWIN_COMPATIBILITY_2_6
 

diff --git a/interface/wx/defs.h b/interface/wx/defs.h
index a66d3b38a929cc9ef0240d2840a7cf0db1a915f5..6783dc686a7a3afb155e569d240e28517a133316 100644 (file)
--- a/interface/wx/defs.h
+++ b/interface/wx/defs.h
@@ -1555,11 +1555,40 @@ template <typename T> wxDELETE(T*& ptr);
 */
 template <typename T> wxDELETEA(T*& array);
 
+/**
+    Generate deprecation warning with the given message when a function is
+    used.
+
+    This macro can be used to generate a warning indicating that a function is
+    deprecated (i.e. scheduled for removal in the future) and explaining why is
+    it so and/or what should it be replaced with. It applies to the declaration
+    following it, for example:
+    @code
+    wxDEPRECATED_MSG("use safer overload returning wxString instead")
+    void wxGetSomething(char* buf, size_t len);
+
+    wxString wxGetSomething();
+    @endcode
+
+    For compilers other than clang, g++ 4.5 or later and MSVC 8 (MSVS 2005) or
+    later, the message is ignored and a generic deprecation warning is given if
+    possible, i.e. if the compiler is g++ (any supported version) or MSVC 7
+    (MSVS 2003) or later.
+
+    @since 3.0
+
+    @header{wx/defs.h}
+ */
+
 /**
     This macro can be used around a function declaration to generate warnings
     indicating that this function is deprecated (i.e. obsolete and planned to
-    be removed in the future) when it is used. Only Visual C++ 7 and higher and
-    g++ compilers currently support this functionality.
+    be removed in the future) when it is used.
+
+    Notice that this macro itself is deprecated in favour of wxDEPRECATED_MSG()!
+
+    Only Visual C++ 7 and higher and g++ compilers currently support this
+    functionality.
 
     Example of use: