+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% 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
\membersection{Static functions}
The functions in this section work with and manipulate the active log target.
-The {\it OnLog()} is called by the {\it wxLogXXX()} functions and invokes the
-{\it DoLog()} of the active log target if any. Get/Set methods are used to
-install/query the current active target and, finally, {\it
-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.
+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}
-
-\membersection{Message buffering}
-
-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). {\it Flush()} shows them all and clears the buffer
-contents. Although this function doesn't do anything if the buffer is already
-empty, {\it HasPendingMessages()} is also provided which allows to explicitly
-verify it.
+\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}{haspendingmessages}
+\helpref{HasPendingMessages}{wxloghaspendingmessages}
\membersection{Customization}\label{wxlogcustomization}
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}
\helpref{AddTraceMask}{wxlogaddtracemask}\\
\helpref{RemoveTraceMask}{wxlogremovetracemask}\\
+\helpref{ClearTraceMasks}{wxlogcleartracemasks}\\
\helpref{IsAllowedTraceMask}{wxlogisallowedtracemask}\\
\helpref{SetVerbose}{wxlogsetverbose}\\
\helpref{GetVerbose}{wxloggetverbose}\\
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}}
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.
+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}
\helpref{Flush}{wxlogflush}
-\membersection{wxLog::HasPendingMessages}\label{haspendingmessages}
+\membersection{wxLog::HasPendingMessages}\label{wxloghaspendingmessages}
\constfunc{bool}{HasPendingMessages}{\void}
\membersection{wxLog::SetVerbose}\label{wxlogsetverbose}
-\func{void}{SetVerbose}{\param{bool }{ verbose = TRUE}}
+\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}
-\constfunc{bool}{GetVerbose}{\void}
+\func{static bool}{GetVerbose}{\void}
Returns whether the verbose mode is currently active.
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.
+
projects / wxWidgets.git / blobdiff