@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).
/**
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()
/**
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();
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
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);
*/
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 %
/** @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
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()
+
+//@}
+
projects / wxWidgets.git / blobdiff