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

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):
 

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:

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)
+    Macros for marking functions as being deprecated.
-    #define wxDEPRECATED(x) __attribute__((deprecated)) x
+
+    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

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); }
 

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_MSG("use SetInitialSize() instead.")
-    wxDEPRECATED( virtual void SetInitialBestSize(const wxSize& size) );  // use SetInitialSize
+    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_MSG("use wxWindow::NewControlId() instead")
-    wxDEPRECATED( wxWindowID NewControlId() );
     inline wxWindowID NewControlId() { return wxWindowBase::NewControlId(); }
 #endif // WXWIN_COMPATIBILITY_2_6
 

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
+    be removed in the future) when it is used.
-    g++ compilers currently support this functionality.
+
+    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: