]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/log.h
undo the last change as it results in buildbot configuration error
[wxWidgets.git] / interface / wx / log.h
index fa6d09912027a579d3bc5fb6ab14dbd4b148fb4a..d404dafe9fb07d6492c2a158cbe68c7d3eda332a 100644 (file)
@@ -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
-    the (application global) @e trace mask which can either be specified using
-    SetTraceMask(), GetTraceMask() and wxLogTrace() which takes an integer mask
-    or using AddTraceMask() for string trace masks.
+    As for the (real) trace messages, their handling depends on the currently
+    enabled trace masks: if AddTraceMask() was called for the mask of the given
+    message, it will be logged, otherwise nothing happens.
 
-    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
@@ -763,9 +740,10 @@ public:
     /**
         Returns the current timestamp format string.
     */
-    static const wxString GetTimestamp();
+    static const wxString& GetTimestamp();
 
     /**
+        @deprecated
         Returns the current trace mask, see Customization() section for details.
     */
     static wxTraceMask GetTraceMask();
@@ -775,7 +753,7 @@ public:
 
         @see AddTraceMask().
     */
-    static const wxArrayString GetTraceMasks();
+    static const wxArrayString& GetTraceMasks();
 
     /**
         Returns whether the verbose mode is currently active.
@@ -793,7 +771,7 @@ public:
         Forwards the message at specified level to the @e DoLog() function of the
         active log target if there is any, does nothing otherwise.
     */
-    static void OnLog(wxLogLevel level, const wxString& message);
+    static void OnLog(wxLogLevel level, const wxString& msg, time_t t);
 
     /**
         Remove the @a mask from the list of allowed masks for
@@ -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);
 
@@ -874,6 +853,34 @@ public:
     */
     static void Suspend();
 
+    /**
+        Log the given message.
+
+        This function should only be called from the DoLog() implementations in
+        the derived classes (which can't call wxLog::DoLog() directly as it is
+        protected), it should not be used for logging new messages which can be
+        only sent to the currently active logger using OnLog() which also
+        checks if the logging (for this level) is enabled while this method
+        just directly calls DoLog().
+
+        Example of use of this class from wxLogChain:
+        @code
+        void wxLogChain::DoLog(wxLogLevel level, const wxString& msg, time_t t)
+        {
+            // let the previous logger show it
+            if ( m_logOld && IsPassingMessages() )
+                m_logOld->Log(level, msg, t);
+
+            // and also send it to the new one
+            if ( m_logNew && m_logNew != this )
+                m_logNew->Log(level, msg, t);
+        }
+        @endcode
+
+        @since 2.9.0
+     */
+    void Log(wxLogLevel level, const wxString& msg, time_t timestamp);
+
 protected:
 
     /**
@@ -947,7 +954,7 @@ protected:
     @library{wxbase}
     @category{logging}
 */
-class wxLogNull : public wxLog
+class wxLogNull
 {
 public:
     /**
@@ -967,7 +974,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 
 /**
@@ -1013,7 +1020,7 @@ const wxChar* wxSysErrorMsg(unsigned long errCode = 0);
 
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     For all normal, informational messages. They also appear in a message box
@@ -1025,7 +1032,7 @@ void wxLogMessage(const char* formatString, ... );
 void wxVLogMessage(const char* formatString, va_list argPtr);
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     For verbose output. Normally, it is suppressed, but might be activated if
@@ -1038,7 +1045,7 @@ void wxLogVerbose(const char* formatString, ... );
 void wxVLogVerbose(const char* formatString, va_list argPtr);
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     For warnings - they are also normally shown to the user, but don't
@@ -1050,7 +1057,7 @@ void wxLogWarning(const char* formatString, ... );
 void wxVLogWarning(const char* formatString, va_list argPtr);
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     Like wxLogError(), but also terminates the program with the exit code 3.
@@ -1063,7 +1070,7 @@ void wxLogFatalError(const char* formatString, ... );
 void wxVLogFatalError(const char* formatString, va_list argPtr);
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     The functions to use for error messages, i.e. the messages that must be
@@ -1076,7 +1083,7 @@ void wxLogError(const char* formatString, ... );
 void wxVLogError(const char* formatString, va_list argPtr);
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     Like wxLogDebug(), trace functions only do something in debug builds and
@@ -1084,18 +1091,18 @@ 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
-    wxLogDebug(wxTraceMask,const char*,...) can be used instead if you would
-    like to be able to separate trace messages into different categories which
-    can be enabled or disabled with the static functions provided in wxLog.
+    wxLogTrace(const char*,const char*,...) and can be used instead of
+    wxLogDebug() if you would like to be able to separate trace messages into
+    different categories which can be enabled or disabled with
+    wxLog::AddTraceMask() and wxLog::RemoveTraceMask().
 
     @header{wx/log.h}
 */
-void wxLogTrace(const char* formatString, ... );
-void wxVLogTrace(const char* formatString, va_list argPtr);
+void wxLogTrace(const char *mask, const char* formatString, ... );
+void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr);
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     Like wxLogDebug(), trace functions only do something in debug builds and
@@ -1138,7 +1145,7 @@ void wxVLogTrace(const char* mask,
                   va_list argPtr);
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     Like wxLogDebug(), trace functions only do something in debug builds and
@@ -1150,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.
 
@@ -1170,7 +1177,7 @@ void wxLogTrace(wxTraceMask mask, const char* formatString, ... );
 void wxVLogTrace(wxTraceMask mask, const char* formatString, va_list argPtr);
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     The right functions for debug output. They only do something in debug mode
@@ -1183,7 +1190,7 @@ void wxLogDebug(const char* formatString, ... );
 void wxVLogDebug(const char* formatString, va_list argPtr);
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     Messages logged by this function will appear in the statusbar of the
@@ -1200,7 +1207,7 @@ void wxLogStatus(const char* formatString, ... );
 void wxVLogStatus(const char* formatString, va_list argPtr);
 //@}
 
-/** @ingroup group_funcmacro_log */
+/** @addtogroup group_funcmacro_log */
 //@{
 /**
     Mostly used by wxWidgets itself, but might be handy for logging errors