/////////////////////////////////////////////////////////////////////////////
// Name: log.h
-// Purpose: interface of wxLogWindow
+// Purpose: interface of wxLog* classes
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
@true to show the frame initially (default), otherwise
Show() must be called later.
@param passToOld
- @true to process the log messages normally in addition to
- logging them in the log frame (default), @false to only log them in the
- log frame.
+ @true to process the log messages normally in addition to logging them
+ in the log frame (default), @false to only log them in the log frame.
+ Note that if no targets were set using wxLog::SetActiveTarget() then
+ wxLogWindow simply becomes the active one and messages won't be passed
+ to other targets.
*/
wxLogWindow(wxWindow* pParent, const wxString& szTitle, bool show = true,
bool passToOld = true);
/**
@class wxLog
- wxLog class defines the interface for the @e log targets used by wxWidgets
+ wxLog class defines the interface for the <em>log targets</em> used by wxWidgets
logging functions as explained in the @ref overview_log.
+
The only situations when you need to directly use this class is when you want
to derive your own log target because the existing ones don't satisfy your
- needs. Another case is if you wish to customize the behaviour of the standard
- logging classes (all of which respect the wxLog settings): for example, set
- which trace messages are logged and which are not or change (or even remove
- completely) the timestamp on the messages.
+ needs.
- Otherwise, it is completely hidden behind the @e wxLogXXX() functions and
- you may not even know about its existence.
+ Otherwise, it is completely hidden behind the @ref group_funcmacro_log "wxLogXXX() functions"
+ and you may not even know about its existence.
@note For console-mode applications, the default target is wxLogStderr, so
that all @e wxLogXXX() functions print on @c stderr when @c wxUSE_GUI = 0.
-
- @section log_derivingyours Deriving your own log target
-
- There are several methods which may be overridden in the derived class to
- customize log messages handling: DoLogRecord(), DoLogTextAtLevel() and
- DoLogText().
-
- The last method is the simplest one: you should override it if you simply
- want to redirect the log output elsewhere, without taking into account the
- level of the message. If you do want to handle messages of different levels
- differently, then you should override DoLogTextAtLevel().
-
- Finally, if more control over the output format is needed, then the first
- function must be overridden as it allows to construct custom messages
- depending on the log level or even do completely different things depending
- on the message severity (for example, throw away all messages except
- warnings and errors, show warnings on the screen and forward the error
- messages to the user's (or programmer's) cell phone -- maybe depending on
- whether the timestamp tells us if it is day or night in the current time
- zone).
-
- There also functions to support message buffering. Why are they needed?
- Some of wxLog implementations, most notably the standard wxLogGui class,
- buffer the messages (for example, to avoid showing the user a zillion of modal
- message boxes one after another -- which would be really annoying).
-
- Flush() shows them all and clears the buffer contents.
- This function doesn't do anything if the buffer is already empty.
-
- @see FlushActive()
-
-
- @section log_tracemasks Using trace masks
-
- 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).
- The verbose messages are the trace messages which are not disabled in the
- release mode and are generated by wxLogVerbose().
- They are not normally shown to the user because they present little interest,
- 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 currently
- enabled trace masks: if AddTraceMask() was called for the mask of the given
- message, it will be logged, otherwise nothing happens.
-
- For example,
- @code
- wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" );
- @endcode
-
- will log the message if it was preceded by:
-
- @code
- wxLog::AddTraceMask( wxTRACE_OleCalls);
- @endcode
-
- The standard trace masks are given in wxLogTrace() documentation.
-
- Finally, the @e wxLog::DoLog() function automatically prepends a time stamp
- to all the messages. The format of the time stamp may be changed: it can be
- any string with % specifications fully described in the documentation of the
- standard @e strftime() function. For example, the default format is
- "[%d/%b/%y %H:%M:%S] " which gives something like "[17/Sep/98 22:10:16] "
- (without quotes) for the current date. Setting an empty string as the time
- format or calling the shortcut wxLog::DisableTimestamp(), disables timestamping
- of the messages completely.
-
- See also
- @li AddTraceMask()
- @li RemoveTraceMask()
- @li ClearTraceMasks()
- @li GetTraceMasks()
- @li IsAllowedTraceMask()
- @li SetVerbose()
- @li GetVerbose()
- @li SetTimestamp()
- @li GetTimestamp()
- @li SetTraceMask()
- @li GetTraceMask()
- @li SetRepetitionCounting()
- @li GetRepetitionCounting()
-
- @note
- Timestamping is disabled for Visual C++ users in debug builds by
- default because otherwise it would be impossible to directly go to the line
- from which the log message was generated by simply clicking in the debugger
- window on the corresponding error message. If you wish to enable it, please
- use SetTimestamp() explicitly.
-
-
- @section log_target Manipulating the log target
-
- The functions in this section work with and manipulate the active log
- target.
-
- Get/Set methods are used to install/query the current active target and,
- finally, DontCreateOnDemand() disables the automatic creation of a standard
- log target if none actually exists. It is only useful when the application
- is terminating and shouldn't be used in other situations because it may
- easily lead to a loss of messages.
-
- See also:
- @li GetActiveTarget()
- @li SetActiveTarget()
- @li DontCreateOnDemand()
- @li Suspend()
- @li Resume()
-
-
@library{wxcore}
@category{logging}
- @see @ref overview_log
+ @see @ref overview_log, @ref group_funcmacro_log "wxLogXXX() functions"
*/
class wxLog
{
public:
+ /**
+ @name Trace mask functions
+ */
+ //@{
+
/**
Add the @a mask to the list of allowed masks for wxLogTrace().
static void ClearTraceMasks();
/**
- Instructs wxLog to not create new log targets on the fly if there is none
- currently. (Almost) for internal use only: it is supposed to be called by the
- application shutdown code.
+ Returns the currently allowed list of string trace masks.
- Note that this function also calls ClearTraceMasks().
+ @see AddTraceMask().
*/
- static void DontCreateOnDemand();
+ static const wxArrayString& GetTraceMasks();
/**
- Globally enable or disable logging.
+ Returns @true if the @a mask is one of allowed masks for wxLogTrace().
- Calling this function with @false argument disables all log messages.
+ See also: AddTraceMask(), RemoveTraceMask()
+ */
+ static bool IsAllowedTraceMask(const wxString& mask);
+
+ /**
+ Remove the @a mask from the list of allowed masks for
+ wxLogTrace().
+
+ @see AddTraceMask()
+ */
+ static void RemoveTraceMask(const wxString& mask);
+
+ //@}
- @see wxLogNull, IsEnabled()
- @return
- The old state, i.e. @true if logging was previously enabled and
- @false if it was disabled.
- */
- static bool EnableLogging(bool enable = true);
/**
- Shows all the messages currently in buffer and clears it.
- If the buffer is already empty, nothing happens.
+ @name Log target functions
*/
- virtual void Flush();
-
+ //@{
+
/**
- Flushes the current log target if any, does nothing if there is none.
+ Instructs wxLog to not create new log targets on the fly if there is none
+ currently (see GetActiveTarget()).
+
+ (Almost) for internal use only: it is supposed to be called by the
+ application shutdown code (where you don't want the log target to be
+ automatically created anymore).
- @see Flush()
+ Note that this function also calls ClearTraceMasks().
*/
- static void FlushActive();
+ static void DontCreateOnDemand();
/**
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();
/**
- Returns the current log level limit.
+ Sets the specified log target as the active one.
- All messages at levels strictly greater than the value returned by this
- function are not logged at all.
+ Returns the pointer to the previous active log target (may be @NULL).
+ 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 SetLogLevel(), IsLevelEnabled()
+ @see SetThreadActiveTarget()
*/
- static wxLogLevel GetLogLevel();
+ static wxLog* SetActiveTarget(wxLog* logtarget);
/**
- Returns whether the repetition counting mode is enabled.
- */
- static bool GetRepetitionCounting();
+ Sets a thread-specific log target.
- /**
- Returns the current timestamp format string.
- */
- static const wxString& GetTimestamp();
+ 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.
- /**
- @deprecated
- Returns the current trace mask, see Customization() section for details.
- */
- static wxTraceMask GetTraceMask();
+ 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);
+
/**
- Returns the currently allowed list of string trace masks.
+ Flushes the current log target if any, does nothing if there is none.
- @see AddTraceMask().
+ 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 const wxArrayString& GetTraceMasks();
-
+ static void FlushActive();
+
/**
- Returns whether the verbose mode is currently active.
+ Resumes logging previously suspended by a call to Suspend().
+ All messages logged in the meanwhile will be flushed soon.
*/
- static bool GetVerbose();
+ static void Resume();
/**
- Returns @true if the @a mask is one of allowed masks for wxLogTrace().
+ Suspends the logging until Resume() is called.
- See also: AddTraceMask(), RemoveTraceMask()
+ Note that the latter must be called the same number of times as the former
+ to undo it, i.e. if you call Suspend() twice you must call Resume() twice as well.
+
+ Note that suspending the logging means that the log sink won't be be flushed
+ periodically, it doesn't have any effect if the current log target does the
+ logging immediately without waiting for Flush() to be called (the standard
+ GUI log target only shows the log dialog when it is flushed, so Suspend()
+ works as expected with it).
+
+ @see Resume(), wxLogNull
*/
- static bool IsAllowedTraceMask(const wxString& mask);
+ static void Suspend();
+
+ //@}
+
+
/**
- Returns true if logging is enabled at all now.
+ @name Log level functions
+ */
+ //@{
+
+ /**
+ Returns the current log level limit.
- @see IsLevelEnabled(), EnableLogging()
- */
- static bool IsEnabled();
+ All messages at levels strictly greater than the value returned by this
+ function are not logged at all.
+ @see SetLogLevel(), IsLevelEnabled()
+ */
+ static wxLogLevel GetLogLevel();
+
/**
- 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
*/
static bool IsLevelEnabled(wxLogLevel level, wxString component);
- /**
- Remove the @a mask from the list of allowed masks for
- wxLogTrace().
-
- @see AddTraceMask()
- */
- static void RemoveTraceMask(const wxString& mask);
-
- /**
- Resumes logging previously suspended by a call to Suspend().
- All messages logged in the meanwhile will be flushed soon.
- */
- static void Resume();
-
- /**
- Sets the specified log target as the active one.
-
- Returns the pointer to the previous active log target (may be @NULL).
- 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.
- */
- static wxLog* SetActiveTarget(wxLog* logtarget);
-
/**
Sets the log level for the given component.
@see SetComponentLevel()
*/
static void SetLogLevel(wxLogLevel logLevel);
+
+ //@}
+
+
+
+ /**
+ @name Enable/disable features functions
+ */
+ //@{
+
+ /**
+ Globally enable or disable logging.
+
+ Calling this function with @false argument disables all log messages
+ for the current thread.
+
+ @see wxLogNull, IsEnabled()
+
+ @return
+ The old state, i.e. @true if logging was previously enabled and
+ @false if it was disabled.
+ */
+ static bool EnableLogging(bool enable = true);
+
+ /**
+ Returns true if logging is enabled at all now.
+
+ @see IsLevelEnabled(), EnableLogging()
+ */
+ static bool IsEnabled();
+
+ /**
+ Returns whether the repetition counting mode is enabled.
+ */
+ static bool GetRepetitionCounting();
/**
Enables logging mode in which a log message is logged once, and in case exactly
repetitions is logged.
*/
static void SetRepetitionCounting(bool repetCounting = true);
+
+ /**
+ Returns the current timestamp format string.
+ */
+ static const wxString& GetTimestamp();
/**
Sets the timestamp format prepended by the default log targets to all
@since 2.9.0
*/
static void DisableTimestamp();
-
+
/**
- @deprecated
- Sets the trace mask, see @ref log_tracemasks section for details.
+ Returns whether the verbose mode is currently active.
*/
- static void SetTraceMask(wxTraceMask mask);
+ static bool GetVerbose();
/**
Activates or deactivates verbose mode in which the verbose messages are
logged as the normal ones instead of being silently dropped.
+
+ The verbose messages are the trace messages which are not disabled in the
+ release mode and are generated by wxLogVerbose().
+
+ @see @ref overview_log
*/
static void SetVerbose(bool verbose = true);
+
+ //@}
+
+
/**
- Suspends the logging until Resume() is called.
-
- Note that the latter must be called the same number of times as the former
- to undo it, i.e. if you call Suspend() twice you must call Resume() twice as well.
-
- Note that suspending the logging means that the log sink won't be be flushed
- periodically, it doesn't have any effect if the current log target does the
- logging immediately without waiting for Flush() to be called (the standard
- GUI log target only shows the log dialog when it is flushed, so Suspend()
- works as expected with it).
+ Some of wxLog implementations, most notably the standard wxLogGui class,
+ buffer the messages (for example, to avoid showing the user a zillion of modal
+ message boxes one after another -- which would be really annoying).
+ This function shows them all and clears the buffer contents.
+ If the buffer is already empty, nothing happens.
- @see Resume(), wxLogNull
+ If you override this method in a derived class, call the base class
+ version first, before doing anything else.
*/
- static void Suspend();
-
+ virtual void Flush();
+
/**
Log the given record.
/** @addtogroup group_funcmacro_log */
//@{
/**
- 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
- make sense to separate them from other debug messages.
+ Log a message at @c wxLOG_Trace log level (see ::wxLogLevelValues enum).
- 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().
+ 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.
- @header{wx/log.h}
-*/
-void wxLogTrace(const char *mask, const char* formatString, ... );
-void wxVLogTrace(const char *mask, const char* formatString, va_list argPtr);
-//@}
-
-/** @addtogroup group_funcmacro_log */
-//@{
-/**
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
make sense to separate them from other debug messages.
- In this version of wxLogTrace(), trace messages can be separated into
- different categories and calls using this function only log the message if
- the given @a mask is currently enabled in wxLog. This lets you selectively
- trace only some operations and not others by enabling the desired trace
- masks with wxLog::AddTraceMask() or by setting the
+ Trace messages can be separated into different categories; these functions in facts
+ only log the message if the given @a mask is currently enabled in wxLog.
+ This lets you selectively trace only some operations and not others by enabling the
+ desired trace masks with wxLog::AddTraceMask() or by setting the
@ref overview_envvars "@c WXTRACE environment variable".
The predefined string trace masks used by wxWidgets are:
@itemdef{ wxTRACE_OleCalls, Trace OLE method calls (Win32 only) }
@endDefList
- @note Since both the mask and the format string are strings, this might
- lead to function signature confusion in some cases: if you intend to
- call the format string only version of wxLogTrace(), add a "%s"
- format string parameter and then supply a second string parameter for
- that "%s", the string mask version of wxLogTrace() will erroneously
- get called instead, since you are supplying two string parameters to
- the function. In this case you'll unfortunately have to avoid having
- two leading string parameters, e.g. by adding a bogus integer (with
- its "%d" format string).
-
@header{wx/log.h}
*/
void wxLogTrace(const char* mask, const char* formatString, ... );
-void wxVLogTrace(const char* mask,
- const char* formatString,
- va_list argPtr);
+void wxVLogTrace(const char* mask, const char* formatString, va_list argPtr);
//@}
/** @addtogroup group_funcmacro_log */
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 wxIMPLEMENT_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