4a20e7568e
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@10966 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
461 lines
17 KiB
TeX
461 lines
17 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Name: log.tex
|
|
%% Purpose: wxLog and related classes documentation
|
|
%% Author: Vadim Zeitlin
|
|
%% Modified by:
|
|
%% Created: some time ago
|
|
%% RCS-ID: $Id$
|
|
%% Copyright: (c) 1997-2001 Vadim Zeitlin
|
|
%% License: wxWindows license
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\section{\class{wxLog}}\label{wxlog}
|
|
|
|
wxLog class defines the interface for the {\it log targets} used by wxWindows
|
|
logging functions as explained in the \helpref{wxLog overview}{wxlogoverview}.
|
|
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.
|
|
|
|
Otherwise, it is completely hidden behind the {\it wxLogXXX()} functions and
|
|
you may not even know about its existence.
|
|
|
|
See \helpref{log overview}{wxlogoverview} for the descriptions of wxWindows
|
|
logging facilities.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
No base class
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/log.h>
|
|
|
|
\latexignore{\rtfignore{\wxheading{Function groups}}}
|
|
|
|
\membersection{Static functions}
|
|
|
|
The functions in this section work with and manipulate the active log target.
|
|
The \helpref{OnLog()}{wxlogonlog} is called by the {\it wxLogXXX()} functions
|
|
and invokes the \helpref{DoLog()}{wxlogdolog} of the active log target if any.
|
|
Get/Set methods are used to install/query the current active target and,
|
|
finally, \helpref{DontCreateOnDemand()}{wxlogdontcreateondemand} 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.
|
|
|
|
\helpref{OnLog}{wxlogonlog}\\
|
|
\helpref{GetActiveTarget}{wxloggetactivetarget}\\
|
|
\helpref{SetActiveTarget}{wxlogsetactivetarget}\\
|
|
\helpref{DontCreateOnDemand}{wxlogdontcreateondemand}\\
|
|
\helpref{Suspend}{wxlogsuspend}\\
|
|
\helpref{Resume}{wxlogresume}
|
|
|
|
\membersection{Logging functions}
|
|
|
|
There are two functions which must be implemented by any derived class to
|
|
actually process the log messages: \helpref{DoLog}{wxlogdolog} and
|
|
\helpref{DoLogString}{wxlogdologstring}. 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).
|
|
\helpref{Flush()}{wxlogflush} shows them all and clears the buffer contents.
|
|
Although this function doesn't do anything if the buffer is already empty,
|
|
\helpref{HasPendingMessages()}{wxloghaspendingmessages} is also provided which
|
|
allows to explicitly verify it.
|
|
|
|
\helpref{Flush}{wxlogflush}\\
|
|
\helpref{FlushActive}{wxlogflushactive}\\
|
|
\helpref{HasPendingMessages}{wxloghaspendingmessages}
|
|
|
|
\membersection{Customization}\label{wxlogcustomization}
|
|
|
|
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 \helpref{wxLogVerbose}{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) {\it trace mask}. There are two ways to specify it:
|
|
either by using \helpref{SetTraceMask}{wxlogsettracemask} and
|
|
\helpref{GetTraceMask}{wxloggettracemask} and using
|
|
\helpref{wxLogTrace}{wxlogtrace} which takes an integer mask or by using
|
|
\helpref{AddTraceMask}{wxlogaddtracemask} 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,
|
|
|
|
\begin{verbatim}
|
|
// wxTraceOleCalls is one of standard bit masks
|
|
wxLogTrace(wxTraceRefCount | wxTraceOleCalls, "Active object ref count: %d", nRef);
|
|
\end{verbatim}
|
|
will do something only if the current trace mask contains both
|
|
{\tt wxTraceRefCount} and {\tt wxTraceOle}, but
|
|
|
|
\begin{verbatim}
|
|
// wxTRACE_OleCalls is one of standard string masks
|
|
wxLogTrace(wxTRACE_OleCalls, "IFoo::Bar() called");
|
|
\end{verbatim}
|
|
|
|
will log the message if it was preceded by
|
|
|
|
\begin{verbatim}
|
|
wxLog::AddTraceMask(wxTRACE_OleCalls);
|
|
\end{verbatim}
|
|
|
|
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 \helpref{wxLogTrace}{wxlogtrace}
|
|
documentation.
|
|
|
|
Finally, the {\it 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 \% specificators fully described in the documentation of the
|
|
standard {\it 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.
|
|
|
|
{\bf NB:} 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
|
|
\helpref{SetTimestamp}{wxlogsettimestamp} explicitly.
|
|
|
|
\helpref{AddTraceMask}{wxlogaddtracemask}\\
|
|
\helpref{RemoveTraceMask}{wxlogremovetracemask}\\
|
|
\helpref{ClearTraceMasks}{wxlogcleartracemasks}\\
|
|
\helpref{IsAllowedTraceMask}{wxlogisallowedtracemask}\\
|
|
\helpref{SetVerbose}{wxlogsetverbose}\\
|
|
\helpref{GetVerbose}{wxloggetverbose}\\
|
|
\helpref{SetTimestamp}{wxlogsettimestamp}\\
|
|
\helpref{GetTimestamp}{wxloggettimestamp}\\
|
|
\helpref{SetTraceMask}{wxlogsettracemask}\\
|
|
\helpref{GetTraceMask}{wxloggettracemask}
|
|
|
|
%%%%% MEMBERS HERE %%%%%
|
|
\helponly{\insertatlevel{2}{
|
|
|
|
\wxheading{Members}
|
|
|
|
}}
|
|
|
|
\membersection{wxLog::AddTraceMask}\label{wxlogaddtracemask}
|
|
|
|
\func{static void}{AddTraceMask}{\param{const wxString\& }{mask}}
|
|
|
|
Add the {\it mask} to the list of allowed masks for
|
|
\helpref{wxLogTrace}{wxlogtrace}.
|
|
|
|
See also: \helpref{RemoveTraceMask}{wxlogremovetracemask}
|
|
|
|
\membersection{wxLog::ClearTraceMasks}\label{wxlogcleartracemasks}
|
|
|
|
\func{static void}{ClearTraceMasks}{\void}
|
|
|
|
Removes all trace masks previously set with
|
|
\helpref{AddTraceMask}{wxlogaddtracemask}.
|
|
|
|
See also: \helpref{RemoveTraceMask}{wxlogremovetracemask}
|
|
|
|
\membersection{wxLog::OnLog}\label{wxlogonlog}
|
|
|
|
\func{static void}{OnLog}{\param{wxLogLevel }{ level}, \param{const char * }{ message}}
|
|
|
|
Forwards the message at specified level to the {\it DoLog()} function of the
|
|
active log target if there is any, does nothing otherwise.
|
|
|
|
\membersection{wxLog::GetActiveTarget}\label{wxloggetactivetarget}
|
|
|
|
\func{static wxLog *}{GetActiveTarget}{\void}
|
|
|
|
Returns the pointer to the active log target (may be NULL).
|
|
|
|
\membersection{wxLog::SetActiveTarget}\label{wxlogsetactivetarget}
|
|
|
|
\func{static wxLog *}{SetActiveTarget}{\param{wxLog * }{ logtarget}}
|
|
|
|
Sets the specified log target as the active one. Returns the pointer to the
|
|
previous active log target (may be NULL).
|
|
|
|
\membersection{wxLog::Suspend}\label{wxlogsuspend}
|
|
|
|
\func{static void}{Suspend}{\void}
|
|
|
|
Suspends the logging until \helpref{Resume}{wxlogresume} 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 \helpref{Flush}{wxlogflush} to be
|
|
called (the standard GUI log target only shows the log dialog when it is
|
|
flushed, so Suspend() works as expected with it).
|
|
|
|
\wxheading{See also:}
|
|
|
|
\helpref{Resume}{wxlogresume},\\
|
|
\helpref{wxLogNull}{wxlogoverview}
|
|
|
|
\membersection{wxLog::Resume}\label{wxlogresume}
|
|
|
|
\func{static void}{Resume}{\void}
|
|
|
|
Resumes logging previously suspended by a call to
|
|
\helpref{Suspend}{wxlogsuspend}. All messages logged in the meanwhile will be
|
|
flushed soon.
|
|
|
|
\membersection{wxLog::DoLog}\label{wxlogdolog}
|
|
|
|
\func{virtual void}{DoLog}{\param{wxLogLevel }{level}, \param{const wxChar }{*msg}, \param{time\_t }{timestamp}}
|
|
|
|
Called to process the message of the specified severity. {\it msg} is the text
|
|
of the message as specified in the call of {\it wxLogXXX()} function which
|
|
generated it and {\it timestamp} is the moment when the message was generated.
|
|
|
|
The base class version prepends the timestamp to the message, adds a prefix
|
|
corresponding to the log level and then calls
|
|
\helpref{DoLogString}{wxlogdologstring} with the resulting string.
|
|
|
|
\membersection{wxLog::DoLogString}\label{wxlogdologstring}
|
|
|
|
\func{virtual void}{DoLogString}{\param{const wxChar }{*msg}, \param{time\_t }{timestamp}}
|
|
|
|
Called to log the specified string. The timestamp is already included into the
|
|
string but still passed to this function.
|
|
|
|
A simple implementation may just send the string to {\tt stdout} or, better,
|
|
{\tt stderr}.
|
|
|
|
\membersection{wxLog::DontCreateOnDemand}\label{wxlogdontcreateondemand}
|
|
|
|
\func{static void}{DontCreateOnDemand}{\void}
|
|
|
|
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.
|
|
|
|
Note that this function also calls
|
|
\helpref{ClearTraceMasks}{wxlogcleartracemasks}.
|
|
|
|
\membersection{wxLog::Flush}\label{wxlogflush}
|
|
|
|
\func{virtual void}{Flush}{\void}
|
|
|
|
Shows all the messages currently in buffer and clears it. If the buffer
|
|
is already empty, nothing happens.
|
|
|
|
\membersection{wxLog::FlushActive}\label{wxlogflushactive}
|
|
|
|
\func{static void}{FlushActive}{\void}
|
|
|
|
Flushes the current log target if any, does nothing if there is none.
|
|
|
|
See also:
|
|
|
|
\helpref{Flush}{wxlogflush}
|
|
|
|
\membersection{wxLog::HasPendingMessages}\label{wxloghaspendingmessages}
|
|
|
|
\constfunc{bool}{HasPendingMessages}{\void}
|
|
|
|
Returns true if there are any messages in the buffer (not yet shown to the
|
|
user). (Almost) for internal use only.
|
|
|
|
\membersection{wxLog::SetVerbose}\label{wxlogsetverbose}
|
|
|
|
\func{static void}{SetVerbose}{\param{bool }{ verbose = TRUE}}
|
|
|
|
Activates or desactivates verbose mode in which the verbose messages are
|
|
logged as the normal ones instead of being silently dropped.
|
|
|
|
\membersection{wxLog::GetVerbose}\label{wxloggetverbose}
|
|
|
|
\func{static bool}{GetVerbose}{\void}
|
|
|
|
Returns whether the verbose mode is currently active.
|
|
|
|
\membersection{wxLog::SetTimestamp}\label{wxlogsettimestamp}
|
|
|
|
\func{void}{SetTimestamp}{\param{const char * }{ format}}
|
|
|
|
Sets the timestamp format prepended by the default log targets to all
|
|
messages. The string may contain any normal characters as well as \%
|
|
prefixed format specificators, see {\it strftime()} manual for details.
|
|
Passing a NULL value (not empty string) to this function disables message timestamping.
|
|
|
|
\membersection{wxLog::GetTimestamp}\label{wxloggettimestamp}
|
|
|
|
\constfunc{const char *}{GetTimestamp}{\void}
|
|
|
|
Returns the current timestamp format string.
|
|
|
|
\membersection{wxLog::SetTraceMask}\label{wxlogsettracemask}
|
|
|
|
\func{static void}{SetTraceMask}{\param{wxTraceMask }{ mask}}
|
|
|
|
Sets the trace mask, see \helpref{Customization}{wxlogcustomization}
|
|
section for details.
|
|
|
|
\membersection{wxLog::GetTraceMask}\label{wxloggettracemask}
|
|
|
|
Returns the current trace mask, see \helpref{Customization}{wxlogcustomization} section
|
|
for details.
|
|
|
|
\membersection{wxLog::IsAllowedTraceMask}\label{wxlogisallowedtracemask}
|
|
|
|
\func{static bool}{IsAllowedTraceMask}{\param{const wxChar *}{mask}}
|
|
|
|
Returns TRUE if the {\it mask} is one of allowed masks for
|
|
\helpref{wxLogTrace}{wxlogtrace}.
|
|
|
|
See also: \helpref{AddTraceMask}{wxlogaddtracemask},
|
|
\helpref{RemoveTraceMask}{wxlogremovetracemask}
|
|
|
|
\membersection{wxLog::RemoveTraceMask}\label{wxlogremovetracemask}
|
|
|
|
\func{static void}{RemoveTraceMask}{\param{const wxString\& }{mask}}
|
|
|
|
Remove the {\it mask} from the list of allowed masks for
|
|
\helpref{wxLogTrace}{wxlogtrace}.
|
|
|
|
See also: \helpref{AddTraceMask}{wxlogaddtracemask}
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogChain %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\section{\class{wxLogChain}}\label{wxlogchain}
|
|
|
|
This simple class allows to chain log sinks, that is to install a new sink but
|
|
keep passing log messages to the old one instead of replacing it completely as
|
|
\helpref{SetActiveTarget}{wxlogsetactivetarget} does.
|
|
|
|
It is especially useful when you want to divert the logs somewhere (for
|
|
example to a file or a log window) but also keep showing the error messages
|
|
using the standard dialogs as \helpref{wxLogGui}{wxloggui} does by default.
|
|
|
|
Example of usage:
|
|
|
|
\begin{verbatim}
|
|
wxLogChain *logChain = new wxLogChain(new wxLogStderr);
|
|
|
|
// all the log messages are sent to stderr and also processed as usually
|
|
...
|
|
|
|
delete logChain;
|
|
|
|
\end{verbatim}
|
|
|
|
\wxheading{Derived from}
|
|
|
|
\helpref{wxLog}{wxlog}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/log.h>
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxLogChain::wxLogChain}\label{wxlogchainwxlogchain}
|
|
|
|
\func{}{wxLogChain}{\param{wxLog *}{logger}}
|
|
|
|
Sets the specified {\tt logger} (which may be {\tt NULL}) as the default log
|
|
target but the log messages are also passed to the previous log target if any.
|
|
|
|
\membersection{wxLogChain::\destruct{wxLogChain}}
|
|
|
|
\func{}{\destruct{wxLogChain}}{\void}
|
|
|
|
Destroys the previous log target.
|
|
|
|
\membersection{wxLogChain::GetOldLog}\label{wxlogchaingetoldlog}
|
|
|
|
\constfunc{wxLog *}{GetOldLog}{\void}
|
|
|
|
Returns the pointer to the previously active log target (which may be {\tt
|
|
NULL}).
|
|
|
|
\membersection{wxLogChain::IsPassingMessages}\label{wxlogchainispassingmessages}
|
|
|
|
\constfunc{bool}{IsPassingMessages}{\void}
|
|
|
|
Returns {\tt TRUE} if the messages are passed to the previously active log
|
|
target (default) or {\tt FALSE} if \helpref{PassMessages}{wxlogchainpassmessages}
|
|
had been called.
|
|
|
|
\membersection{wxLogChain::PassMessages}\label{wxlogchainpassmessages}
|
|
|
|
\func{void}{PassMessages}{\param{bool }{passMessages}}
|
|
|
|
By default, the log messages are passed to the previously active log target.
|
|
Calling this function with {\tt FALSE} parameter disables this behaviour
|
|
(presumably temporarily, as you shouldn't use wxLogChain at all otherwise) and
|
|
it can be reenabled by calling it again with {\it passMessages} set to {\tt
|
|
TRUE}.
|
|
|
|
\membersection{wxLogChain::SetLog}\label{wxlogchainsetlog}
|
|
|
|
\func{void}{SetLog}{\param{wxLog *}{logger}}
|
|
|
|
Sets another log target to use (may be {\tt NULL}). The log target specified
|
|
in the \helpref{constructor}{wxlogchainwxlogchain} or in a previous call to
|
|
this function is deleted.
|
|
|
|
This doesn't change the old log target value (the one the messages are
|
|
forwarded to) which still remains the same as was active when wxLogChain
|
|
object was created.
|
|
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxLogChain %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\section{\class{wxLogPassThrough}}\label{wxlogpassthrough}
|
|
|
|
A special version of \helpref{wxLogChain}{wxlogchain} which uses itself as the
|
|
new log target. Maybe more clearly, it means that this is a log target which
|
|
forwards the log messages to the previously installed one in addition to
|
|
processing them itself.
|
|
|
|
Unlike \helpref{wxLogChain}{wxlogchain} which is usually used directly as is,
|
|
this class must be derived from to implement \helpref{DoLog}{wxlogdolog}
|
|
and/or \helpref{DoLogString}{wxlogdologstring} methods.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
\helpref{wxLogChain}{wxlogchain}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/log.h>
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxLogPassThrough::wxLogPassThrough}\label{wxlogpassthroughctor}
|
|
|
|
Default ctor installs this object as the current active log target.
|
|
|