diff --git a/interface/log.h b/interface/log.h index 3292edb5f8..e1f65501cb 100644 --- a/interface/log.h +++ b/interface/log.h @@ -373,6 +373,115 @@ public: See @ref overview_wxlogoverview "log overview" for the descriptions of wxWidgets logging facilities. + @section overview_wxLog_Trace_Masks 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. 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). + 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 also: + @li Flush() + @li FlushActive() + + @section overview_wxLog_Trace_Masks Using trace masks + + The functions below allow some limited customization of wxLog behaviour + without writing a new log target class (which, aside of 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 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. + 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, + + @begincode + 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 + + @begincode + wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" ); + @endcode + + will log the message if it was preceded by + + @begincode + wxLog::AddTraceMask( wxTRACE_OleCalls); + @endcode + + Using string masks is simpler and allows 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 + 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 disables timestamping of the messages completely. + @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. 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() + + @section overview_wxLog_Target Manipulating the log target + + The functions in this section work with and manipulate the active log + target. The OnLog() is called by the @e wxLogXXX() functions + and invokes the DoLog() of the active log target if any. + 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 OnLog() + @li GetActiveTarget() + @li SetActiveTarget() + @li DontCreateOnDemand() + @li Suspend() + @li Resume() + @library{wxcore} @category{logging} @@ -397,75 +506,6 @@ public: */ static void ClearTraceMasks(); - /** - The functions below allow some limited customization of wxLog behaviour - without writing a new log target class (which, aside of 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 settings of - the (application global) @e trace mask. There are two ways to specify it: - either by using SetTraceMask() and - GetTraceMask() and using - wxLogTrace() which takes an integer mask or by using - AddTraceMask() for string trace masks. - 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, - - will do something only if the current trace mask contains both - @c wxTraceRefCount and @c wxTraceOle, but - - will log the message if it was preceded by - - Using string masks is simpler and allows 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 - 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 disables timestamping of the messages completely. - @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. - AddTraceMask() - - RemoveTraceMask() - - ClearTraceMasks() - - GetTraceMasks() - - IsAllowedTraceMask() - - SetVerbose() - - GetVerbose() - - SetTimestamp() - - GetTimestamp() - - SetTraceMask() - - GetTraceMask() - - SetRepetitionCounting() - - GetRepetitionCounting() */ @@ -554,34 +594,11 @@ public: */ static bool GetVerbose(); - /** - The functions in this section work with and manipulate the active log target. - The OnLog() is called by the @e wxLogXXX() functions - and invokes the DoLog() of the active log target if any. - 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. - OnLog() - - GetActiveTarget() - - SetActiveTarget() - - DontCreateOnDemand() - - Suspend() - - Resume() - */ - - /** Returns @true if the @a mask is one of allowed masks for wxLogTrace(). - See also: AddTraceMask(), - RemoveTraceMask() + + See also: AddTraceMask(), RemoveTraceMask() */ static bool IsAllowedTraceMask(const wxString& mask);