deprecate integer trace masks and don't define the methods related to them if WXWIN_COMPATIBILITY_2_8==0

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

include/wx/log.h

@@ -15,14 +15,15 @@
 #include "wx/defs.h"
 
 // ----------------------------------------------------------------------------
-// common constants for use in wxUSE_LOG/!wxUSE_LOG
+// types
 // ----------------------------------------------------------------------------
 
-// the trace masks have been superceded by symbolic trace constants, they're
+// NB: this is needed even if wxUSE_LOG == 0
-// for compatibility only andwill be removed soon - do NOT use them
+typedef unsigned long wxLogLevel;
 
-// meaning of different bits of the trace mask (which allows selectively
+// the trace masks have been superseded by symbolic trace constants, they're
-// enable/disable some trace messages)
+// for compatibility only and will be removed soon - do NOT use them
+#if WXWIN_COMPATIBILITY_2_8
     #define wxTraceMemAlloc 0x0001  // trace memory allocation (new/delete)
     #define wxTraceMessages 0x0002  // trace window messages/X callbacks
     #define wxTraceResAlloc 0x0004  // trace GDI resource allocation
@@ -32,13 +33,8 @@
         #define wxTraceOleCalls 0x0100  // OLE interface calls
     #endif
 
-// ----------------------------------------------------------------------------
-// types
-// ----------------------------------------------------------------------------
-
-// NB: these types are needed even if wxUSE_LOG == 0
     typedef unsigned long wxTraceMask;
-typedef unsigned long wxLogLevel;
+#endif // WXWIN_COMPATIBILITY_2_8
 
 // ----------------------------------------------------------------------------
 // headers
@@ -191,9 +187,6 @@ public:
     // gets duplicate counting status
     static bool GetRepetitionCounting() { return ms_bRepetCounting; }
 
-    // trace mask (see wxTraceXXX constants for details)
-    static void SetTraceMask(wxTraceMask ulMask) { ms_ulTraceMask = ulMask; }
-
     // add string trace mask
     static void AddTraceMask(const wxString& str);
 
@@ -221,9 +214,6 @@ public:
     // gets the verbose status
     static bool GetVerbose() { return ms_bVerbose; }
 
-    // get trace mask
-    static wxTraceMask GetTraceMask() { return ms_ulTraceMask; }
-
     // is this trace mask in the list?
     static bool IsAllowedTraceMask(const wxString& mask);
 
@@ -260,6 +250,14 @@ public:
     wxDEPRECATED( static wxChar *SetLogBuffer(wxChar *buf, size_t size = 0) );
 #endif
 
+    // don't use integer masks any more, use string trace masks instead
+#if WXWIN_COMPATIBILITY_2_8
+    wxDEPRECATED_INLINE( static void SetTraceMask(wxTraceMask ulMask),
+        ms_ulTraceMask = ulMask; )
+    wxDEPRECATED_BUT_USED_INTERNALLY_INLINE( static wxTraceMask GetTraceMask(),
+        return ms_ulTraceMask; )
+#endif // WXWIN_COMPATIBILITY_2_8
+
 protected:
     // the logging functions that can be overridden
 
@@ -343,8 +341,12 @@ private:
     // disabled
     static wxString    ms_timestamp;
 
+#if WXWIN_COMPATIBILITY_2_8
     static wxTraceMask ms_ulTraceMask;   // controls wxLogTrace behaviour
-    static wxArrayString ms_aTraceMasks; // more powerful filter for wxLogTrace
+#endif // WXWIN_COMPATIBILITY_2_8
+
+    // currently enabled trace masks
+    static wxArrayString ms_aTraceMasks;
 };
 
 // ----------------------------------------------------------------------------
@@ -740,7 +742,9 @@ DECLARE_LOG_FUNCTION2(SysError, unsigned long, lErrCode);
     // and this one does nothing if all of level bits are not set in
     // wxLog::GetActive()->GetTraceMask() -- it's deprecated in favour of
     // string identifiers
+#if WXWIN_COMPATIBILITY_2_8
     DECLARE_LOG_FUNCTION2(Trace, wxTraceMask, mask);
+#endif // wxDEBUG_LEVEL
 #ifdef __WATCOMC__
     // workaround for http://bugzilla.openwatcom.org/show_bug.cgi?id=351
     DECLARE_LOG_FUNCTION2(Trace, int, mask);

interface/wx/log.h

@@ -27,11 +27,6 @@ enum wxLogLevelValues
     wxLOG_Max = 10000
 };
 
-/**
-    The type used for trace masks.
-*/
-typedef unsigned long wxTraceMask;
-
 /**
     The type used to specify a log level.
 
@@ -613,24 +608,11 @@ public:
     but may be activated, for example, in order to help the user find some program
     problem.
 
-    As for the (real) trace messages, their handling depends on the settings of
+    As for the (real) trace messages, their handling depends on the currently
-    the (application global) @e trace mask which can either be specified using
+    enabled trace masks: if AddTraceMask() was called for the mask of the given
-    SetTraceMask(), GetTraceMask() and wxLogTrace() which takes an integer mask
+    message, it will be logged, otherwise nothing happens.
-    or using AddTraceMask() for string trace masks.
 
-    The difference between bit-wise and string trace masks is that a message using
-    integer trace mask will only be logged if all bits of the mask are set in the
-    current mask while a message using string mask will be logged simply if the
-    mask had been added before to the list of allowed ones.
     For example,
-
-    @code
-    wxLogTrace( wxTraceRefCount|wxTraceOleCalls, "Active object ref count: %d", nRef );
-    @endcode
-
-    will do something only if the current trace mask contains both @c wxTraceRefCount
-    and @c wxTraceOle, but:
-
     @code
     wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" );
     @endcode
@@ -641,11 +623,6 @@ public:
     wxLog::AddTraceMask( wxTRACE_OleCalls);
     @endcode
 
-    Using string masks is simpler and allows you to easily add custom ones, so this
-    is the preferred way of working with trace messages. The integer trace mask is
-    kept for compatibility and for additional (but very rarely needed) flexibility
-    only.
-
     The standard trace masks are given in wxLogTrace() documentation.
 
     Finally, the @e wxLog::DoLog() function automatically prepends a time stamp
@@ -766,6 +743,7 @@ public:
     static const wxString& GetTimestamp();
 
     /**
+        @deprecated
         Returns the current trace mask, see Customization() section for details.
     */
     static wxTraceMask GetTraceMask();
@@ -848,7 +826,8 @@ public:
     static void DisableTimestamp();
 
     /**
-        Sets the trace mask, see @ref log_derivingyours section for details.
+        @deprecated
+        Sets the trace mask, see @ref log_tracemasks section for details.
     */
     static void SetTraceMask(wxTraceMask mask);
 
@@ -1112,15 +1091,15 @@ void wxVLogError(const char* formatString, va_list argPtr);
     function is that usually there are a lot of trace messages, so it might
     make sense to separate them from other debug messages.
 
-    wxLogDebug(const char*,const char*,...) and
+    wxLogTrace(const char*,const char*,...) and can be used instead of
-    wxLogDebug(wxTraceMask,const char*,...) can be used instead if you would
+    wxLogDebug() if you would like to be able to separate trace messages into
-    like to be able to separate trace messages into different categories which
+    different categories which can be enabled or disabled with
-    can be enabled or disabled with the static functions provided in wxLog.
+    wxLog::AddTraceMask() and wxLog::RemoveTraceMask().
 
     @header{wx/log.h}
 */
-void wxLogTrace(const char* formatString, ... );
+void wxLogTrace(const char *mask, const char* formatString, ... );
-void wxVLogTrace(const char* formatString, va_list argPtr);
+void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr);
 //@}
 
 /** @addtogroup group_funcmacro_log */
@@ -1178,7 +1157,7 @@ void wxVLogTrace(const char* mask,
     This version of wxLogTrace() only logs the message if all the bits
     corresponding to the @a mask are set in the wxLog trace mask which can be
     set by calling wxLog::SetTraceMask(). This version is less flexible than
-    wxLogDebug(const char*,const char*,...) because it doesn't allow defining
+    wxLogTrace(const char*,const char*,...) because it doesn't allow defining
     the user trace masks easily. This is why it is deprecated in favour of
     using string trace masks.
 

src/common/log.cpp

@@ -331,6 +331,9 @@ void wxDoLogVerboseUtf8(const char *format, ...)
   }
 #endif // wxUSE_UNICODE_UTF8
 
+// deprecated (but not declared as such because we don't want to complicate
+// DECLARE_LOG_FUNCTION macros even more) overloads for wxTraceMask
+#if WXWIN_COMPATIBILITY_2_8
   void wxVLogTrace(wxTraceMask mask, const wxString& format, va_list argptr)
   {
     // we check that all of mask bits are set in the current mask, so
@@ -361,7 +364,10 @@ void wxDoLogVerboseUtf8(const char *format, ...)
   }
 #endif // wxUSE_UNICODE_UTF8
 
+#endif // WXWIN_COMPATIBILITY_2_8
+
 #ifdef __WATCOMC__
+#if WXWIN_COMPATIBILITY_2_8
   // workaround for http://bugzilla.openwatcom.org/show_bug.cgi?id=351
   void wxDoLogTraceWchar(int mask, const wxChar *format, ...)
   {
@@ -370,6 +376,7 @@ void wxDoLogVerboseUtf8(const char *format, ...)
     wxVLogTrace(mask, format, argptr);
     va_end(argptr);
   }
+#endif // WXWIN_COMPATIBILITY_2_8
 
   void wxDoLogTraceWchar(const char *mask, const wxChar *format, ...)
   {
@@ -387,8 +394,10 @@ void wxDoLogVerboseUtf8(const char *format, ...)
     va_end(argptr);
   }
 
+#if WXWIN_COMPATIBILITY_2_8
   void wxVLogTrace(int mask, const wxString& format, va_list argptr)
     { wxVLogTrace((wxTraceMask)mask, format, argptr); }
+#endif // WXWIN_COMPATIBILITY_2_8
   void wxVLogTrace(const char *mask, const wxString& format, va_list argptr)
     { wxVLogTrace(wxString(mask), format, argptr); }
   void wxVLogTrace(const wchar_t *mask, const wxString& format, va_list argptr)
@@ -975,7 +984,10 @@ size_t          wxLog::ms_suspendCount = 0;
 
 wxString        wxLog::ms_timestamp(wxS("%X"));  // time only, no date
 
+#if WXWIN_COMPATIBILITY_2_8
 wxTraceMask     wxLog::ms_ulTraceMask  = (wxTraceMask)0;
+#endif // wxDEBUG_LEVEL
+
 wxArrayString   wxLog::ms_aTraceMasks;
 
 // ----------------------------------------------------------------------------