Formatting
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@54296 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Robert Roebling
parent
8b9aed29b7
commit
5bc128d67f
205
interface/log.h
205
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);
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user