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: