X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c602c59b6e623d7775c16ce6412b64b34dc5dd94..85b1997c095b18cd5e9e54e9d39feaa71c5ffa06:/interface/wx/log.h

diff --git a/interface/wx/log.h b/interface/wx/log.h
index 49a9f10d76..04f57638d4 100644
--- a/interface/wx/log.h
+++ b/interface/wx/log.h
@@ -633,6 +633,11 @@ public:
 
     @section log_tracemasks Using trace masks
 
+    Notice that the use of log trace masks is hardly necessary any longer in
+    current wxWidgets version as the same effect can be achieved by using
+    different log components for different log statements of any level. Please
+    see @ref overview_log_enable for more information about the log components.
+
     The functions below allow some limited customization of wxLog behaviour
     without writing a new log target class (which, aside from being a matter of
     several minutes, allows you to do anything you want).
@@ -744,7 +749,8 @@ public:
     /**
         Globally enable or disable logging.
 
-        Calling this function with @false argument disables all log messages.
+        Calling this function with @false argument disables all log messages
+        for the current thread.
 
         @see wxLogNull, IsEnabled()
 
@@ -756,19 +762,39 @@ public:
 
     /**
         Shows all the messages currently in buffer and clears it.
+
         If the buffer is already empty, nothing happens.
+
+        If you override this method in a derived class, call the base class
+        version first, before doing anything else.
     */
     virtual void Flush();
 
     /**
         Flushes the current log target if any, does nothing if there is none.
 
-        @see Flush()
+        When this method is called from the main thread context, it also
+        flushes any previously buffered messages logged by the other threads.
+        When it is called from the other threads it simply calls Flush() on the
+        currently active log target, so it mostly makes sense to do this if a
+        thread has its own logger set with SetThreadActiveTarget().
     */
     static void FlushActive();
 
     /**
         Returns the pointer to the active log target (may be @NULL).
+
+        Notice that if SetActiveTarget() hadn't been previously explicitly
+        called, this function will by default try to create a log target by
+        calling wxAppTraits::CreateLogTarget() which may be overridden in a
+        user-defined traits class to change the default behaviour. You may also
+        call DontCreateOnDemand() to disable this behaviour.
+
+        When this function is called from threads other than main one,
+        auto-creation doesn't happen. But if the thread has a thread-specific
+        log target previously set by SetThreadActiveTarget(), it is returned
+        instead of the global one. Otherwise, the global log target is
+        returned.
     */
     static wxLog* GetActiveTarget();
 
@@ -825,7 +851,7 @@ public:
     static bool IsEnabled();
 
     /**
-        Returns true if logging at this level is enabled.
+        Returns true if logging at this level is enabled for the current thread.
 
         This function only returns @true if logging is globally enabled and if
         @a level is less than or equal to the maximal log level enabled for the
@@ -858,6 +884,8 @@ public:
         To suppress logging use a new instance of wxLogNull not @NULL.  If the
         active log target is set to @NULL a new default log target will be
         created when logging occurs.
+
+        @see SetThreadActiveTarget()
     */
     static wxLog* SetActiveTarget(wxLog* logtarget);
 
@@ -898,6 +926,32 @@ public:
     */
     static void SetRepetitionCounting(bool repetCounting = true);
 
+    /**
+        Sets a thread-specific log target.
+
+        The log target passed to this function will be used for all messages
+        logged by the current thread using the usual wxLog functions. This
+        shouldn't be called from the main thread which never uses a thread-
+        specific log target but can be used for the other threads to handle
+        thread logging completely separately; instead of buffering thread log
+        messages in the main thread logger.
+
+        Notice that unlike for SetActiveTarget(), wxWidgets does not destroy
+        the thread-specific log targets when the thread terminates so doing
+        this is your responsibility.
+
+        This method is only available if @c wxUSE_THREADS is 1, i.e. wxWidgets
+        was compiled with threads support.
+
+        @param logger
+            The new thread-specific log target, possibly @NULL.
+        @return
+            The previous thread-specific log target, initially @NULL.
+
+        @since 2.9.1
+     */
+    static wxLog *SetThreadActiveTarget(wxLog *logger);
+
     /**
         Sets the timestamp format prepended by the default log targets to all
         messages. The string may contain any normal characters as well as %
@@ -1208,6 +1262,13 @@ void wxVLogError(const char* formatString, va_list argPtr);
 /** @addtogroup group_funcmacro_log */
 //@{
 /**
+    Log a message at wxLOG_Trace log level.
+
+    Notice that the use of trace masks is not recommended any more as setting
+    the log components (please see @ref overview_log_enable) provides a way to
+    do the same thing for log messages of any level, and not just the tracing
+    ones.
+
     Like wxLogDebug(), trace functions only do something in debug builds and
     expand to nothing in the release one. The reason for making it a separate
     function is that usually there are a lot of trace messages, so it might
@@ -1347,3 +1408,24 @@ void wxLogSysError(const char* formatString, ... );
 void wxVLogSysError(const char* formatString, va_list argPtr);
 //@}
 
+/** @addtogroup group_funcmacro_debug */
+//@{
+
+/**
+    @def wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
+
+    Use this macro to disable logging at debug and trace levels in release
+    build when not using IMPLEMENT_APP().
+
+    @see wxDISABLE_DEBUG_SUPPORT(),
+         wxDISABLE_ASSERTS_IN_RELEASE_BUILD(),
+         @ref overview_debugging
+
+    @since 2.9.1
+
+    @header{wx/log.h}
+ */
+#define wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
+
+//@}
+