From 178635b62a262f694533468a355dd090cbf78a32 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Wed, 4 Sep 2013 00:14:22 +0000 Subject: [PATCH 1/1] 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 | 1 + include/wx/app.h | 5 ++--- include/wx/defs.h | 48 ++++++++++++++++++++++++++++++++++++++++----- include/wx/string.h | 6 +++--- include/wx/window.h | 20 ++++++++++++------- interface/wx/defs.h | 33 +++++++++++++++++++++++++++++-- 6 files changed, 93 insertions(+), 20 deletions(-) diff --git a/docs/changes.txt b/docs/changes.txt index 9a3493850f..2d108769d3 100644 --- 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 7d180bd248..60e02b35cc 100644 --- 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 25cd7b1b1f..00c6427636 100644 --- 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 1aafbe15f6..ef1a8d9aa8 100644 --- 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 199c4b7ef3..fc37b81944 100644 --- 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 a66d3b38a9..6783dc686a 100644 --- a/interface/wx/defs.h +++ b/interface/wx/defs.h @@ -1555,11 +1555,40 @@ template wxDELETE(T*& ptr); */ template 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: -- 2.45.2