X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ba3af1010d452862c384beba48b8dfb8de45c908..8bd410eb8082d9e009ece7cc279faa5f73ea1f5e:/interface/wx/log.h diff --git a/interface/wx/log.h b/interface/wx/log.h index 4492e375fd..04f57638d4 100644 --- a/interface/wx/log.h +++ b/interface/wx/log.h @@ -37,8 +37,23 @@ typedef unsigned long wxLogLevel; /** Information about a log record (unit of the log output). */ -struct wxLogRecordInfo +class wxLogRecordInfo { +public: + /// The name of the file where this log message was generated. + const char *filename; + + /// The line number at which this log message was generated. + int line; + + /** + The name of the function where the log record was generated. + + This field may be @NULL if the compiler doesn't support @c __FUNCTION__ + (but most modern compilers do). + */ + const char *func; + /// Time when the log message was generated. time_t timestamp; @@ -587,19 +602,23 @@ public: @section log_derivingyours Deriving your own log target - There are two functions which must be implemented by any derived class to - actually process the log messages: DoLog() and DoLogString(). - The second function receives a string which just has to be output in some way - and the easiest way to write a new log target is to override just this function - in the derived class. + There are several methods which may be overridden in the derived class to + customize log messages handling: DoLogRecord(), DoLogTextAtLevel() and + DoLogText(). - If more control over the output format is needed, then the first function must - be overridden which 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). + 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, @@ -609,13 +628,16 @@ public: Flush() shows them all and clears the buffer contents. This function doesn't do anything if the buffer is already empty. - See also: - @li Flush() - @li FlushActive() + @see FlushActive() @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). @@ -727,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() @@ -739,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(); @@ -808,14 +851,17 @@ 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 - this level is less than or equal to the global log level value. + @a level is less than or equal to the maximal log level enabled for the + given @a component. - @see IsEnabled(), SetLogLevel(), GetLogLevel() + @see IsEnabled(), SetLogLevel(), GetLogLevel(), SetComponentLevel() + + @since 2.9.1 */ - static bool IsLevelEnabled(wxLogLevel level); + static bool IsLevelEnabled(wxLogLevel level, wxString component); /** Remove the @a mask from the list of allowed masks for @@ -838,12 +884,38 @@ 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); + /** + Sets the log level for the given component. + + For example, to disable all but error messages from wxWidgets network + classes you may use + @code + wxLog::SetComponentLevel("wx/net", wxLOG_Error); + @endcode + + SetLogLevel() may be used to set the global log level. + + @param component + Non-empty component name, possibly using slashes (@c /) to separate + it into several parts. + @param level + Maximal level of log messages from this component which will be + handled instead of being simply discarded. + + @since 2.9.1 + */ + static void SetComponentLevel(const wxString& component, wxLogLevel level); + /** Specifies that log messages with level greater (numerically) than @a logLevel should be ignored and not sent to the active log target. + + @see SetComponentLevel() */ static void SetLogLevel(wxLogLevel logLevel); @@ -854,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 % @@ -1164,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 @@ -1303,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() + +//@} +